Application permissions
Application permissions allow you to control the types of actions that users can perform in your applications and APIs.
To implement access control based on permissions, commonly known as role-based access control (RBAC), define permissions for application features, then group these permissions into roles. Assigning roles to users grants access to features and API resources.
Application permissions and roles in PingOne help you centralize access control, making it easier to quickly and repeatedly assign permissions to users and adjust them as your business needs change.
|
To use application permissions, you must have PingOne Authorize in your environment. |
Resources and permissions
Applications are built on top of APIs, and application features are often represented as API operations. Accordingly, you define permissions against an API. Application resources are the things that you want to protect in your API or application.
An application permission specifies an action that a user can perform on an application resource. For example, if you have an invoicing application, you might define an invoice resource with permissions to view, create, pay, and void invoices. Learn more about this scenario in Adding application permissions.
Configuring application permissions
Complete the following steps to configure application permissions:
-
Add application roles. This includes assigning permissions to roles, and then assigning roles to users.
Enforcing permissions
To enable your application to retrieve and enforce permissions, you can include the permissions claim in access tokens or use permissions-based rules.
Permissions claim in access tokens
To include permissions in access tokens, enable the Include user permissions in Access Token toggle on the Permissions tab for a custom resource. When the toggle is enabled, the p1.permissions claim is included in access tokens scoped to the custom resource.
-
When an OAuth 2.0 client application requests an access token on behalf of a user, the claim is populated with the authenticated user’s permissions. The application must be scoped to the custom resource. Permissions are not included in tokens obtained through the Client Credentials grant type.
-
The claim is empty if the authenticated user isn’t assigned to a role that has application permissions.
A resource server can use this JWT claim to identify the token holder’s permissions in order to make authorization decisions.
|
The |
The p1.permissions claim contains an array of strings. Each member of the array is a permission key, such as invoices:read. For example, consider a business application called BizPro that has invoicing capabilities. A decoded token for a BizPro user with permissions to read, write, and pay invoices looks something like this:
{
"aud": [
"BizPro Invoices API"
],
"client_id": "2be7e2f8-02d8-46ca-9ebb-35e129a78452",
"exp": 1702659466,
"iat": 1702655866,
"iss": "https://auth.pingone.com/672e060d-e6c9-49d9-81b8-22ac46e55c85/as",
"p1.permissions": [
"invoices:read",
"invoices:write",
"invoices:pay"
],
"scope": "bizpro:invoices",
"sid": "d11d5eb0-b2cb-4674-b4ef-2cdc211d379c",
"sub": "c52cc34d-2f29-442d-adf8-00fc89f7bbd8",
}You can use the token introspection endpoint to return information about claims in the access token. Learn more in the Token Introspection API documentation.
Permissions-based rules
If your organization has more extensive use cases that require a large number of permissions, you can define permissions-based rules that work with your API gateway to enforce entitlements.
After you configure application permissions, complete the following steps to define permissions-based rules for permissions enforcement:
-
Register the API in order to enforce permissions.
Extending access control
When your organization’s access control needs progress beyond static permissions, you can leverage real-time contextual information in your access control decisions. Fine-grained authorization policies can factor in a range of contextual attributes, such as user characteristics, risk signals, and environment properties such as location and time.
You can use PingOne’s API Access Management custom policy capabilities in conjunction with application permissions to satisfy these access control requirements. Learn more in API services.