PingAuthorize

Setting up step-up authentication for APIs

Use step-up authentication in applications that require stronger authentication methods for access to sensitive resources.

To access an API resource, applications provide an access token. Step-up authentication uses the acr claim in the access token to ensure that users authenticate with a higher level of assurance when they access a sensitive API resource and the auth_time claim in the access token to ensure they’ve authenticated recently. When an access token doesn’t meet these requirements, PingAuthorize can challenge the client to obtain a stronger token. Learn more about step-up authentication.

To support step-up authentication, configure your authorization server to issue access tokens that include the user’s authentication context. PingAuthorize relies on the acr and auth_time claims to evaluate whether stronger authentication is required. If these claims are missing, PingAuthorize can’t determine the authentication strength and won’t trigger a step-up challenge.

Complete these high-level steps to set up step-up authentication:

Steps

  1. Define API external servers to represent your protected resource servers.

  2. Define Gateway or Sideband API endpoints to represent your protected resources.

  3. Create policies using the following generated request attributes:

    • authentication_time

    • authentication_age

    • authentication_policy

    Learn more about these attributes in API security gateway policy request attributes and Sideband API policy request attributes.

  4. Attach the Auth Challenge statement template to your policies and edit the payload to reflect your authentication requirements.

  5. Commit your updates and deploy your policies.

Next steps

Configure your client application to handle 401 challenge responses that specify authentication policy (acr_values) and maximum authentication age (max_age) requirements. Your application should parse the challenge response, acquire a new access token that satisfies the requirements, and retry the request with that token.

Avoid retry loops. If the client repeatedly tries the same request with an insufficient token, PingAuthorize will continue to deny the request. Make sure the client upgrades the authentication context or stops retrying when receiving a step-up challenge.