PingOne

Troubleshooting external token sources in PingOne Authorize

Diagnose and fix common issues when using access tokens from external sources for API access control.

When PingOne Authorize rejects an access token from an external source, it returns a 401 (Unauthorized) response code to the API gateway. The response includes a WWW-authenticate HTTP response header with an error code and description that can help you determine why the token was rejected.

You can find general troubleshooting information in Troubleshooting API Access Management.

Check external OAuth server configuration

To ensure correct configuration of the external OAuth server, check settings in PingOne Authorize:

  1. Verify that the Issuers setting matches the iss claim in the access token.

  2. Verify that the JWKS URL or JWKS document points to public keys used to verify the token’s signature.

  3. If external OAuth server settings have been updated, ensure that any associated API services have been re-deployed.

Check the audit log

Examine the PingOne audit log for details about why the token was rejected. Check key fields in the HTTP Request Policy Evaluated event:

  • evaluationResult: Indicates the reason for failure, such as invalid audience or token expired.

  • externalOAuthServer: Identifies the external OAuth server’s name and ID, which helps you confirm that the correct configuration was used for validation.

Issuer mismatch

Problem: The iss (issuer) claim in the access token doesn’t match any of the Issuers configured for the external OAuth server.

Cause: The token was issued by a different token source than the one PingOne Authorize is configured to trust, or the issuer identifier contains a typo. The audit log will show that the token was rejected because of an issuer mismatch.

Solution:

  1. In the PingOne admin console, go to Authorization > External OAuth Servers and select the external OAuth server associated with your API Service.

  2. Verify the Issuers identifier exactly matches the iss claim in the access token. This is case-sensitive.

  3. If the values don’t match, update the Issuers identifier to correct the discrepancy.

  4. Save your changes and redeploy the associated API service.

Audience mismatch

Problem: The aud (audience) claim in the access token doesn’t match the Audience configured for the API service.

Cause: The token was issued for a different audience than the one expected by the API service, or the audience identifier contains a typo. The audit log will show that the token was rejected because of an audience mismatch.

Solution:

  1. In the PingOne admin console, go to Authorization > API Services and select the API service associated with the external OAuth server.

  2. Verify the Audience exactly matches the aud claim in the access token. This is case-sensitive.

  3. If the values don’t match, update the Audience to correct the discrepancy.

  4. Save your changes and redeploy the API service.

Expired or not-yet-active token

Problem: The access token is expired or not yet active.

Cause: The token’s exp (expiration) claim timestamp is earlier than the current time, or the nbf (not before) claim timestamp is later than the current time. The audit log will show that the token was rejected because it’s expired or not yet active.

Solution:

  1. Check the system clocks of both PingOne and the external token source to ensure they’re synchronized. A significant time difference can lead to rejection of valid tokens.

  2. If necessary, adjust the Clock Skew Tolerance setting for the external OAuth server to allow for minor time differences. Learn more in Adding an external OAuth server in PingOne Authorize.

  3. Ensure that API clients obtain new tokens before current tokens expire.

  4. If the token isn’t active yet, ensure that the token’s nbf claim timestamp is set correctly by the token issuer.

Invalid signature

Problem: The access token’s signature is invalid.

Cause: The token wasn’t signed using a trusted key, or the token was tampered with. The audit log will show that the token was rejected because of an invalid signature.

Solution:

  1. Verify that the JSON Web Key Set Method is correct for the token issuer:

    • If you’re using a JWKS URL, verify that the external OAuth server’s JWKS URL is correct and points to a valid JWKS endpoint provided by the token issuer.

    • If you’re using a JWKS document, verify that the external OAuth server’s JWKS setting is correct and matches the actual signing keys used by the token issuer.

      If your JWKS string exceeds the 16 KB size limit, reduce the size by removing keys that aren’t used by the external OAuth server to sign access tokens.

  2. Make sure the access token is a signed JWT and not an unsigned, encrypted, or reference (opaque) token.

  3. Ensure that the token was signed using one of the supported asymmetric signing algorithms: ES256, ES384, ES512, RS256, RS384, or RS512.

  4. If the token was issued recently, ensure that the JWKS endpoint has been updated with the latest public signing keys. Or, if you’re using a JWKS string, ensure that the document has been updated with the latest public signing keys.

  5. Ensure that the token hasn’t been tampered with or altered in any way.