Step-Up Authentication for Third-Party IdP Sign-Ins

If your app authenticates some users against a homegrown or third-party identity system rather than natively through Descope, you can still use those sign-ins to satisfy a step-up requirement. This matters when you're migrating users off a legacy auth system: you can sign a still-validated user into Descope for the first time and have that same sign-in count as step-up, so your app doesn't challenge them again right after.

The Problem This Solves

You can authenticate a user against your legacy system (for example, by validating an existing session cookie with a Generic HTTP Connector), then use a Generate JWT action to issue a matching Descope session for them without asking them to sign in again.

If that migration happens on a page that also requires step-up, like a sensitive account action, you want the resulting Descope JWT to carry step-up status from the start. Otherwise, your app's step-up check runs right after, finds no su claim on the token, and prompts the user to re-authenticate. You end up asking the same person to verify their identity twice in a row for one action.

How the Flow Works

1. Step Up action - Add the Step Up action near the start of the flow. This marks the flow as a step-up authentication, so any sign-in that completes later in the same flow issues a JWT with the su claim set to true.

2. Validate the user against your legacy system - Use a Generic HTTP Connector (or similar) to check the user's existing session or credentials against your old auth system, and set form.email or form.externalId from the result so Descope knows which login ID to match.

3. Generate JWT action - Add a Generate JWT / Sign In, Sign Up, or Sign Up or In with 3rd Party IdP action, depending on whether the user is expected to already exist in Descope. Because this action runs after the Step Up action, the JWT it issues includes su: true.

4. Token returned - The flow returns a Descope session token that reflects both a successful sign-in and a completed step-up, in one pass.

Key Points

• The su claim is added because of the flow-level step-up marking from the Step Up action, not because of any setting on the Generate JWT action itself. The Generate JWT action must run after a Step Up action in the same flow for its issued token to be stepped up.
• This works with any of the three Generate JWT actions (Sign In, Sign Up, or Sign Up or In with 3rd Party IdP).
• Your app can validate the result the same way it validates any other step-up: check for su: true on the session token. See Step-Up Validation.
• If you don't add a Step Up action to the flow, the Generate JWT action still issues a valid session token, just without the su claim.