PingOne

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 that they’ve authenticated recently. Learn more about step-up authentication for APIs.

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

Before you begin

To set up step-up authentication, you’ll need:

  • An API gateway that’s integrated with PingOne Authorize. Learn more in PingOne Authorize API gateway integrations.

  • A PingOne environment that includes the PingOne SSO and PingOne Authorize services.

  • If you’re using DaVinci authentication policies, your environment must include DaVinci.

Steps

  1. Register your application in PingOne.

    The Application Type must be OIDC Web App, Native, or Single-Page. Step-up authentication isn’t supported for client applications that use the SAML or WS-Fed protocols.

  2. Add the authentication policies you want to use for identity verification.

    Ensure that you have policies for basic authentication and for higher levels, such as MFA. You can use DaVinci or PingOne policies. Learn more in:

  3. Assign authentication policies to your application.

    You can assign either DaVinci or PingOne policies to your application, but not both types at the same time.

  4. Add an API service to register your protected API resources in PingOne.

    If you’ll use custom policies for step-up authentication instead of basic rules, make sure that you enable custom policies for the API service.

  5. Define API operations with basic rules for authentication policies and time since last authentication.

  6. Deploy the API service.

Next steps

Configure your client application to handle 401 challenge responses with authentication policy (acr_values) and maximum authentication age (max_age) requirements. Your application should parse the challenge response, construct an appropriate OAuth 2.0 request, then try again with the new access token.

Avoid getting caught in a loop if requests are repeatedly denied when authentication requirements aren’t met.