PingAccess

Configuring OAuth authorization servers

Configure, modify, and edit the OAuth authorization servers in PingAccess.

Before you begin

If you plan to use Mutual TLS, modify the token provider to provide the mtls_endpoint_aliases object, with content defined by RFC-8705, on the OpenID Connect (OIDC) well-known configuration endpoint.

Steps

  1. Click Settings, then go to System > Token Provider > Common > OAuth Authorization Server.

  2. (Optional) In the Description field, enter a description for the authorization server.

  3. In the Targets field, enter one or more hostname:port pairs for the OAuth authorization server.

    1. (Optional) Click Add Target to add additional targets.

  4. In the Introspection Endpoint field, specify the OAuth endpoint through which the token introspection operation is accomplished.

    If you’ve configured a remote token access validator on your PingAccess application and try to remove the Introspection Endpoint or save without configuring it on the OAuth Authorization Server tab, you get the following error message:

    Introspection endpoint is required as there are applications that use remote token validation.

    Remove the remote access token validator before filling out your configuration on the OAuth Authorization Server tab.

  5. In the Token Endpoint field, enter the OAuth 2.0 Authorization Server’s token endpoint.

  6. In the Issuer Endpoint field, enter a valid relative path to the target authorization server’s issuer identifier to comply with RFC 7523.

    If Private Key JWT Audience is set to Issuer or Both, you must configure a value for this field.

  7. To record requests to the OAuth authorization server to the audit store, select the Audit checkbox.

  8. If the OAuth authorization server is expecting HTTPS connections, select the Secure option.

  9. In the Trusted Certificate Group list, select the group of certificates to use when authenticating to the OAuth authorization server.

    PingAccess requires that the certificate in use by the OAuth authorization server anchors to a certificate in the associated trusted certificate group.

  10. In the Client ID field, enter the unique identifier assigned when you created the PingAccess OAuth client within your OAuth authorization server.

  11. Select a Client Credentials Type, then provide the information required for the selected credential type.

    Choose from:

    • Secret: Enter the Client Secret assigned when you created the PingAccess OAuth client in the token provider.

    • Mutual TLS: Select a configured Key Pair to use for mutual TLS client authentication.

    • Private Key JWT: Select this option to use Private Key JSON web token (JWT). No additional information is required.

  12. In the Private Key JWT Audience list, select how to handle the audience claim in private key JWT OAuth client authentication. Possible values include:

    Audience Endpoint (default)

    Includes the token endpoint in the audience claim to preserve backwards compatibility with PingAccess 9.0 and earlier.

    Issuer (preferred)

    Includes the issuer endpoint in the audience claim to comply with RFC 7523.

    Both

    Both the issuer and token endpoints are included in the audience claim.

  13. (Optional) To retain token details for subsequent requests, select the Cache Tokens option.

    This option reduces communication between PingAccess and the OAuth authorization server.

  14. (Optional) To enter the number of seconds to cache the access token, select the Token Time To Live checkbox.

    A value of -1 means that there is no limit. This value should be less than the OAuth authorization server token lifetime.

  15. In the Subject Attribute Name field, enter the attribute that you want to use from the OAuth access token as the subject for auditing purposes.

    At runtime, the attribute’s value is used as the subject field in audit log entries for application programming interface (API) resources with policies that validate access tokens.

  16. To send the URI the user requested as the aud OAuth parameter for PingAccess to the OAuth 2.0 authorization server, select the Send Audience checkbox.

  17. To configure the connection to use a configured proxy, click Show Advanced Settings and select Use Proxy.

    You can find more information about creating proxies in Adding proxies.

  18. To configure OAuth 2.0 Demonstrating Proof of Possession (DPoP) settings, click Show Advanced Settings:

    1. In the DPoP Type list, select the level of DPoP support that you want to enable for access token validation:

      • Off (default): PingAccess doesn’t accept DPoP-bound access tokens, only bearer tokens.

      • Enabled: PingAccess accepts both bearer tokens and DPoP-bound access tokens.

      • Required: PingAccess doesn’t accept bearer tokens, only DPoP-bound access tokens.

    2. To require each DPoP proof to contain a nonce value during validation that was provided by PingAccess when the access token was created, per RFC 9449 section 9, select Require Nonce.

      This check box is cleared by default.

    3. In the DPoP Proof Lifetime (SEC.) field, enter the duration, in seconds, that a DPoP proof should be considered valid after it’s issued.

      As a security best practice, keep this value low and consistent with the DPoP implementation of your API client. The default value is 120 seconds.

  19. Click Save.

    If the node isn’t configured with a proxy, requests are made directly to the token provider.