PingOne

Adding an external OAuth server in PingOne Authorize

Add an external OAuth server to enable PingOne Authorize to validate access tokens issued by external token sources.

You can add up to 25 external OAuth servers in each environment and assign the same external OAuth server to multiple API services.

Before you begin

  • Ensure that the external OAuth server issues access tokens that meet API Access Management requirements. Learn more in External OAuth servers.

  • In the system that issues tokens, create an OAuth 2.0 client application.

    You’ll need the following information from the token issuer:

    • Token issuer identifier

    • JWKS endpoint URI or JWKS document

    • Token audience

Steps

  1. In the PingOne admin console, go to Authorization > External OAuth Servers.

  2. Click the icon next to External OAuth Servers to add an external OAuth server.

  3. Enter a Name that identifies the external OAuth server.

    Each external OAuth server in the environment must have a unique name of up to 256 characters.

  4. (Optional) Enter a Description of the external OAuth server’s purpose.

  5. In Issuers, enter the token issuer identifier.

    Screen capture showing the OAuth server Name, Description, Issuers, JWKS URL, and Clock Skew Tolerance fields in the Add External OAuth Server panel.
    Example

    In PingOne Advanced Identity Cloud, you can use the /oauth2/realms/root/.well-known/openid-configuration endpoint to identify the issuer. For example, a PingAM issuer identifier might be https://example.com:8443/am/oauth2/realms/root/realms/alpha. Learn more in Access the keys exposed by the JWK URI endpoint in the PingAM documentation.

  6. (Optional) To add additional issuers, click + Add Issuer.

  7. In the JSON Web Key Set Method section, select the method PingOne Authorize uses to retrieve public keys for JWT signature verification.

    Choose from:

    • JWKS URL: Enter the JSON Web Key Set Uniform Resource Identifier address in the JWKS URL field.

      Example

      In PingOne Advanced Identity Cloud, you can use the well-known endpoint mentioned in step 5 to identify the JWKS URL. For example, a PingAM JWKS URL might be https://example.com:8443/am/oauth2/realms/root/realms/alpha/connect/jwk_uri.

    • JWKS: Paste the contents of a JWKS document in the JWKS field. The JWKS document contains the public keys the OAuth server uses to sign its JWTs.

  8. Enter a Clock Skew Tolerance value, or use the arrows to increase or decrease the value.

    Clock skew accounts for small time differences between PingOne and the external OAuth server’s system clocks. When validating time-based token claims, such as nbf (not before) and exp (expires), PingOne Authorize allows a time difference up to the tolerance value.

    If PingOne Authorize frequently rejects valid tokens, consider increasing the clock skew tolerance. However, a higher tolerance can compromise security by allowing tokens that are already expired or aren’t valid yet.

  9. Click Save.

Next steps

Associate the external OAuth server with an API service. Learn more in Defining your API in PingOne Authorize.

Whenever you update external OAuth server settings, you must deploy each API service associated with the OAuth server.