Skip to content

feat(authz): Documentation for typed entities #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
elizabethhealy merged 2 commits into from
Aug 20, 2024
Merged

feat(authz): Documentation for typed entities #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39fe870
include entity type in docs
elizabethhealy Aug 7, 2024
0af069c
Merge branch 'main' into entity-type-docs
elizabethhealy Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions docs/components/authorization/entity_resolution/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ The entity resolution service is an IDP specific service that interacts with the
As the service may differ from IDP to IDP, the platform consumer is required to implement their own entity resolution service for the IDP they choose to use. The service must follow the provided [protos](https://github.com/opentdf/platform/blob/main/service/entityresolution/entity_resolution.proto).

## CreateEntityChainFromJwt
This endpoint takes JWTs (usually representing IDP access tokens) and converts them into [entity chains](../overview.md#entity-chains). As stated in the authorization docs, more than one entity can be involved in a particular request. We must parse these entities from the token and form an entity chain to ensure all entities have the required entitlements. This endpoint is primarily used by KAS to form an entity chain from the access token it recieves on a rewrap request.
This endpoint takes JWTs (usually representing IDP access tokens) and converts them into [entity chains](../overview.md#entity-chains). As stated in the authorization docs, more than one entity can be involved in a particular request. We must parse these entities from the token, categorize the entities as either subject or environment, and form an entity chain to ensure the relevant entities have the required entitlements. This endpoint is primarily used by KAS to form an entity chain from the access token it recieves on a rewrap request.

### Request and Response
Below is an example request to CreateEntityChainFromJwt containing a list of tokens and IDs for each token:
Expand Down Expand Up @@ -31,11 +31,13 @@ Below is an example response to the above request:
"entities": [
{
"id": "jwtentity-0",
"client_id": "client1"
"client_id": "client1",
"category": "CATEGORY_ENVIRONMENT"
},
{
"id": "jwtentity-1",
"user_name": "alice"
"user_name": "alice",
"category": "CATEGORY_SUBJECT"
}
]
},
Expand All @@ -44,18 +46,20 @@ Below is an example response to the above request:
"entities": [
{
"id": "jwtentity-0",
"client_id": "client2"
"client_id": "client2",
"category": "CATEGORY_ENVIRONMENT"
},
{
"id": "jwtentity-1",
"user_name": "bob"
"user_name": "bob",
"category": "CATEGORY_SUBJECT"
}
]
},
]
}
```
Each token resolved to a chain with multiple entities including a client and user.
Each token resolved to a chain with multiple entities including a client and user.

## ResolveEntities
This endpoint takes a list of entities and resolves them with the IDP to entity representations. As this service is implemented by the platform consumer, it is up to the implementer to build the entity representations. For example, in the Keycloak entity resolution service implementation we return the json client/user representations that the service retrieves from Keycloak.
Expand All @@ -68,11 +72,13 @@ Below is an example request to ResolveEntities including a list of entities to r
"entities": [
{
"id": "e1",
"userName": "alice"
"userName": "alice",
"category": "CATEGORY_SUBJECT"
},
{
"id": "e2",
"clientId": "client1"
"clientId": "client1",
"category": "CATEGORY_ENVIRONMENT"
}
]
}
Expand Down
30 changes: 21 additions & 9 deletions docs/components/authorization/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ The GetEntitlements endpoint takes a list of entities and returns the attributes

An entity is any being or structure interacting with the platform. A person-entity (PE) represents an actual user/person while a non-person entity (NPE) can represent a system or program interacting with the platform on behalf of a user or via an automated process.
The authorization service accepts a variety of methods to identify an entity all listed in the defined proto below.
Entities are also categorized as either subject entities or environment entities. A subject entity represents a subject (PE or NPE) and is included in data attribute policy access decisions. An environment entity is excluded from data attribute policy access decisions.

```
message Entity {
Expand All @@ -27,6 +28,12 @@ message Entity {
EntityCustom custom = 7;
string client_id = 8;
}
enum Category {
CATEGORY_UNSPECIFIED = 0;
CATEGORY_SUBJECT = 1;
CATEGORY_ENVIRONMENT = 2;
}
Category category = 9;
}
```

Expand All @@ -41,11 +48,13 @@ Below is an example GetEntitlements request:
"entities": [
{
"id": "e1",
"emailAddress": "[email protected]"
"emailAddress": "[email protected]",
"category": "CATEGORY_SUBJECT"
},
{
"id": "e2",
"userName": "bob"
"userName": "bob",
"category": "CATEGORY_SUBJECT"
}
],
"scope": {
Expand Down Expand Up @@ -117,11 +126,13 @@ Below is an example GetDecisions request:
"entities": [
{
"id": "e1",
"emailAddress": "[email protected]"
"emailAddress": "[email protected]",
"category": "CATEGORY_SUBJECT"
},
{
"id": "e2",
"userName": "alice"
"userName": "alice",
"category": "CATEGORY_SUBJECT"
}
],
"id": "ec1"
Expand All @@ -130,7 +141,8 @@ Below is an example GetDecisions request:
"entities": [
{
"id": "e1",
"clientId": "client1"
"clientId": "client1",
"category": "CATEGORY_ENVIRONMENT"
}
],
"id": "ec2"
Expand All @@ -156,7 +168,7 @@ Below is an example GetDecisions request:
}
```

In this example, there are two entity chains, one comprised of users bob and alice, and the other comprised of client1. This request seeks to evaluate whether these entity chains have permission to DECRYPT two resources with the provided attribute sets.
In this example, there are two entity chains, one comprised of users bob and alice both categorized as subject entities, and the other comprised of client1 which is categorized as an environment entity. This request seeks to evaluate whether these entity chains have permission to DECRYPT two resources with the provided attribute sets.

Below is an example GetDecisions response:

Expand Down Expand Up @@ -196,12 +208,12 @@ Below is an example GetDecisions response:
"action": {
"standard": "STANDARD_ACTION_DECRYPT"
},
"decision": "DECISION_DENY",
"decision": "DECISION_PERMIT",
"obligations": []
}
]
}
```

In the response there are four entries, one for each combination of entity chain and resource attribute set, indicating whether that entity chain has permission access to data with that attribute set based on the attribute rules defined [here](../policy/attributes/overview.md#definitions). For example, we can see that client1 does not have access to the attribute set
"ra-set-2" while both alice and bob do have access to that set.
In the response there are four entries, one for each combination of entity chain and resource attribute set, indicating whether that entity chain has permission access to data with that attribute set based on the attribute rules defined [here](../policy/attributes/overview.md#definitions). For example, we can see that bob and alice do not have access to the attribute set
"ra-set-1". Because environment entities are not included in the data attribute access decsiion, and because client1 is the only entity in the chain, the chain will always be given DECISION_PERMIT.