diff --git a/docs/components/authorization/entity_resolution/overview.md b/docs/components/authorization/entity_resolution/overview.md index 1f9f2381..2068591d 100644 --- a/docs/components/authorization/entity_resolution/overview.md +++ b/docs/components/authorization/entity_resolution/overview.md @@ -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: @@ -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" } ] }, @@ -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. @@ -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" } ] } diff --git a/docs/components/authorization/overview.md b/docs/components/authorization/overview.md index 040ae28b..ac3e9710 100644 --- a/docs/components/authorization/overview.md +++ b/docs/components/authorization/overview.md @@ -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 { @@ -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; } ``` @@ -41,11 +48,13 @@ Below is an example GetEntitlements request: "entities": [ { "id": "e1", - "emailAddress": "alice@example.com" + "emailAddress": "alice@example.com", + "category": "CATEGORY_SUBJECT" }, { "id": "e2", - "userName": "bob" + "userName": "bob", + "category": "CATEGORY_SUBJECT" } ], "scope": { @@ -117,11 +126,13 @@ Below is an example GetDecisions request: "entities": [ { "id": "e1", - "emailAddress": "bob@example.com" + "emailAddress": "bob@example.com", + "category": "CATEGORY_SUBJECT" }, { "id": "e2", - "userName": "alice" + "userName": "alice", + "category": "CATEGORY_SUBJECT" } ], "id": "ec1" @@ -130,7 +141,8 @@ Below is an example GetDecisions request: "entities": [ { "id": "e1", - "clientId": "client1" + "clientId": "client1", + "category": "CATEGORY_ENVIRONMENT" } ], "id": "ec2" @@ -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: @@ -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.