PingOne

Step-up authentication for APIs

Step-up authentication enables you to require users to provide additional levels of authentication when they access sensitive API resources or perform high-risk actions.

Step-up authentication is also known as just-in-time authentication or route-based authentication. It allows your organization to reduce friction during the authentication experience while ensuring that sensitive resources are protected. For example, a bank might require only a basic level of authentication when customers view available banking products, but require an additional authentication method when they view their account balance or transaction history.

Step-up authentication has the following benefits:

  • Balances a frictionless authentication experience with the need for increased security

  • Limits MFA fatigue by asking for additional authentication only when it’s needed

  • Protects critical assets or high-risk resources that only certain users need to access

  • Reassures users that their sensitive data is safe

When to use step-up authentication

Use step-up authentication when you want to guarantee that users are always required to provide an additional authentication factor when they try to access sensitive data or perform high-risk actions.

Specific kinds of API resources can be more sensitive than others, such as salary data, health records, or premium content. Before you allow a client to access these resources, you can use step-up authentication to require that:

  • The user authenticated with a higher-level authentication policy

  • The user authenticated recently

How is step-up authentication different from MFA?

With MFA, users must always present two or more authentication factors to verify their identity, such as a password and a one-time passcode (OTP) sent to their device.

With step-up authentication, users are allowed to access certain resources with one level of authentication, while more sensitive resources are protected by an additional level of authentication. Higher-level authentication is required only when it’s needed.

You can learn more about authentication levels in NIST authenticator assurance levels.

How it works

Step-up authentication uses PingOne in combination with your API gateway to require higher-level authentication for sensitive resources. You define authentication policies for an application with DaVinci or PingOne SSO, then use PingOne API Access Management in conjunction with your API gateway to protect your sensitive resources.

The following diagram and steps represent a typical step-up authentication flow:

Diagram showing initial authorization, an additional prompt condition met, additional authorization required, and access granted or denied.

  1. A user accesses an application with a basic level of authentication.

    The authorization server issues an access token that the client application uses to request resources. For example:

    GET /secrets HTTP/1.1
Host: example.com
Authorization: Bearer eyJ0eX

    The access token includes claims related to authentication requirements:

    • acr: The name of the authentication policy used to satisfy the authentication event.

    • auth_time: The timestamp of the authentication event, expressed in epoch seconds.

  2. The user requests access to a sensitive resource, meeting a condition that requires additional authentication.

    The resource server checks the acr and auth_time claims in the client’s access token and determines that authentication requirements are not met. The resource server rejects the request and issues a challenge response. For example:

    HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
  error_description="A different authentication level is required",
  acr_values="strong_authentication_policy", max_age=300

    The challenge response includes the following details about authentication requirements:

    • insufficient_user_authentication error code: Tells the client that the user needs to reauthenticate.

    • acr_values: A list of acceptable authentication policies.

    • max_age: The allowable elapsed time in seconds since the last active authentication event associated with the access token.

  3. The user is prompted to reauthenticate with higher-level factors.

    • The client parses the challenge response. The error code indicates that the user needs to reauthenticate.

    • The client requests a new access token from the authorization server based on the acr_values and max_age provided in the challenge response. For example:

      GET /<envId>/as/authorize?client_id=<clientId>&scope=secret&response_type=code&redirect_uri=<redirectUri>&state=<state>&acr_values=strong_authentication_policy&max_age=300
Host: auth.pingone.com

    • The authorization server prompts the user to reauthenticate with the policy named in acr_values.

  4. The user reauthenticates.

    If authentication is successful, the authorization server issues a new access token that includes the necessary claims.

  5. If authentication is successful, the user requests access to the sensitive resource.

    • The client requests access to the sensitive resource with the new access token.

    • The resource server fulfills the request if the authentication policy matches the acr_values requested in the challenge response, or max_age is not exceeded.

    • The resource server denies the request if the authentication policy doesn’t match the acr_values requested in the challenge response, or max_age is exceeded.

You can learn more about authentication challenges and bearer token usage in RFC 9470 and RFC 6750.

When you use PingOne for step-up authentication, PingOne SSO acts as the authorization server. PingOne API Access Management acts on behalf of the resource server to enforce authentication requirements and issue challenge responses when requirements aren’t met.

Learn more in Setting up step-up authentication for APIs.