Authorization APIs

The Platform provides Runtime authorization endpoints that support different access patterns:

• Permit\Deny
• User Access Token (Entitlement Resolution)
• Policy Resolution
• User List (Subject Resolution)
• Policy List

The response to each Authorization request is calculated based on the matching Policy in real-time. The REST-based Runtime endpoints support specific, generic, and advanced requests and responses for the access patterns and support the use of adaptive search queries.

Authorization requests can be asked in multiple ways, supporting the way the application chooses to enforce access. PlainID authorization endpoints are designed to support those requests, providing the Application the flexibility it requires to enforce access.

To determine which Authorization API to use, you must understand your Application access patterns. These APIs determine how your Application offers access to your Identities (Dynamic Groups, users, employees, etc.)
The API you choose can:

• Grant access to single Asset or multiple Assets.
• Grant access per session or to a single call.
• Redirect access decisions to an underlying system (databases, search engines, etc.).
• Return a list of users with their associated attributes and Actions per Asset.

Authorization API URL Base

To access the Authorization APIs, ensure that the URL prefix matches your PlainID PDP location:

• United States Cloud PDP

https://tenant-name.us1.plainid.io

• Canadian Cloud PDP

https://tenant-name.ca1.plainid.io

• European Cloud PDP

https://tenant-name.eu1.plainid.io

• Local PAA

https://your-paa.acme.local

Authorization APIs

Understanding how each of the four Access patterns work will help determine which endpoint is the most suitable for your Application:

1. Permit/Deny

The Permit/Deny API call is a Yes/No authorization question built to respond to the request and optionally provide more details. The API response provides an Access Decision related to the request.

Best Practice
The Permit/Deny endpoint allows for integration with the Application without requiring any complex logic managed on the Application side. This approach is considered best practice when the requesting application is familiar with the assets requiring access permission.

For example:

To begin using the Permit/Deny API call, you must specify (at least):

• One Identity
• One or more Assets
• Scope credentials
• Associated Actions (Optional)

In PlainID terminology, this means that, along with Scope credentials (which handles authentication to the PDP), you must specify:

"WHO (Identity) can do WHAT (Action/s) on WHAT(Asset/s)" and a Permit/Deny response is returned.

• Permit is returned when the specified Identity is allowed to perform all the specified Action/Asset combinations.

• Deny is returned when the identity and/or the Action/Asset combination are not allowed.

The request can also include an optional parameter that would require the response to return a full breakdown showing what access was permitted or denied per Asset/Action and why:

2. User Access Token

The User Access Token API call is an open-ended request for a specific user. The response returns a list of allowed assets and associated actions for the specific user in the application. The request allows the integrating application to cache the list of allowed assets and associated actions to the duration for the session. This reduces the overall effort involved in enforcing access.

Best Practice
This API is designed to deliver session-based results for efficiency and security.

It is not designed for delivering real-time decisions. It is session-based and may not have updated information for extended session times. Further, it may impact memory and/or performance if the request includes a large amount of Assets in a single token (more than 1000).

This token works similarly to the Authentication token, where a response is provided at the beginning of the session and is used for the duration or until its timeout.

For example:

Similar to the additional parameter in the Permit/Deny API, the User Access Token returns a response that contains a list of all the authorized Actions/Assets associated with the requested user:

For a complete overview of the request parameters, including accepted and required default values, see User Access Token in the PlainID Developer Authorization Guide.

3. Policy Resolution

The Policy Resolution API call enables you to create your own enforcement points when you need to support access to large amounts of data (SQL, search engines, big data, etc.) or when another system or platform is enforcing access. In order to use the API, you must specify the Identity, Scope credentials, in addition to optional attributes to receive a more specific response.

Best Practice
Integrating with this API is recommended for data use-cases and for scenarios when the expected number of Assets returned per call is more than 1000.

The API is designed to respond to requests that ask "What access filters need to be set for a specific user to access an asset?"
 
For example:

The response will then show the data filters and/or the list of data items that user is allowed to access.

4. User List

The User List API call is an open-ended question for a specific Asset. It returns the list of users, the attributes they are associated with, and which action they are allowed to perform on a specific asset. In order to use the API, you must specify the Asset, Scope credentials, in addition to optional attributes to receive a more specific response.

For example:

The API will respond to the the request asking "Which Identities can perform this Action on this Asset?"

For more information on using each Access API, refer to their respective API documentation.

Unavailable Identity Sources

PIP Sources can serve as external sources for Identity Templates, which are integrated into Policy logic. If external Sources (AUX/Context) are not part of the business logic, rendering them unnecessary for Policy evaluation, or become unavailable, Policy evaluation can still be performed without affecting the Policy result.
In such cases, the Runtime can continue to function if the Authorization calculation can be performed within the Policy logic. This approach reduces dependency on external sources, potentially lowers execution time, and prevents Runtime request failures.

To use the Unavailable Identity Sources feature:
The parameter skipUnneededOrUnavailableIdentitySources can be set to true in the Authorization request when users still need Policy evaluation to run if Identity Sources are unavailable.
Users can also set the default parameter for Unavailable Identity Sources as true or false using the config key RUNTIME_DEFAULT_SKIP_UNNEEDED_OR_UNAVAILABLE_IDENTITY_SOURCES. This key can be set in either the standalone configuration file or through the Helm Environment Variables to apply the default for all requests for the applicable PDP.

See the skipUnneededOrUnavailableIdentitySources parameter in the relevant Authorization API endpoints for information on toggling the relevant parameter to skip or include the value in the request.

Note that if an Identity Source is unavailable, a limited response is returned to avoid unauthorized decisions.

For more information about external Identity Sources, see Managing Attribute Sources.