PingOne

External OAuth servers in PingOne Authorize

Use tokens issued by external OAuth servers to secure your APIs through basic token validation and claims-based access control.

You can find details about how to add an external token source in Adding an external OAuth server in PingOne Authorize.

You can have up to 25 external OAuth servers in each PingOne environment. Learn more about PingOne Authorize limits in PingOne standard platform limits.

Token validation

When PingOne Authorize receives a request to access an API resource, it validates the access token to ensure the information in the token is trustworthy. This basic form of access control includes verifying the token’s signature, issuer, audience, and time-based claims.

PingOne Authorize makes sure that:

  • The iss claim matches one of the Issuers defined for the external OAuth server.

  • The aud claim matches the Audience defined for the API resource.

  • The nbf claim timestamp precedes the token validation time.

  • The exp claim timestamp is later than the token validation time, the iat value, and the nbf value.

  • The access token has a valid signature and was signed using trusted keys provided by the issuer.

If the token is valid, PingOne Authorize passes a request to the HTTP Access Policy service. As part of this process, PingOne Authorize maps parsed token claims to PingOne.API Access Management.Identity.Access Token built-in attributes you can use in custom policies.

Token validation provides only a basic level of access control for protected API resources. Use custom policies to secure your API resources with additional claims-based access control checks.

Access token requirements

PingOne Authorize can validate tokens that meet the following requirements.

JWT requirements

The bearer token must be:

  • A signed JSON Web Token (JWT)

  • Broadly compliant with RFC 9068

API Access management doesn’t support unsigned, encrypted, or reference (opaque) tokens.

Signing algorithms

The following asymmetric signing algorithms are supported:

  • ES256, ES384, ES512

  • RS256, RS384, RS512

Tokens that use symmetric signing algorithms, such as HS256, aren’t supported.

JWKS endpoint

To validate the token’s signature, PingOne Authorize uses public signing certificates published to a JSON Web Key Set (JWKS) endpoint or a JWKS document. The JWKS endpoint must:

  • Be available over HTTPS on the public internet

  • Support GET requests

  • Not require authentication or a custom trust server certificate

If JWKS responses don’t include the HTTP Cache-Control: max-age header, PingOne Authorize caches the responses for each external OAuth server for 60 minutes and continues token validation during signing key rotation.

If PingOne Authorize receives a token signed using a key ID not present in the cache, it makes a request to the JWKS endpoint.

Mandatory claims

The token must contain the following standard claims:

  • aud: Token recipient (audience)

  • exp: When the token will expire (expiration time)

  • iat: When the token was issued (issued at)

  • iss: Token source (issuer)

PingOne Authorize evaluates the nbf (not before) claim if it’s present, but this claim isn’t mandatory.

Claims-based access control

You can leverage claims from externally sourced tokens in custom policies. PingOne Authorize populates built-in attributes with claims from validated tokens. For example, if the token includes a sub claim, you can use the PingOne.API Access Management.Identity.Access Token.Subject attribute to resolve user identity information from an external directory and use it in custom policies.

Learn more in API Access Management attributes and Adding custom policies for API services and operations.

PingOne Authorize omits any access token claims with the p1 prefix from decision requests when the token comes from an external source.