Skip to content

Commit b70dc62

Browse files
jp-ayyappanjp-ayyappan
authored
Merge branch 'main' into sdk-contributor-guidelines
2 parents a2e9b5b + 5ca594f commit b70dc62

33 files changed

+29874
-5223
lines changed

‎.github/workflows/vale.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: Vale
33
on:
44
pull_request:
55
branches:
6-
- main
6+
- disabled
77

88
jobs:
99
vale-check:

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
specs-processed/
2+
docs/OpenAPI-clients/
3+
docs/SDK-Samples/
4+
15
# Dependencies
26
/node_modules
37

‎.languagetool.yml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
language: en-US
2+
disabledRules: []
3+
enabledRules: []
4+
disabledCategories: []
5+
dictionary:
6+
- OpenTDF
7+
- SDKs
8+
# This helps LanguageTool understand Markdown format
9+
markup:
10+
- markdown
11+
# Skip code blocks and inline code
12+
skipPatterns:
13+
- '```[\s\S]*?```' # Skip fenced code blocks
14+
- '`[^`]*`' # Skip inline code

‎docs/components/core/authz.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: Authorization Configuration
3+
description: Learn about the standard authorization (AuthZ) configuration and role-based access control in the OpenTDF platform
4+
sidebar_position: 2
5+
---
6+
7+
# Standard Authorization (AuthZ) Configuration for opentdf Platform
8+
9+
The opentdf platform uses **Casbin** to manage authorization (AuthZ) for its routes, which are defined using **ConnectRPC**. This document outlines the standard AuthZ configuration, role mappings, and administrative responsibilities for managing and customizing the platform to meet specific security requirements.
10+
11+
## Default Authorization Roles and Policies
12+
13+
By default, the platform provides three role mappings (`admin`, `standard`, and `unknown`) and a concept of **public endpoints**. These roles are tied to the `realmsRole` claim of the OIDC token issued by the Keycloak Identity Provider.
14+
15+
### Role Mappings and Their Permissions
16+
17+
1. **`admin`**
18+
- **Description**: Administrators of the platform.
19+
- **Permissions**:
20+
- Perform all actions.
21+
- Modify and mutate policy data.
22+
- Access private and public endpoints.
23+
- **Requirements**: Must have a valid OIDC token with a claim mapping to the `admin` role.
24+
25+
2. **`standard`**
26+
- **Description**: Standard users of the platform.
27+
- **Permissions**:
28+
- Perform basic actions.
29+
- Cannot modify policy data.
30+
- Access private and public endpoints.
31+
- **Requirements**: Must have a valid OIDC token with a claim mapping to the `standard` role.
32+
33+
3. **`unknown`**
34+
- **Description**: Users with valid OIDC tokens who are not mappable into the platform's predefined roles.
35+
- **Permissions**:
36+
- Can only perform public functions.
37+
- Cannot access private endpoints.
38+
- **Requirements**: Must have a valid OIDC token, but no mapping exists for the `realmsRole` claim.
39+
40+
### Public Endpoints
41+
42+
- **Description**: Certain routes are designated as public endpoints and **bypass AuthZ entirely**.
43+
- **Use Case**: These routes are accessible to all users, regardless of their role or token validity.
44+
45+
## Responsibilities of Administrators
46+
47+
It is critical to note that the opentdf platform provides a **basic configuration** for authorization. Administrators are fully responsible for customizing and managing authorization policies to align with their organization's security posture. This includes:
48+
49+
1. **Configuring the Platform for Security Posture**:
50+
- Review and customize the default Casbin policy to meet organizational needs.
51+
- Ensure that sensitive routes are properly protected.
52+
53+
2. **Managing Role Mappings**:
54+
- Update and maintain the mappings for the `realmsRole` claim in Keycloak to ensure accurate role assignment.
55+
- Ensure that users are correctly categorized into `admin`, `standard`, or custom roles as required.
56+
57+
3. **Monitoring and Updating Policies**:
58+
- Regularly review policy files to ensure compliance with evolving security requirements.
59+
- Keep track of updates and changes in the Casbin model and policy files.
60+
61+
## Default Casbin Policy
62+
63+
The platform leverages Casbin to enforce role-based access control (RBAC). Below is an outline of the default policy:
64+
65+
### Default Role Mapping
66+
67+
- `admin` → Full permissions to all resources and actions.
68+
- `standard` → Limited permissions to basic resources and actions.
69+
- `unknown` → Only permitted to access public functions.
70+
71+
### Casbin Access Control Model
72+
73+
The Casbin model supports **extensibility** so that administrators can define custom access control logic to meet their specific needs. For example, administrators can override the default policy using custom mapping logic or additional claims.
74+
75+
## Example Configuration
76+
77+
Here is an example of how the `realmsRole` claim in Keycloak maps to Casbin roles:
78+
79+
```yaml
80+
server:
81+
auth:
82+
policy:
83+
csv: |
84+
p, role:admin, *, *, allow
85+
p, role:standard, /basic/*, GET|POST, allow
86+
p, role:unknown, /public/*, GET, allow
87+
g, opentdf-admin, role:admin
88+
g, opentdf-standard, role:standard
89+
```
90+
91+
## Key Takeaways
92+
93+
- The opentdf platform provides a basic AuthZ configuration as a starting point.
94+
- Administrators are responsible for ensuring the platform's configuration aligns with their security policies.
95+
- It is the organization's responsibility to manage role mappings and to ensure that the `realmsRole` claim in Keycloak is configured correctly.
96+
- By default, `admin`, `standard`, and `unknown` roles are provided, with respective permissions. Public endpoints bypass AuthZ entirely.
97+
98+
For more advanced configurations, refer to the [Casbin documentation](https://casbin.org/docs/syntax-for-models) for guidance on customizing policies and models.

‎docs/components/core/index.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Core Components
3+
description: Learn about the core components and fundamental services of the OpenTDF platform
4+
sidebar_position: 1
5+
---
6+
7+
# Core Components
8+
9+
The core components of the OpenTDF platform provide the fundamental building blocks for secure data access and control. These components implement the essential services and configurations that enable the platform's data-centric security capabilities.
10+
11+
## Key Components
12+
13+
### Authorization (AuthZ)
14+
15+
The standard authorization configuration manages access control using Casbin and ConnectRPC. It provides role-based access control through predefined roles (admin, standard, unknown) and public endpoints, integrating with the platform's OIDC token system.
16+
17+
### Service Registration and Configuration
18+
19+
Core services in the platform are designed to work together through standardized registration and configuration patterns. This includes:
20+
21+
- Service discovery and communication
22+
- Standard health checks and monitoring
23+
- Configuration management and validation
24+
- Security and authentication setup
25+
26+
### Platform Integration Points
27+
28+
The core components establish crucial integration points for:
29+
30+
- Identity Provider (IdP) integration
31+
- Key management and access control
32+
- Policy enforcement points
33+
- Service-to-service communication
34+
35+
## Purpose
36+
37+
The core components documentation provides essential information about:
38+
39+
- Standard configuration patterns
40+
- Service initialization and bootstrap processes
41+
- Security configurations and best practices
42+
- Integration guidelines for platform services
43+
44+
These components form the foundation of the OpenTDF platform, ensuring consistent behavior, security, and interoperability across all platform services.

‎docs/sdks/overview.mdx

Lines changed: 1 addition & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -6,40 +6,7 @@ sidebar_position: 1
66

77
OpenTDF supports native SDKs in the Go, Java and JavaScript languages.
88

9-
## Supported Features
10-
11-
| | Go | Java | C++ | JavaScript |
12-
| :------------------------- | -------- | -------- | -------- | ---------- |
13-
| **Lifecycle** | Beta | Alpha | Alpha | Alpha |
14-
| **Support**[^101] | Official | Official | Official | Official |
15-
| | | | | |
16-
| **Encrypt/Decrypt**[^103] | Stable | Unstable | Planned | Unstable |
17-
| - ZTDF[^110] | Stable | Unstable | Planned | Unstable |
18-
| - NanoTDF[^111] | Stable | Planned | Planned | Unstable |
19-
| - ABAC[^112] | Stable | Unstable | Planned | Unstable |
20-
| - Dissem[^113] | Unstable | Unstable | Planned | Unstable |
21-
| | | | | |
22-
| **Service APIs**[^105] | Stable | Stable | Planned | Planned |
23-
| - Authorization [^120] | | | | |
24-
| - Key Access Server [^121] | | | | |
25-
| - Policy: Attributes[^130] | | | | |
26-
27-
[^101]: Support is the level of support for the SDK (Official, Community).
28-
[^103]: Encrypt is the ability to encrypt data.
29-
[^105]: Service APIs are APIs that are provided by the library to interact with the service.
30-
31-
<!-- SDK Footnotes -->
32-
33-
[^110]: Support for the [Zero Trust Data Format](https://github.com/opentdf/spec/tree/main/schema/tdf) utilizing JSON manifests.
34-
[^111]: Support for the [Nano Trusted Data Format](https://github.com/opentdf/spec/tree/main/schema/nanotdf).
35-
[^112]: ABAC is Attribute Based Access Control.
36-
[^113]: Dissem is Dissemination List (i.e. email lists).
37-
38-
<!-- Service Footnotes -->
39-
40-
[^120]: Authorization APIs for managing authorization policies.
41-
[^121]: Key Access Server (KAS) APIs for accessing key management.
42-
[^130]: APIs for managing policy attributes [proto](https://github.com/opentdf/platform/blob/main/service/policy/attributes/attributes.proto).
9+
Please refer to the [SDK Feature Matrix](../appendix/matrix.mdx#sdk) in the Appendix for the supported features in each SDK.
4310

4411
## Repositories
4512

‎docusaurus.config.ts

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import type { Config } from "@docusaurus/types";
99
import type * as Preset from "@docusaurus/preset-classic";
1010
import matter from "gray-matter";
1111
import listRemote from "./docusaurus-lib-list-remote";
12+
import { openApiSpecs } from "./preprocessing";
13+
import languageTabs from "./openapi-generated-clients";
1214

1315
const otdfctl = listRemote.createRepo("opentdf", "otdfctl", "main");
1416

@@ -46,10 +48,11 @@ const config: Config = {
4648

4749
onBrokenLinks: "throw",
4850
onBrokenMarkdownLinks: "warn",
51+
onBrokenAnchors: "warn",
4952
markdown: {
5053
mermaid: true,
5154
},
52-
themes: ["@docusaurus/theme-mermaid", "docusaurus-theme-github-codeblock"],
55+
themes: ["@docusaurus/theme-mermaid", "docusaurus-theme-github-codeblock", "docusaurus-theme-openapi-docs"],
5356

5457
// Even if you don't use internationalization, you can use this field to set
5558
// useful metadata like html lang. For example, if your site is Chinese, you
@@ -67,6 +70,7 @@ const config: Config = {
6770
docs: {
6871
routeBasePath: "/",
6972
sidebarPath: "./sidebars.js",
73+
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
7074
// Please change this to your repo.
7175
// Remove this to remove the "edit this page" links.
7276
// editUrl:
@@ -108,6 +112,10 @@ const config: Config = {
108112
label: "GitHub",
109113
position: "right",
110114
},
115+
{
116+
type: "search",
117+
position: "right",
118+
},
111119
],
112120
},
113121
footer: {
@@ -188,6 +196,7 @@ const config: Config = {
188196
// template: '#zoom-template',
189197
// },
190198
},
199+
languageTabs: languageTabs,
191200
} satisfies Preset.ThemeConfig,
192201
plugins: [
193202
[
@@ -731,6 +740,15 @@ ${updatedContent}`,
731740
},
732741
},
733742
],
743+
[
744+
"docusaurus-plugin-openapi-docs",
745+
{
746+
id: "api", // plugin id
747+
docsPluginId: "classic", // configured for preset-classic
748+
config: openApiSpecs
749+
},
750+
],
751+
require.resolve("docusaurus-lunr-search"),
734752
],
735753
};
736754

‎openapi-generated-clients.ts

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
/**
2+
* This file defines language tabs configuration for OpenAPI documentation
3+
*
4+
* TODO: Note that the languages commented below have been removed, since we offer
5+
* official SDKs for them, and we don't want to duplicate code or cause confusion.
6+
*/
7+
const languageTabs = [
8+
// {
9+
// highlight: "go",
10+
// language: "go",
11+
// logoClass: "go",
12+
// },
13+
// {
14+
// highlight: "javascript",
15+
// language: "nodejs",
16+
// logoClass: "nodejs",
17+
// },
18+
// {
19+
// highlight: "java",
20+
// language: "java",
21+
// logoClass: "java",
22+
// variant: "unirest",
23+
// },
24+
// {
25+
// highlight: "javascript",
26+
// language: "javascript",
27+
// logoClass: "javascript",
28+
// },
29+
{
30+
highlight: "bash",
31+
language: "curl",
32+
logoClass: "curl",
33+
},
34+
{
35+
highlight: "csharp",
36+
language: "csharp",
37+
logoClass: "csharp",
38+
},
39+
{
40+
highlight: "ruby",
41+
language: "ruby",
42+
logoClass: "ruby",
43+
},
44+
{
45+
highlight: "php",
46+
language: "php",
47+
logoClass: "php",
48+
},
49+
{
50+
highlight: "powershell",
51+
language: "powershell",
52+
logoClass: "powershell",
53+
},
54+
{
55+
highlight: "dart",
56+
language: "dart",
57+
logoClass: "dart",
58+
},
59+
{
60+
highlight: "c",
61+
language: "c",
62+
logoClass: "c",
63+
},
64+
{
65+
highlight: "objective-c",
66+
language: "objective-c",
67+
logoClass: "objective-c",
68+
},
69+
{
70+
highlight: "ocaml",
71+
language: "ocaml",
72+
logoClass: "ocaml",
73+
},
74+
{
75+
highlight: "r",
76+
language: "r",
77+
logoClass: "r",
78+
},
79+
{
80+
highlight: "swift",
81+
language: "swift",
82+
logoClass: "swift",
83+
},
84+
{
85+
highlight: "kotlin",
86+
language: "kotlin",
87+
logoClass: "kotlin",
88+
},
89+
{
90+
highlight: "rust",
91+
language: "rust",
92+
logoClass: "rust",
93+
},
94+
{
95+
highlight: "python",
96+
language: "python",
97+
logoClass: "python",
98+
},
99+
];
100+
101+
// export it
102+
export default languageTabs;

0 commit comments

Comments
 (0)