PingOne

API services

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

Access control policies

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

  • Authorized scopes

  • User membership in groups

  • User permissions

For more information about these rules, see Defining operations for protected actions.

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

Token and user 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 to issue access tokens and manage users for the API service, or you can use external providers, such as PingFederate and PingDirectory.

PingOne token provider

If you use PingOne to issue tokens and manage users 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 providers

If you use external providers to issue tokens and manage users for the API service, you can define custom policies, but you can’t use built-in access control rules. You must configure your API gateway to validate access tokens and pass verified claims to PingOne in the inbound request.

When using an external token provider, PingOne Authorize relies on the API gateway for token validation and does not verify any matching claims.

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

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. For more information, see Deploying an API service.