Interface: WebAuthnSdk
This is the main SDK object
Methods
init
▸ init(clientId, options?): Promise<void>
Creates a new WebAuthn SDK instance with your client context.
Throws
NotInitialized in case of invalid init params
Parameters
| Name | Type | Description |
|---|---|---|
clientId |
string |
Client ID for this application |
options? |
WebAuthnInitOptions |
WebAuthnInitOptions Additional environment configuration for the SDK operation |
Returns
Promise<void>
reset
▸ reset(): Promise<void>
Resets the SDK instance state but retains the configuration. This function should be called after every flow in order to prepare the SDK for the next flow (useful in Single Page Applications).
Returns
Promise<void>
isPlatformAuthenticatorSupported
▸ isPlatformAuthenticatorSupported(): Promise<boolean>
Indicates whether this browser supports WebAuthn, and has a platform authenticator
Returns
Promise<boolean>
isPasskeySupported
▸ isPasskeySupported(): Promise<boolean>
Indicates whether this browser supports passkey authentication
Returns
Promise<boolean>
getDeviceUsers
▸ getDeviceUsers(): Promise<DeviceUserInfo[]>
List of users that previously registered or authenticated using this device.
Returns
Promise<DeviceUserInfo[]>
List of usernames, indicating the current user (last user to authenticate or register). If there are no device users, an empty list is returned
prepareWebauthnRegistration
▸ prepareWebauthnRegistration(username, displayName?, authSessionId?): Promise<void>
Obtains the registration challenge from the Mosaic Service, and stores the response locally to be used by executeWebauthnRegistration. This allows reducing latency when registration is requested. To provide the best experience, this should be called as soon as the username is known. If the registration does not occur in a cross device flow, a secure context should be established using an authentication session which is obtained from a backend API call to the Mosaic Service (see Auth Session APIs).
In case of failure, the promise will resolve to an SdkRejection.
Throws
Throws
Parameters
| Name | Type | Description |
|---|---|---|
username |
string |
Username for the registering account. |
displayName? |
string |
Display name for this registered credential. Default is the username. |
authSessionId? |
string |
ID of the authentication session, returned upon creation (via backend API). |
Returns
Promise<void>
executeWebauthnRegistration
▸ executeWebauthnRegistration(allowCrossPlatformAuthenticators?, registerAsDiscoverable?): Promise<string>
Invokes a WebAuthn credential registration, including prompting the user for biometrics. This must be called only after calling prepareWebauthnRegistration to obtain the server challenge.
If registration is completed successfully, this call will return a promise that resolves to an authorization code, which can be used to obtain user tokens. If it fails, an SdkRejection will be returned instead.
Throws
Throws
UserCanceledWebAuthnRegistration
Throws
Throws
Parameters
| Name | Type | Description |
|---|---|---|
allowCrossPlatformAuthenticators? |
boolean |
Allow registration using cross-platform authenticators, such as a USB security key or a different device. If enabled, cross-device authentication flows can be performed using the native browser experience (via QR code). default: false |
registerAsDiscoverable? |
boolean |
Must be set to true to register credentials as passkeys when supported (except for Apple devices, which always register credentials as passkeys). default: false |
Returns
Promise<string>
Authorization code to exchange for user tokens
prepareWebauthnAuthentication
▸ prepareWebauthnAuthentication(username?, approvalData?, redirectUri?): Promise<void>
Obtains the authentication challenge from the Mosaic Service, and stores the response locally to be used by executeWebauthnAuthentication. This allows reducing latency when authentication is requested. To provide the best experience, this should be called as soon as possible.
This call must be invoked for a registered user. It is invoked on the last user that logged in or registered, unless you specify a different user in the request (for example, when explicitly switching to a different user). If the target user is not registered or in case of any other failure, an SdkRejection will be returned.
Throws
Throws
AuthenticationFailed in case of API call failure to startWebauthnAuthentication
Throws
InvalidAuthSession in case of API call failure to startRestrictedSession
Throws
Parameters
| Name | Type | Description |
|---|---|---|
username? |
string |
Username for the authenticating account. Only needed if switching to another registered user. Otherwise, the call is processed using the current user (as indicated by getDeviceUsers). |
approvalData? |
ApprovalData |
Flat object that describes the data to sign for approval flows. It should be presented to the user to approve before they authenticate, and will be returned in the ID token where it should be validated against this parameter. Valid data can only include up to 10 keys, and characters that are alphanumeric, period, underscore or hyphen. It can also be passed hashed to avoid exposing potentially sensitive data in a client-side request. |
redirectUri? |
string |
URI used to complete the WebAuthn flow. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal. If empty, the first redirect URI in the allowed redirect URIs list will be selected. |
Returns
Promise<void>
executeWebauthnAuthentication
▸ executeWebauthnAuthentication(): Promise<string>
Invokes a WebAuthn authentication, including prompting the user for biometrics. This must be called only after calling prepareWebauthnAuthentication to obtain the server challenge.
If authentication is completed successfully, this call will return a promise that resolves to an authorization code, which can be used to obtain user tokens. If it fails, an SdkRejection will be returned instead.
Throws
Throws
Throws
AuthenticationFailed in case of API call failure to completeWebauthnAuthentication
Returns
Promise<string>
Authorization code to exchange for user tokens
preparePasskeyAuthentication
▸ preparePasskeyAuthentication(approvalData?, redirectUri?): Promise<void>
Obtains Passkey WebAuthn authentication challenge from the Mosaic Service, and stores the response locally to be used by executePasskeyAuthentication. This allows reducing latency when authentication is requested. To provide the best experience, this should be called as soon as possible. This call must be invoked for a user with registered passkey credentials.
If the target user is not registered or in case of any other failure, an SdkRejection will be returned.
Throws
Throws
InvalidAuthSession in case of API call failure to startRestrictedSession
Throws
Parameters
| Name | Type | Description |
|---|---|---|
approvalData? |
ApprovalData |
Flat object that describes the data to sign for approval flows. It should be presented to the user to approve before they authenticate, and will be returned in the ID token where it should be validated against this parameter. Valid data can only include up to 10 keys, and characters that are alphanumeric, period, underscore or hyphen. It can also be passed hashed to avoid exposing potentially sensitive data in a client-side request. |
redirectUri? |
string |
URI to redirect to upon completion of the WebAuthn flow. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal. If this parameter remains empty, the first redirect URI in the allowed redirect URIs list will be selected. |
Returns
Promise<void>
executePasskeyAuthentication
▸ executePasskeyAuthentication(passkeysMediationType?): Promise<string>
Invokes a Passkey WebAuthn authentication, including prompting the user to select from a list of registered credentials, and then prompting the user for biometrics. The credentials list can be displayed either using autofill or the native browser modal. To display the credentials list using autofill, the autocomplete="username webauthn" attribute must be defined on the username input box of the authentication page
This must be called only after calling preparePasskeyAuthentication to obtain the server challenge.
If authentication is completed successfully, this call will return a promise that resolves to an authorization code, which can be used to obtain user tokens. If it fails, an SdkRejection will be returned instead.
Throws
Throws
Throws
AuthenticationFailed in case of API call failure to completePasskeyAuthentication
Throws
Throws
Parameters
| Name | Type | Description |
|---|---|---|
passkeysMediationType? |
PasskeysMediationType |
Indication of the display method of the passkeys list. default: InputAutofill |
Returns
Promise<string>
Authorization code to exchange for user tokens
abortPasskeyAuthentication
▸ abortPasskeyAuthentication(): void
Aborts a Passkey WebAuthn authentication. This method should be called after the passkey autofill is dismissed in order to be able to query existing passkeys once again.
Returns
void
startCrossDeviceFlow
▸ startCrossDeviceFlow(handlers, bindingMessage?, approvalData?, redirectUri?): Promise<CrossDeviceController>
Initializes a cross device flow, such as when users request to login to a desktop using their mobile device. Once invoked, the SDK will start listening for events occuring on the other device, and calls your handlers when a state change is detected.
This call returns a promise that resolves to a CrossDeviceController object, which allows you to stop listening to events and includes the authSessionId which is used when attaching another device to the flow. If it fails, an SdkRejection will be returned instead.
Throws
Throws
Parameters
| Name | Type | Description |
|---|---|---|
handlers |
CrossDeviceFlowHandlers |
CrossDeviceFlowHandlers an instance that contains your handlers for cross device events. For example, these handlers may update the UI or any other relevant application state. Handlers should return 'true' for polling to continue, and 'false' otherwise. |
bindingMessage? |
string |
Recommended for securing cross-device flows. If provided, this message will be transferred to the authenticating device (via the attachDevice call) to display to the end user. The token will also contain this message to allow checking for tampering. |
approvalData? |
ApprovalData |
Flat object that describes the data to sign for approval flows. It should be presented to the user to approve before they authenticate, and will be returned in the ID token where it should be validated against this parameter. Valid data can only include up to 10 keys, and characters that are alphanumeric, period, underscore or hyphen. It can also be passed hashed to avoid exposing potentially sensitive data in a client-side request. |
redirectUri? |
string |
URI used to complete the WebAuthn flow. This URI must also be configured as an allowed redirect URI in the Mosaic Admin Portal. If empty, the first redirect URI in the allowed redirect URIs list will be selected. |
Returns
Promise<CrossDeviceController>
CrossDeviceController - Object that allows you to stop the event loop, and obtain the authSessionId
attachDevice
▸ attachDevice(authSessionId): Promise<CrossDeviceBindingInfo>
Indicates when a session is accepted on another device in cross-device flows.
If successful, this call returns a promise that resolves to info about the originating device. This info will include the binding message provided in startCrossDeviceFlow, which should be displayed to the end user to help prevent phishing. In case of failure, the promise will resolve to an SdkRejection.
Throws
Parameters
| Name | Type | Description |
|---|---|---|
authSessionId |
string |
ID of the authentication session, as obtained from the CrossDeviceController on the originating device |
Returns
Promise<CrossDeviceBindingInfo>
Info about the originating device, and the binding message.
detachDevice
▸ detachDevice(): Promise<void>
Indicates when a session is no longer in use on another device in cross-device flows. In case of failure, the promise will resolve to an SdkRejection.
Throws
Throws
InvalidAuthSession when called on a device that was never attached with attachDevice before.
Returns
Promise<void>
getDefaultPaths
▸ getDefaultPaths(): WebauthnApis
Returns the URL paths for invoking Mosaic APIs, which are used by default by the SDK unless alternate paths are configured.
Returns
getApiPaths
▸ getApiPaths(): WebauthnApis
Returns the configured API URL paths.