Authorization APIs
  • 10 Jul 2024
  • 6 Minutes to read
  • Dark
    Light
  • PDF

Authorization APIs

  • Dark
    Light
  • PDF

Article summary

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

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:
image.png

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.

image.png

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:
image.png

If the Policy logic relies on a value mapped to an unavailable external Identity Source, it may cause errors, fail, or return a restricted response if included in the request calculation.
For more information about Unavailable Identity Sources, see Unavailable Identity Sources.


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:
image.png

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:
image.png

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

The Asset List will not include the relevant assets if the external Identity Source is unavailable or may return an empty response.
For more information about Unavailable Identity Sources, see Unavailable Identity Sources.


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:
image.png

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

If an external Identity Source is inaccessible, Policy Resolution may impact specific filters.
For more information about Unavailable Identity Sources, see Unavailable Identity Sources.


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:
image.png

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

image.png


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 preformed 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.


© 2024 PlainID Ltd.  All rights reserved.
 
 All intellectual property rights in, related to, or derived from this material will remain with PlainID Ltd. 

Reproduction, modification, recompilation, or transfer in whole or in part without written permission is prohibited. This material is made available as-is, without any implied warranties, all of which are hereby disclaimed, and PlainID Ltd. shall have no liability in relation hereto. 


Was this article helpful?

What's Next