PingOne

Application permissions

Application permissions allow you to control the types of actions that users can perform in your applications and APIs.

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.

With access control based on permissions, you define permissions for application features, then group these permissions into roles. Assigning roles to users grants access to features and API resources. This is commonly known as role-based access control (RBAC).

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 in Adding application permissions.

Configuring application permissions

Complete the following steps to configure application permissions:

  1. Add application permissions to an API

  2. 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 p1.permissions claim increases access token size and the time required to generate a token. Include permissions in access tokens if your organization doesn’t require a large number of permissions.

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

For more extensive use cases that require a large number of permissions, define permissions-based rules that work with your API gateway to enforce entitlements.

Complete the following steps to configure permissions-based rules for permissions enforcement:

  1. Connect your API gateway to PingOne.

  2. Register the API in order to enforce permissions.

  3. Define access control rules for API operations.

Extending access control

When your 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, environment properties such as location and time, and risk signals.

You can use PingOne’s API Access Management capabilities in conjunction with application permissions to satisfy these access control requirements. Learn more in API services.