PDP - PEP Use-Cases

# Use Cases: PDP ↔ PEP Communication Scheme [TOC] # What sort of different uses-cases for communication between PEP and PDP exist? ## 1. Assumptions * Communication is always initiated from the PEP to the PDP * The security of the communication is off-topic. * It is not the scope of this document to assume the definition of “_what is a policy?_” or how the policy is authored or stored by the PDP * We assume that the PDP might hold only _one Policy_ or _a collection of Policies_. \ In case a PDP holds a collection of Policies, each individual Policy can be identified and addressed by a PEP * The use cases should cover all common authorization models, including ABAC, RBAC, ReBAC and Graph-based AC ### Use cases with an Object database involved (PIP) * In a ReBAC and Graph model, the relationships between resources are internally known/accessible by the PDP - the PEP may only refer to them by _object-type_ and _object-id_ * In a ABAC model, the attributes of resource/subjects may or may not be known/accessible to the PDP: * if known by the PDP: the PEP may only refer to them by an Identifier * if not known by the PDP: the PEP must present the objects to the PDP * The same may be the case for RBAC and other models. * We assume that authorization requests come in two basic variants: * resource bound: refer to at least one resource and action * free form (non-resource bound): don’t refer to any resource, but a complex structure of input parameters determined by the policy context ## 1.1 Resource bound/unbound authorization requests * We assume that resource bound authorization requests involve the following _set of entities_: SUBJECT x ACTION x RESOURCE * a SUBJECT is an entity/object that requests a permission * an ACTION (a function/method the subject wants to execute or relates to the subject) * a RESOURCE is an entity/object to which a function/action is to be applied or part of an relation Resource bound authorization requests come in different variations, depending on the set of input parameters: * a) SUBJECT x ACTION x RESOURCE \ The PDP shall decide whether a specific _SUBJECT_ can perform an _ACTION_ on a specific _RESOURCE_ * b) ACTION x SUBJECT \ The PDP shall decide whether a _SUBJECT_ can perform an _ACTION_ in general. * c) ACTION x RESOURCE \ the PDP shall decide whether an _ACTION_ is available for a specific _RESOURCE_ in general. ## 1.2 form-free authorization requests In this kind of authorization request, the input data is structured to fit the policies request parameters, but does not require the PDP to gather object data from a database (PIP). In other words: * all necessary data to evaluate the policy is provided by the PEP * The input data is not subject to a specified format Example use cases: * any kubernetes deployment manifest * HTTP requests enforced by a HTTP-Proxy (as PEP) * any imaginable application-specific policy # 2. Use cases ## 2.1 Request PDP Metadata ### Rationale A PEP (or client) wants to discover the capabilities, features and characteristics of a PDP in order to deviate the appropriate communication scheme (message format) for further requests. Similar to SAML metadata, the PDP’s metadata MAY manifest the following characteristics: * about the PDP itself (as an entity), like * a **version string** to identify the PDP's communication scheme * a date/**timestamp** to inform about the timeliness of the PDP's metadata * **contact data** (administrative contact) ? * **certificate data** as a trust anchor for the PDP (?) * about the PDP's supported DECISION schemes/endpoints, like * support for single Policy Decision schema, incl. endpoint URL * support for aggregated Policy Decision schema, incl. endpoint URL * support for Partial Evaluation schema, incl. endpoint URL * … * about the PDP's communication policy, like * caching policy (is a PEP allowed to cache decisions?) * mandatory/optional **message authentication** for the PEP-PDP exchange * mandatory/optional **message encryption** for the PEP-PDP exchange * … ? * about the PDP's supported **HEALTH endpoints**, like * health metrics * decision log/statistics * about the PDP's **related PIP endpoints**, like * a list and status of external PIPs that are associated with the PDP * about the PDP's **policy management** endpoints, like * get a list of policies * get a list of policy sources (policies fetched from external sources) * endpoints to manipulate a policy (create/update/delete) * endpoints to trigger a policy refresh ### Examples See the prior art in the [XACML REST Profile](https://docs.oasis-open.org/xacml/xacml-rest/v1.0/xacml-rest-v1.0.html) ## 2.2 Request single Policy Decision ### Rationale A PEP may want a PDP to make a decision based on arbitrary input data. The PDP is requested to decide based on one policy (either named by its ID or a _default_ policy). The input data may be unbound/free or in a resource-bound context. ### Examples #### Example 1: Subject * Action * Resource The PEP needs a decision whether “User: Alice” has permission to perform action “DELETE” on “Document: Y”. * Input: * subject: User:Alice * action: DELETE * resource: Document:Y * evaluation result: * True or False #### Example 2: Subject * Action The PEP needs a decision whether the ACTION “PRINT” is available for “User:Alice”. * Input: * subject: User:Alice * action: PRINT * evaluation result: * True or False #### Example 3: Resource * Action The PEP needs a decision whether the ACTION “DELETE” is generally available for a resource “Document:Y”. * Input: * resource: Document:Y * action: DELETE * evaluation result: * True or False #### Example 4: Perform complex action The PEP needs a decision whether the subject “User:Alice” is allowed to perform the ACTION “Add Number” with the parameter “number = 20” and “currency = EUR” to the resource “Bank account: Y”. * Input: * subject: user:Alice * action: Add Number * parameter: number = 20 * parameter: currency = EUR * resource: Bank account: Y * evaluation result: * True or False This form can also represent a request to CREATE a new resource with arbitrary data: * Input: * subject: user:Alice * action: CREATE * parameter: resource type = DOCUMENT * parameter: title = “Lorem ipsum” * parameter: author = “user:Malory” * evaluation result: * True or False #### Example 5: complex authorization request The PEP needs a decision whether a supplied input structure is compliant with a certain policy, e.g.: * Is the supplied OIDC IdToken valid and compliant? * not expired? * Is the audience valid? Is the signature valid? Is the issuer valid? * Is the scope valid? * etc. * Is the supplied structure representing a “_comment message_” valid? * “name” contains values * “sender address” is a valid email address * “content” does not contain blocked keywords * other requirements are met * Is the supplied structure representing an “_online procurement form_”? * is the address valid? * is the invoice address valid? Is a VAT supplied? * is the total sum above a certain business value? * other arbitrary requirements #### Example 6: Return Policy for applications use The PEP wants the user to present/render/validate a form for an unspecified user and requires a set of parameters from the PDP based on certain context values provided by the PEPs runtime context. Example: Render a “customer onboarding” form with dependent form attribute requirements: * if “customer type = business customer” then * “VAT ID” is mandatory * “company name” is mandatory * if “customer type != business customer” then * don’t show “VAT ID” and “company name” * attribute “social-security number” is shown if “region == US” and “type = personal” ## 2.3 Request aggregated Policy Decision ### Rationale A PDP can contain a collection of policies that can be referred to by their individual policy ID. To secure a complex transaction, a PEP might need evaluations for a series of policies before allowing the transaction to commit. A PEP might want to request the PDP to evaluate given input data against a list of policies and evaluate the individual results against an expected value, given by the PEP. Each (sub-) policy addressed refers to a certain aspect of the transaction context of the PEP. Note: This use case is already described in [[XACML v3.0 Multiple Decision Profile Version 1.0 - OASIS Open](http://docs.oasis-open.org/xacml/3.0/xacml-3.0-multiple-v1-spec-cd-03-en.html)] ### Examples #### Example 1: An OAuth2 associated _user_ wants to _create_ a new _document_ with _specific_ attributes. * Input data: * subject: the OAuth2 ID Token of the user * action: CREATE * Resource: * type: document * name: “lorem ipsum” * author: “user: malory” * state published: True * category: “public” * policies to evaluate: * policy “_validate OAuth2 Token_” * policy “_validate permission for user to create resources_” * policy “_validate the requirements for document_” * expected results per policy: “true” * evaluate decision request to “true” if all sub-policies evalue to “true” ## 2.4 Request Policy Decision with explanation ### Rationale A PEP might want a detailed output of the PDP's evaluation result, not only a `true/false` decision. It is assumed that a policy can produce additional output if defined so and turned on by a parameter. This additional output may include * intermediate steps in policy evaluation * a decision id * runtime data by the PDP (decision duration, load metrics, ..?) This would mostly be required for debugging and profiling purposes. ### Examples Assume a policy that requires * the user to have the role “manager” * the user to be in the same group as the resource * the user to be “active” * the current time to be within “business hours” The Policy will evaluate to “true” if all requirements are satisfied. However, evaluating “false” doesn’t reveal which conditions failed. With explanation, the PDP would response a breakdown of the evaluated policy criteria: ``` result: True ⇐ Policy evaluation result explanation: ⇐ Policy breakdown is_role_manager: False is_same_group: True is_active: True is_within_business_hrs: True ``` ## 2.5 Request Partial Evaluation ### Rationale Partial Evaluation (PE) addresses the use case of “data filtering”, where the PEP requires a set of criteria and defined unknowns, that can be applied as a filter by the PEP for subsequent actions. The result of the Partial Evaluation forms a policy by itself and can be transformed/converted into a Domain-Specific-Language by the PEP and subsequently applied by the PEP. A convertible PE result can be represented as syntax-tree. This feature is implemented in Open Policy Agent - see: * [https://blog.openpolicyagent.org/partial-evaluation-162750eaf422](https://blog.openpolicyagent.org/partial-evaluation-162750eaf422) * [https://blog.openpolicyagent.org/write-policy-in-opa-enforce-policy-in-sql-d9d24db93bf4](https://blog.openpolicyagent.org/write-policy-in-opa-enforce-policy-in-sql-d9d24db93bf4) * [https://jacky-jiang.medium.com/policy-based-data-filtering-solution-using-partial-evaluation-c8736bd089e0](https://jacky-jiang.medium.com/policy-based-data-filtering-solution-using-partial-evaluation-c8736bd089e0) ### Examples (see [https://blog.openpolicyagent.org/write-policy-in-opa-enforce-policy-in-sql-d9d24db93bf4](https://blog.openpolicyagent.org/write-policy-in-opa-enforce-policy-in-sql-d9d24db93bf4) for the full use case example) <deleted image> The result of this PE result can be transformed into a SQL filter statement: <Deleted image> ## 2.6 Resource lookup Query ### Rationale A PEP might want the PDP to return a list of **_resources_** to which a _subject_ is permitted to perform a given _action_. This use-case requires the PDP to have some form of a datastore builtin or attached to (Policy Information Point). It can be applied at least to ReBAC, ABAC and Graph Models, but also RBAC, PBAC with attached PIPs. In ReBAC and GraphBAC scenarios, the ACTION or PERMISSION may also refer to a RELATIONSHIP. The PDP may return full objects or only refer to type/identifiers of those resources. The input parameters may involve * a subject * an action or permission (or relation) * a resource-type expected outputs are * a list of resources of the given type that comply with the requested policy context. The application may often be interested in the number of resources, e.g. for UI, forms, list views etc. So it would be helpful to provide the number of elements as metadata in the result. ### Examples #### Example 1: in ReBAC Return all RESOURCES of type “_document”_ where a SUBJECT of type “_user” _with ID “_alice”_ has the PERMISSION/RELATION “_reader_”. Input: * subject: * type: user * id: alice * permission/relation: “reader” * resource type: “document” Output: * metadata * resourceCount: 3 * resultset * document:doc-1 * document:doc-2 * document:doc-... or * {“type”: “document”, “id”: “doc-1”, name: “example 1”, ….} * {“type”: “document”, “id”: “doc-2”, name: “example 2”, ….} * {“type”: “document”, “id”: “doc-..”, name: “example ..”, ….} #### Example 2: in ReBAC - functional extended Extended example where the functional part is also extended by complex parameters. This case would require the PDP to (1) check on the relationships/permission in ReBAC and (2) evaluate the objects against a PBAC policy Input: * subject: * type: user * id: alice * permission: “set_quota” * parameter: _new_quota = 100_ * parameter: _units = GB_ * resource type: “document” output: _ same as previous example_ ## 2.7 Subject lookup Query ### Rationale A PEP might want the PDP to return a list of specific **_subjects_** that have a _permission_ on a given _resource_. This use-case requires the PDP to have some form of a datastore builtin or attached to (Policy Information Point). It can be applied at least to ReBAC, ABAC and Graph Models, but also RBAC, PBAC with attached PIPs. The PDP may return full subjects (with attributes) or only refer to type/identifiers of those. The input parameters would be: * a subject type * an action or permission (or relation) * a resource type * a resource id expected outputs are * a list of subjects of the given type that comply with the requested policy context. The application may often be interested in the number of resources, e.g. for UI, forms, list views etc. So it would be helpful to provide the number of elements as metadata in the result. ### Examples #### Example 1: in ReBAC Return all SUBJECTS of type “_user”_ which have a permission _“read”_ on the RESOURCE of type “_document_” and resource id “_doc-abc_”. Input: * subject: * type: user * permission/relation: “read” * resource type: “document” * resource id: “doc-abc” Example output: * metadata * resourceCount: 3 * permission: read * resource type: document * resource id: doc-abc * subject type: user * resultset: * user-alice * user-bob * user-fred * user . . . # 3. Additional use cases ## 3.1 Request a PDP health status Note: Not so obviously NOT subject to the PEP-PDP use-cases, but could a PEP be interested in the status of a PDP ? ### Rationale A PEP may want to contact a PDP and request its operational health status, e.g. to decide based on the result whether he can use the PDP for requests. ### Examples <t.b.d.> ## 3.3 Request a Object manipulation Note: Debatable! ### Rationale In practice, a PDP is often incorporated with an external datastore, holding metadata about objects, like: * relationships (in a ReBAC/GraphBAC approach) * attributes of the objects * other metadata, which can be the subject of a policy. In general, those entities are available over a Policy Information Point (PIP) component. Data in the PDP is also subject to changes by the application. From the application’s perspective point of view it is sometimes difficult to convey that authorization data can accessed over the PDP (as sort of “read” operation) BUT changes on authorization must be committed to “somewhere else”, e.g. the 3rd-party that is the also backend for the PDP/PIP. There_ _are use cases where the PDP _could_ be used by the application to commit changes on data: * An application may want to commit changes on authorization data the same way it does queries to the PDP. It is convenient to application developers to use the same instance for changes as used for (policy evaluation) queries on the same subject/object. * Change operation on authorization data is likely also subject to a policy evaluation, like “_is this application permitted to submit this change_” or “_does this change request comply with the policy?_”, before the change is actually committed. * An application may want to rely on the success of a change operation - AS per policy - and only continue if the operation was successful. \ I.e. Applications perspective> “_Can I assume that the new data as presented is now the new state of the authorization system?_” In this case, the expectations between both components are reversed: The application asks the PDP/PIP if their state complies with the applications expectation at runtime. ### Examples #### Example 1: Update relationship of resources In a ReBAC case, the application may want to set relationships between e.g. a document and users: Input: * action: Update Resources * update element 1: * resource type: document * resource type: doc-123 * permission/relation: “owner” * subject type: “user” * resource id: “alice” * update element 2: * resource type: document * resource type: doc-123 * permission/relation: “editor” * subject type: “user” * resource id: “bob” Example output: * success or error If the operation is successful, the authorization system has a new state that complies with the applications expection. Update operations may include * create/delete permission/relation between a subject & a resource * modify permission/relation between a subject & a resource, e.g. * set an attribute to a relation (e.g. like GraphBAC) * set parameters limited to a operation, like “_credit-limit = xy_” * add/delete/change attributes of any object (subject or resource) ## 4. Open Points / Questions / Discussion ## 4.1 Representation of the functional element ### Rationale * many real-worlds authorization requests refer to a “SUBJECT - ACTION - RESOURCE” _authorization triplet_ There is need to define a structured representation of the ACTION (or “operator”) part: * the** ACTION** part can express * a) **simple string**: e.g. “view”, “update”, “print”, “delete” or * b) a **complex function** with parameters**:** * deposit_money (amount = 100, currency = EUR) * fill_with_color (red = .., green = .., blue= ..) * In ReBAC and GraphBAC scenarios, there is also a **relationship** between subject & resource, which is the basis for a **permission** (aka action) - _a subject has a permission because of its relationship_ * in GraphBAC (and other generic) scenarios, a RELATIONSHIP may also have attributes, e.g. * relationship: “connected”, attributes: _date of connection_, _type of connection, cost of the path_ * relationship: “member”, attribute: _date of membership_, _type of membership_ (premium, normal, ..), etc. ### Hypothesis: At QUERY time, there is no need to distinguish between a “PERMISSION” or “ACTION” in the functional element of the triplet, because **a query would** **always involve 3 or less elements**, but never more than those 3. \ In other words: A meaningful query can involve.. * “Subject + Resource + Action” * “Subject + Resource + Relation” * “Subject + Action” * or “Resource + Action” but not all 4 elements: * “Subject + Resource + Action + Relation” **Question: **Do we have a better term to subsume the different manifestations of the second element in “_Subject + [??] + [Resource]_” (which can be an “ACTION” or a “RELATION”) ? Suggestion: call it “_Operator_” or “_Authorization_” or “_Entitlement_” # References [IETF-SET] [https://datatracker.ietf.org/doc/html/rfc8417](https://datatracker.ietf.org/doc/html/rfc8417) [OPENID-SSF] [https://openid.net/specs/openid-sse-framework-1_0-ID1.html#rfc.section.2](https://openid.net/specs/openid-sse-framework-1_0-ID1.html#rfc.section.2) [OPENID-SSF-WG] [https://openid.net/wg/sharedsignals/](https://openid.net/wg/sharedsignals/) [XACML v3.0 Multiple Decision Profile] [http://docs.oasis-open.org/xacml/3.0/multiple/v1.0/cs02/xacml-3.0-multiple-v1.0-cs02.html](http://docs.oasis-open.org/xacml/3.0/multiple/v1.0/cs02/xacml-3.0-multiple-v1.0-cs02.html)