Working with the V5 Endpoint for API Access

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:

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:

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:

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__, example: 1_APA9G5HV7WXN9C_1023045.

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"
  }'

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.