Skip to content

Commit a18cf71

Browse files
pflynn-virtrupflynn-virtru
authored
chore: Casbin authorization policy configuration docs (#1674)
Updated documentation to include Casbin configuration for endpoint authorization. Added details on key aspects of authorization, example configuration, role permissions, and managing policy through the YAML file. This enhances the security and flexibility of endpoint access control. opentdf/docs#28 DSP-129
1 parent a4583b0 commit a18cf71

File tree

1 file changed

+106
-18
lines changed

1 file changed

+106
-18
lines changed

‎docs/configuration.md‎

Lines changed: 106 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -66,23 +66,24 @@ The server configuration is used to define how the application runs its server.
6666
6767
Root level key `server`
6868

69-
| Field | Description | Default | Environment Variable |
70-
| --------------------- | ----------------------------------------------------------------- | ------- | -------------------- |
71-
| `auth.audience` | The audience for the IDP. | | OPENTDF_SERVER_AUTH_AUDIENCE |
72-
| `auth.issuer` | The issuer for the IDP. | | OPENTDF_SERVER_AUTH_ISSUER |
73-
| `auth.cache_refresh` | Interval in which the IDP jwks should be refreshed | `15m` | OPENTDF_SERVER_AUTH_CACHE_REFRESH |
74-
| `auth.dpopskew` | The amount of time drift allowed between when the client generated a dpop proof and the server time. | `1h` | OPENTDF_SERVER_AUTH |
75-
| `auth.skew` | The amount of time drift allowed between a tokens `exp` claim and the server time. | `1m` | OPENTDF_SERVER_AUTH_SKEW |
76-
| `auth.public_client_id` | The oidc client id. This is leveraged by otdfctl. | | OPENTDF_SERVER_AUTH_PUBLIC_CLIENT_ID |
77-
| `auth.enforceDPoP` | If true, DPoP bindings on Access Tokens are enforced. | `false` | OPENTDF_SERVER_AUTH_ENFORCEDPOP |
78-
| `cryptoProvider` | A list of public/private keypairs and their use. Described [below](#crypto-provider) | empty | |
79-
| `enable_pprof` | Enable golang performance profiling | `false` | OPENTDF_SERVER_ENABLE_PPROF |
80-
| `grpc.reflection` | The configuration for the grpc server. | `true` | OPENTDF_SERVER_GRPC_REFLECTION |
81-
| `host` | The host address for the server. | `""` | OPENTDF_SERVER_HOST |
82-
| `port` | The port number for the server. | `9000` | OPENTDF_SERVER_PORT |
83-
| `tls.enabled` | Enable tls. | `false` | OPENTDF_SERVER_TLS_ENABLED |
84-
| `tls.cert` | The path to the tls certificate. | | OPENTDF_SERVER_TLS_CERT |
85-
| `tls.key` | The path to the tls key. | | OPENTDF_SERVER_TLS_KEY |
69+
| Field | Description | Default | Environment Variable |
70+
|-------------------------|---------------------------------------------------------------------------------------------------------------|---------|--------------------------------------|
71+
| `auth.audience` | The audience for the IDP. | | OPENTDF_SERVER_AUTH_AUDIENCE |
72+
| `auth.issuer` | The issuer for the IDP. | | OPENTDF_SERVER_AUTH_ISSUER |
73+
| `auth.policy` | The Casbin policy for enforcing authorization on endpoints. Described [below](#casbin-endpoint-authorization) | | |
74+
| `auth.cache_refresh` | Interval in which the IDP jwks should be refreshed | `15m` | OPENTDF_SERVER_AUTH_CACHE_REFRESH |
75+
| `auth.dpopskew` | The amount of time drift allowed between when the client generated a dpop proof and the server time. | `1h` | OPENTDF_SERVER_AUTH |
76+
| `auth.skew` | The amount of time drift allowed between a tokens `exp` claim and the server time. | `1m` | OPENTDF_SERVER_AUTH_SKEW |
77+
| `auth.public_client_id` | The oidc client id. This is leveraged by otdfctl. | | OPENTDF_SERVER_AUTH_PUBLIC_CLIENT_ID |
78+
| `auth.enforceDPoP` | If true, DPoP bindings on Access Tokens are enforced. | `false` | OPENTDF_SERVER_AUTH_ENFORCEDPOP |
79+
| `cryptoProvider` | A list of public/private keypairs and their use. Described [below](#crypto-provider) | empty | |
80+
| `enable_pprof` | Enable golang performance profiling | `false` | OPENTDF_SERVER_ENABLE_PPROF |
81+
| `grpc.reflection` | The configuration for the grpc server. | `true` | OPENTDF_SERVER_GRPC_REFLECTION |
82+
| `host` | The host address for the server. | `""` | OPENTDF_SERVER_HOST |
83+
| `port` | The port number for the server. | `9000` | OPENTDF_SERVER_PORT |
84+
| `tls.enabled` | Enable tls. | `false` | OPENTDF_SERVER_TLS_ENABLED |
85+
| `tls.cert` | The path to the tls certificate. | | OPENTDF_SERVER_TLS_CERT |
86+
| `tls.key` | The path to the tls key. | | OPENTDF_SERVER_TLS_KEY |
8687

8788
Example:
8889

@@ -216,4 +217,91 @@ services:
216217
rego:
217218
path: /path/to/policy.rego
218219
query: data.opentdf.entitlements.attributes
219-
```
220+
```
221+
222+
### Casbin Endpoint Authorization
223+
224+
OpenTDF uses Casbin to manage authorization policies. This document provides an overview of how to configure and manage the default authorization policy in OpenTDF.
225+
226+
#### Key Aspects of Authorization Configuration
227+
228+
1. **Default Role**: The default role assigned to an authorized user if no specific role is found.
229+
2. **Claim**: The claim in the OIDC token that should be used to map roles.
230+
3. **Map**: Mapping between policy roles and IdP roles.
231+
4. **CSV**: The authorization policy in CSV format.
232+
5. **Model**: The Casbin policy model.
233+
234+
#### Configuration in opentdf-example.yaml
235+
236+
Below is an example configuration snippet from
237+
opentdf-example.yaml:
238+
239+
```yaml
240+
server:
241+
auth:
242+
enabled: true
243+
enforceDPoP: false
244+
public_client_id: 'opentdf-public'
245+
audience: 'http://localhost:8080'
246+
issuer: http://keycloak:8888/auth/realms/opentdf
247+
policy:
248+
## Default role for all requests
249+
default: "role:standard"
250+
251+
## Dot notation is used to access nested claims (i.e. realm_access.roles)
252+
claim: "realm_access.roles"
253+
254+
## Maps the external role to the OpenTDF role
255+
## Note: left side is used in the policy, right side is the external role
256+
map:
257+
standard: opentdf-standard
258+
admin: opentdf-admin
259+
org-admin: opentdf-org-admin
260+
261+
## Custom policy (see examples https://github.com/casbin/casbin/tree/master/examples)
262+
csv: |
263+
p, role:org-admin, policy:attributes, *, *, allow
264+
p, role:org-admin, policy:subject-mappings, *, *, allow
265+
p, role:org-admin, policy:resource-mappings, *, *, allow
266+
p, role:org-admin, policy:kas-registry, *, *, allow
267+
p, role:org-admin, policy:unsafe, *, *, allow
268+
p, role:admin, policy:attributes, read, allow
269+
p, role:admin, policy:subject-mappings, read, allow
270+
p, role:admin, policy:resource-mappings, read, allow
271+
p, role:admin, policy:kas-registry, read, allow
272+
p, role:standard, policy:attributes, read, allow
273+
p, role:standard, policy:subject-mappings, read, allow
274+
p, role:standard, policy:resource-mappings, read, allow
275+
p, role:standard, policy:kas-registry, read, allow
276+
p, role:unknown, entityresolution.EntityResolutionService.ResolveEntities, write, allow
277+
p, role:unknown, kas.AccessService/Rewrap, *, allow
278+
279+
## Custom model (see https://casbin.org/docs/syntax-for-models/)
280+
model: |
281+
[request_definition]
282+
r = sub, res, act, obj
283+
284+
[policy_definition]
285+
p = sub, res, act, obj, eft
286+
287+
[role_definition]
288+
g = _, _
289+
290+
[policy_effect]
291+
e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
292+
293+
[matchers]
294+
m = g(r.sub, p.sub) && globOrRegexMatch(r.res, p.res) && globOrRegexMatch(r.act, p.act) && globOrRegexMatch(r.obj, p.obj)
295+
```
296+
297+
#### Role Permissions
298+
299+
- **Org Admin**: Can read, write, and perform unsafe mutations.
300+
- **Admin**: Can read and write.
301+
- **Standard User**: Can read.
302+
- **Public Endpoints**: Accessible without specific roles.
303+
304+
#### Managing Authorization Policy
305+
306+
Admins can manage the authorization policy directly in the YAML configuration file. For detailed configuration options, refer to the [Casbin documentation](https://casbin.org/docs/en/syntax-for-models).
307+

0 commit comments

Comments
 (0)