WebAuthn key concepts

This describes some key concepts related to the APIs used to build your custom WebAuthn-based authentication solution.

Flows

WebAuthn APIs provide you the flexibility to implement different flows based on your needs—such as your use case, your technical requirements, and the user experience you'd like to provide your customers.

Each flow may include one or more of these characteristics:

  • Registration - Includes a WebAuthn credential registration
  • Authentication - Includes authentication using a WebAuthn credential

Users

This describes the relationship between WebAuthn credentials to users in your system and to Mosaic user identities.

Username

Each flow is bound to a specific user context, which is provided by a username. This username is tied to the WebAuthn credentials, and should correspond to a representation of the user in your system. For example, it can be their email, phone number, or another verifiable user identifier known to the user (like account ID). If username is used by a different authentication method (e.g., passwords), it should match the WebAuthn one.

The username is set upon credential registration, and can be provided for each authentication request. The username must correspond to WebAuthn credentials registered on the current device. Upon successful authentication, the username is returned in the ID token in a claim called webauthn_username.

Note

The username associated with WebAuthn credentials isn't reflected in the user profile, but the user can be found by user_id, external_user_id (if set), or any other alias you've set for the user (phone_number or email).

Verification

Unlike email or SMS-based authentication methods, WebAuthn registration doesn't implicitly verify that the user is who they say they are. For example, if a user is identified by email, an email OTP login will verify the user's email. WebAuthn credentials should only be registered to a user that has verified their identity. This can be done in different ways, depending on your use case (see Implement login scenarios).

Credentials

WebAuthn APIs can be used to register new credentials and authenticate with them. Credentials are bound to a specific user, Mosaic app and domain. This domain corresponds to the Relying Party ID (RP ID) that is pre-configured in the Admin Portal in your WebAuthn Authentication settings. Your settings also include the Relying Party origin, which must exactly match the origin of the WebAuthn API request. This origin must be HTTPS, must have a domain that matches the RP ID (even if it's a subdomain), and must include port (if relevant).

Upon successful WebAuthn authentication, a user access token is returned to your backend, which also include the user ID of the user in the Mosaic system, an external identifier of the user in your system (if set), and any other user alias you've set for this user (such as their email or phone number).