PingOne

API services

An API service is the fundamental unit of access control in PingOne Authorize that represents the API you want to protect.

Access control policies

To control access to your APIs, you can use built-in access control rules and custom policies. Built-in access control rules grant access based on:

  • Authorized scopes

  • User membership in groups

  • User permissions

  • Authentication policy

  • Time since last authentication

Learn more about these rules in Defining operations for protected actions.

For more complex access control scenarios, you can define custom policies in the API Access Management policy tree. Learn more in Adding custom policies for API services and operations.

Token management

An API service groups related API operations into a protected domain, such as https://example-api-domain.com, that clients access with a single access token. When you define an API service, you can use PingOne SSO to issue access tokens and manage users for the API service, or you can use external token sources such as PingOne Advanced Services or PingOne Advanced Identity Cloud.

PingOne SSO token source

If you use PingOne SSO to issue tokens for the API service, PingOne Authorize works with PingOne resources and applications to manage access control for your API. You can configure access control rules that are tightly integrated with PingOne. You can also define custom policies that handle more complex authorization scenarios.

Each API service is associated with a PingOne resource. This resource is a representation of your API for OAuth authorization purposes. Resources have scopes that are used in access token configuration. Scopes determine which resources a client can access. PingOne Authorize uses scopes to:

  • Ensure that the access token presented by a client was issued for your API. In this basic access control check, PingOne Authorize verifies that the audience claim in the access token for the client request matches the audience value configured for the API service’s associated resource.

    After you define an API service, make sure that you add a PingOne application that’s allowed to access your protected API service. To allow access, grant the application the same scope that you configured for the API service.

  • Determine the extent of access allowed to a client. For example, your API might require a user:read scope for reading user data and a user:write scope for modifying user data. You can configure a built-in access control rule to perform authorized scope checks.

When authorizing an HTTP request, if the request’s access token includes a subject, PingOne Authorize automatically populates the built-in PingOne.User attribute with the requesting user’s data.

External token source

If access tokens come from an external token source, PingOne Authorize validates the access token and inspects its claims. You can use the claims in custom policies to secure your APIs with claims-based access control. You can’t use built-in access control rules when tokens come from external sources.

PingOne Authorize doesn’t automatically provide identity information about the requesting user in built-in user attributes when tokens come from an external source. Instead, if the request’s access token includes a subject claim, you can use the PingOne.API Access Management.Identity.Access Token.Subject attribute to resolve user identity information from an external directory. Learn more in API Access Management attributes.

Learn more about external token sources in External OAuth servers in PingOne Authorize.

Policy deployment

Each API service has a system-owned decision endpoint that provides an environment for managing and deploying authorization policies relevant to the API service. The decision endpoint is created when you deploy the API service for the first time, and it has the same name as the API service. Learn more in Deploying an API service.