achieveStepUpWithWebAuthn

client.achieveStepUpWithWebAuthn({
    stepUpToken: string,
    // Optional arguments
    signal: AbortSignal,
    trustDevice: boolean
})

About this command

Completes a step-up with a passkey that the user registered as a second factor.

Call it with the step-up token that getMfaStepUpToken returns, when the amr list contains webauthn. The browser asks the user to confirm with their passkey, and the SDK then sends the result to Purse Identity.

For the whole flow, see the Passkey as a second factor guide.
  • The WebAuthn feature must be enabled on your Purse Identity account.

  • Call this method in the same browser as getMfaStepUpToken. The SDK keeps the redirectUri and the response mode that you passed to getMfaStepUpToken with the step-up token, and reads them back here.

Examples

client
  .getMfaStepUpToken({
    options: {
      redirectUri: 'https://www.example.com/login/callback',
      responseType: 'code'
    },
    accessToken: 'eyJ0eXAiOiJKV1QiL...',
    action: 'stepup'
  })
  .then(stepUp => {
    // Continue only if the user can use a passkey as a second factor
    if (!stepUp.amr.includes('webauthn')) return

    // The browser asks the user to confirm with their passkey,
    // then navigates to the redirect URI with the authorization code
    return client.achieveStepUpWithWebAuthn({
      stepUpToken: stepUp.token
    })
  })
  .catch(err => console.error(err))

Parameters

stepUpToken string

The step-up token that getMfaStepUpToken returned.

signal AbortSignal

Optional AbortSignal used to cancel the WebAuthn ceremony.

This is most useful with discoverable login and conditional mediation, because browsers typically allow only one navigator.credentials.get() request at a time. Abort the pending autofill request before starting another credentials request (for example a modal passkey login or a password login).

trustDevice boolean

Whether to trust the device after the step-up.

Requires risk-based authentication. If risk-based authentication is disabled, leave this parameter out: the request fails if you pass it, even with false.

If you leave it out, the device isn’t trusted.

Response

Type: Promise<AuthResult>

How the promise resolves depends on the response mode that you passed to getMfaStepUpToken:

  • By default, Purse Identity redirects the page to your redirectUri with the authorization code. The promise resolves with an empty object just before the page navigates, so handle the result on the page that your redirectUri points to. Exchange the code depending on your client:

    • Public client, with the PKCE challenge generated by the SDK: call exchangeAuthorizationCodeWithPkce on that page. The SDK reads the code verifier that it stored.

    • Confidential client, or a codeChallenge that you passed in the options: exchange the code from your backend at the /oauth/token endpoint, with your client secret or your own code verifier.

  • With the web_message response mode (useWebMessage: true), the page doesn’t navigate. For a public client, the promise resolves with the authentication result. For a confidential client, it resolves with the authorization code, which your backend exchanges as above. This mode doesn’t apply when you set popupMode. A flow that Purse Identity orchestrates, such as Hosted Pages, always redirects.

AuthResult object fields

Field Type Description

accessToken

string

The user’s newly-generated access token.

This a security token that gives access to authorized resources without further identification. It is represented as a JSON Web Token (JWT).

If Forbid unverified identifiers login after signup is enabled and a user is unverified, the accessToken is not issued and the user is not redirected.

expiresIn

number

The lifetime of the access token (in seconds).

expiresIn always equals the access token lifetime set on your First-party Identity client in the Purse Identity Console.

tokenType

string

The type of token that is issued.

This is always Bearer.

refreshToken

string

The user’s newly-generated refresh token.

A refresh token is not present unless you are implementing the refresh token grant. This is only possible when the offline_access scope is requested.

idToken

string

The user’s newly-generated ID token. This is a security token that contains authentication claims about the user. It is represented as a JSON Web Token (JWT).

Claims are pieces of information made about a particular subject.

For example, ID tokens might contain a claim called name that makes the claim that the name of the user authenticating is "Nicole Dubois".

{
    "sub": "987654321",
    "name": "Nicole Dubois",
    ...
}

idTokenPayload

JSON

The body of the ID token which outlines the claims. See ID token payload for more details.

For a full list of claims, check out the JWT Claims Registry.

code

string

The authorization code received from the initial authorization call.

state

string

An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

stepUpToken

string

The step up token needed to complete the stepup flow.

amr

string

The Authentication Method Reference (amr). When using MFA, the mfa value must be present.

For more on amr values, see here.

providerName

string

The name of the social login provider used to log in.

Example

kakaotalk

This is only relevant for SLO and is not included in the auth response for other flows.

providerAccessToken

string

The access token from the social login provider.

Example

ya29.a0AbV…​YGo9wg0174

This is only relevant for SLO and is not included in the auth response for other flows.

ID token payload

The possible claims to assert about an authenticated user are outlined in the table below.

Field Type Description

authType

string

The type of authentication used.

allowed values:
  • password

  • phone_number_password

  • magic_link

  • sms

  • external

  • refresh

  • login_as

  • third_party

  • webauthn

birthdate

string

The birthdate of the profile, represented as an ISO 8601 YYYY-MM-DD format.

email

string

The primary email address of the profile.

emailVerified

boolean

True if the user’s e-mail address has been verified; otherwise false.

exp

number

The expiration time claim identifies the point in time (as a Unix timestamp) on or after which the JWT must not be accepted for processing.

Example
1704067201 # unix timestamp
Mon Jan 01 2024 00:00:01 GMT+0000 # corresponding actual date

familyName

string

The family name of the profile.

Also known as surname or last name.

givenName

string

The given name of the profile.

Also known as first name.

gender

string

The gender of the profile.

Currently allowed values are female, male and other.

iat

number

The time (as a Unix timestamp) at which the JWT was issued.

Example
1704067201 # unix timestamp
Mon Jan 01 2024 00:00:01 GMT+0000 # corresponding actual date

iss

string

The issuer claim identifies the principal that issued the JWT.

cico

string

UUID for payment authorization result object; used to track customer-initiated transactions and influence processing speed.

locale

string

The profile’s language code in lowercase and country code in uppercase, separated by a dash (eg en, fr-FR …​).

name

string

The full name of the profile.

newUser

boolean

Whether the profile is new.

sub

string

The subject claim that identifies the profile.

aud

string

Identifies the recipients for which the JWT is intended.

picture

string

The URL of one of the user’s profile pictures. This URL refers to an image file (PNG, JPEG, or GIF image file).

profile

string

The URL of one of the userโ€™s profile pages (usually a social providerโ€™s page).

updatedAt

string

The time the profile’s information was last updated.

auth_time

number

The time when end user authentication occurred. The time represents the first authentication of a given underlying session. This is represented as a Unix timestamp.

Example
1704067201 # unix timestamp
Mon Jan 01 2024 00:00:01 GMT+0000 # corresponding actual date

The promise rejects with Unsupported WebAuthn API when the browser doesn’t support WebAuthn.

AI Assistant

Confirm Deletion