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. |
|
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
The step-up token that getMfaStepUpToken returned. |
|
Optional This is most useful with discoverable login and conditional mediation, because browsers typically allow only one |
|
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 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
redirectUriwith the authorization code. The promise resolves with an empty object just before the page navigates, so handle the result on the page that yourredirectUripoints 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
codeChallengethat you passed in the options: exchange the code from your backend at the/oauth/tokenendpoint, with your client secret or your own code verifier.
-
-
With the
web_messageresponse 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 setpopupMode. A flow that Purse Identity orchestrates, such as Hosted Pages, always redirects.
AuthResult object fields
| Field | Type | Description | ||
|---|---|---|---|---|
|
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 |
|||
|
The lifetime of the access token (in seconds).
|
|||
|
The type of token that is issued.
|
|||
|
The user’s newly-generated refresh token.
|
|||
|
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).
|
|||
|
The body of the ID token which outlines the claims. See ID token payload for more details.
|
|||
|
The authorization code received from the initial authorization call. |
|||
|
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. |
|||
|
The step up token needed to complete the stepup flow. |
|||
|
The Authentication Method Reference (
|
|||
|
The name of the social login provider used to log in.
|
|||
|
The access token from the social login provider.
|
ID token payload
The possible claims to assert about an authenticated user are outlined in the table below.
| Field | Type | Description | ||
|---|---|---|---|---|
|
The type of authentication used. allowed values:
|
|||
|
The birthdate of the profile, represented as an ISO 8601 |
|||
|
The primary email address of the profile. |
|||
|
True if the user’s e-mail address has been verified; otherwise false. |
|||
|
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
|
|||
|
The family name of the profile.
|
|||
|
The given name of the profile.
|
|||
|
The gender of the profile.
|
|||
|
The time (as a Unix timestamp) at which the JWT was issued. Example
|
|||
|
The issuer claim identifies the principal that issued the JWT. |
|||
|
UUID for payment authorization result object; used to track customer-initiated transactions and influence processing speed. |
|||
|
The profile’s language code in lowercase and country code in uppercase, separated by a dash (eg |
|||
|
The full name of the profile. |
|||
|
Whether the profile is new. |
|||
|
The subject claim that identifies the profile. |
|||
|
Identifies the recipients for which the JWT is intended. |
|||
|
The URL of one of the user’s profile pictures. This URL refers to an image file (PNG, JPEG, or GIF image file). |
|||
|
The URL of one of the userโs profile pages (usually a social providerโs page). |
|||
|
The time the profile’s information was last updated. |
|||
|
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
|
The promise rejects with Unsupported WebAuthn API when the browser doesn’t support WebAuthn.