Introduction
This article is a guide on how to use the PDP V5 Endpoint. One of the access patterns supported by the PlainID PDP is API Access Control, in which customers' REST API requests are being evaluated for Authorization based on Policies, Identity awareness and dynamic calculation. This access pattern is supported by using API Matchers and Mappers as part of the Policy modeling and a designated PDP endpoint, usually used by PlainID's API GW and Service Mesh Authorizers.
Request Flow
The API Access request flow starts with any REST API request needs to be evaluated for Authorization. The API request details are converted into a PDP V5 endpoint, either by an Authorizer or directly by the customer's service. The original requesting identity is used as the Identity evaluated for Authorization. The request itself is described with all of its components in the PDP V5 request, which use API Matchers and Mappers to structure an Asset that is evaluated for authorization.
Endpoint Details
Authorization
Like all PDP requests, requests to this endpoint are authorized either with a Client ID and Client Secret (sent as headers) or with an Authorization JWT.
See Managing Scope Authentication for more information on Authorization and Headers.
Request Type
This endpoint allows Permit/Deny decision requests based on the requesting Identity and the protected Asset (represented in the original API call).
Asset Data
The Authorization request's protected Asset is represented in the original API call, as described in the PDP V5 request. PlainID's PDP receives all relevant details from the original API call as part of the authorization request. It then uses API matchers and mappers—configured via the PlainID Management Console’s Policy Authoring tool—to evaluate the protected Asset and determine the Access Decision.
Asset Attribute Mappers can extract values from different parts of the REST request, which includes extracting values from the URI path, query parameters, headers, and the request body, ensuring accurate and efficient Asset Attribute management.
The system supports multiple Asset Types and Actions, allowing Access Decisions to be calculated for various Asset-Action pairs in a single request, representing a single original API call.
Asset Data in Path Parameter Example:
"uri": {
"path": [
"/accounts/customers/customerType/T1",
"accounts",
"customers",
"customerType",
"1"
]
If the assetId is mapped using PATH [3] and the User Type is mapped using PATH [4], then the calculated Asset would be:
| Attribute | Value |
|---|---|
| assetId | customerType |
| userType | 1 |
Asset Data in Body Parameter Example:
"body": {
"accounts": {
"branch": "100",
"type": "A",
"account": "987654",
"customerType":"1"
},
}
If the Asset Attributes from the "accounts" object are mapped using the following Attribute mappings:
assetID - BODY $.accounts.account
accType - BODY $.accounts.type
accBranch - BODY $.accounts.branch
cusType - BODY $.accounts.customerType
The resulting Asset would be:
| assetID | accType | accBranch | cusType |
|---|---|---|---|
| 987654 | A | 100 | 1 |
Working with Multiple Assets
When working with multiple Assets, each Asset can have its own set of values, potentially leading to the creation of several Assets. PlainID simplifies this process by mapping the Assets while maintaining the relationship between their Attribute values.
Asset Data Array in Body Parameter Example:
"body": {
"accounts": [
{
"branch": "100",
"type": "A",
"account": "987654"
"customerType":"1"
},
{
"branch": "200",
"type": "B",
"account": "123456"
"customerType":"2"
}
]
},
If the Asset Attributes from the "accounts" array are mapped using the following Attribute mappings:
assetID - BODY $.accounts[*].account
accType - BODY $.accounts[*].type
accBranch - BODY $.accounts[*].branch
cusType - BODY $.accounts[*].customerType
The resulting Asset would be:
| assetID | accType | accBranch | cusType |
|---|---|---|---|
| 987654 | A | 100 | 1 |
| 123456 | B | 200 | 2 |
Request Attributes
Request Attributes are values extracted from incoming API requests and evaluated during Authorization. These values represent contextual information—such as tenant identifiers, client application names, or request-specific flags—essential for making Access Decisions.
PlainID allows configuration of Request Attribute Mappers that extract data from the original API call. These Mappers can retrieve values from various locations in the request, including HTTP headers, query parameters, and path segments.
Each Request Attribute is configured with:
- A Request Attribute ID, used as a reference in Policies (using dot notation in the request).
- A source and path (
header,query, orpath, etc.) - An API Mapper, associating a specific API request process for Authorization.
For more details on Request Attributes, refer to Request Attributes.
Request Attributes are dynamically extracted during V5 Runtime evaluation based on the API Mapper configuration. They replace the need to manually populate values under the environment parameter in the V5 Permit Deny API, streamlining context-aware access control.
Example: Mapping Contract ID from the API Request
Assuming an external data source is used for an Asset Type called Documents, with Attributes like docId, docName and contractId, which is an identifier of the related contract the document is associated to.
When using API Access, there may be a business requirement to check access permission on a specific document and include a specific check that the document's contract is matching a contract sent as part of the API request.
If the API structure is /api/documents/byID/{docId}/contract/{contractId} in this example, you can define a Request Attribute contractIdentifier and map it to the relevant location in the API request, which would be Path[6]. Alongside this mapping, we can also map AssetID to Path[4].
Now, in the Policy Ruleset we can use a rule that matches the document attribute contractId to the request attribute request.contractIdentifier.
During Runtime, these values are automatically extracted based on the API Mapper configuration. This allows Policies to incorporate request-specific data—without requiring the client to manually pass additional attributes in a separate payload.
Identity Data
In the PDP, Access calculations are identity-aware. Therefore, the PDP should receive data such as UIDs and potential additional virtual attributes.
Identity JWT Support
A JWT can be sent as part of the original request and be included in the call to this endpoint. Using JWT as an Identity information source is a generic capability in the PlainID PDP and can be used in this endpoint like all other PDP endpoints. Refer to the Managing Attribute Sources article on how to pass a JWT in the request and how to parse Identity Attributes from it through mappers.
Identity Attributes
If required, additional Identity Attributes and context information can be sent to the PDP like other PDP endpoints by using the regular PDP request parameters under the meta.runtimeFineTune property.
Request Structure
Endpoint
POST https://{PAA-PDP-Host-Name}/api/runtime/5.0/decisions/permit-deny
Note: Replace {PAA-PDP-Host-Name}
Headers
X-Client-Id - Scope clientID (mandatory)
X-Client-Secret - Scope clientSecret
- The Scope clientSecret can be replaced by a JWT.
X-Authorizer-Meta - Authorizer metadata. Format: 1_
Note: Currently, the Authorizer metadata details are not used or validated yet.
Body
This endpoint’s request body should include the original request divided into sections representing the original structure of the request. The sources are properties of the JSON payload with the relevant data. Sources of the original request should include the following properties, which contain examples for the sample original request:
curl -X POST \
https://example.com/api/1.0/pets/dog/1?color=black&size=L \
--header 'x-request-id: 8CDAC3B6C4D752ABE60EFD7A31AFEEBA' \
--header 'Authorization: Bearer eyJhbG...lXvZQ' \
--data '{
"key1": "value1",
"key2": "value2"
}'
| Property | Value - based on the original request details |
|---|---|
| headers | An object value with the header name (type) key value pairs and its value. "headers": { "x-request-id": "8CDAC3B6C4D752ABE60EFD7A31AFEEBA", "Authorization": "Bearer eyJhbG...lXvZQ" } |
| uri | An object value with sub properties for Path, Query params, etc. "uri": { "schema": "https", "authority": { ... }, "path": [ ... ], "query": { ... } } |
| uri.path | An array of values containing all the uri path parts. This array structure should have the full original URI with a '/' as the first value (array index 0). Additional values can be populated into this array by parsing the URI based on a '/', so each part of the URI will have its own value in the relevant order (part 1 in array index 1 and so on). "path": [ "/api/1.0/pets/dog/1", "api", "1.0", "pets", "dog", "1"] |
| uri.query | An object value containing all the query parameters and values. "query":{"color":"black", "size":"L" } |
| body | An object value that includes the full original body payload. "body":{ "key1": "value1", "key2": "value2" } |
| method | The HTTP verb of the original request. "method": "POST" |
| ip | The IP from which the original request was initiated (only if available and needed) |
Additional PDP Request Properties
An additional property you can use is meta and can include all other PDP request properties such as the Runtime request configuration under runtimeFineTune. This property can include any of the PDP request properties allowed and supported by PlainID’s Permit/Deny Authorization API. For example you can pass PDP request flags such as includeDenyReason, includeAccessPolicy, etc. and other request attributes such as contextData and environment in this property.
Request Body Payload Example
{
"headers": {
"x-request-id": "8CDAC3B6C4D752ABE60EFD7A31AFEEBA",
"Authorization": "Bearer eyJhbG...lXvZQ"
},
"uri": {
"path": [
"/pets/dog/1",
"pets",
"dog",
"1"
]
},
"ipAddress": "141.226.11.45",
"method": "POST",
"body": {
"a": "AA_1",
"uid": "1234566666"
},
"meta": {
"runtimeFineTune": {
"includeAccessPolicy": true,
"includeDetails": true,
"includeDenyReason": true,
"includeAssetAttributes": true,
"includeIdentityAttributes": true,
"includeIdentity": true,
}
}
}
Response Example
The response from this PDP endpoint is similar to the standard PDP Permit/Deny and include Permit/Deny responses. It can also provide a more complex response if multiple resources are evaluated. For more information, refer to the Authorization API article in the Documentation Portal.