Struct Webauthn

pub struct Webauthn { /* private fields */ }

An instance of a Webauthn site. This is the main point of interaction for registering and authenticating credentials for users. Depending on your needs, you’ll want to allow users to register and authenticate with different kinds of authenticators.

I just want to replace passwords with strong cryptographic authentication, and I don’t have other requirements

You should use start_passkey_registration

I want to replace passwords with strong multi-factor cryptographic authentication, limited to a known set of controlled and trusted authenticator types

This type requires attestation enabled as the current form of the Attestation CA List may change in the future.

You should use start_attested_passkey_registration

I want users to have their identities stored on their devices, and for them to authenticate with strong multi-factor cryptographic authentication limited to a known set of trusted authenticator types

This authenticator type consumes limited storage space on users’ authenticators, and may result in failures or device bricking. You MUST only use it in tightly controlled environments where you supply devices to your users.

You should use start_attested_resident_key_registration (still in development, requires resident-key-support feature)

I want a security token along with an external password to create multi-factor authentication

If possible, consider start_passkey_registration OR start_attested_passkey_registration instead - it’s likely to provide a better user experience over security keys as MFA!

If you really want a security key, you should use start_securitykey_registration

Implementations

impl Webauthn

pub fn get_allowed_origins(&self) -> &[Url]

Get the currently configured origins

pub fn start_passkey_registration( &self, user_unique_id: Uuid, user_name: &str, user_display_name: &str, exclude_credentials: Option<Vec<CredentialID>>, ) -> WebauthnResult<(CreationChallengeResponse, PasskeyRegistration)>

Initiate the registration of a new passkey for a user. A passkey is any cryptographic authenticator which internally verifies the user’s identity. As these are self contained multifactor authenticators, they are far stronger than a password or email-reset link. Due to how webauthn is designed these authentications are unable to be phished.

Some examples of passkeys include Yubikeys, TouchID, FaceID, Windows Hello and others.

The keys may exist and ‘roam’ between multiple devices. For example, Apple allows Passkeys to sync between devices owned by the same Apple account. This can affect your risk model related to these credentials, but generally in most cases passkeys are better than passwords!

You should NOT pair this authentication with any other factor. A passkey will always enforce user-verification (MFA) removing the need for other factors.

user_unique_id may be stored in the authenticator. This may allow the credential to identify the user during certain client side work flows.

user_name and user_display_name may be stored in the authenticator. user_name is a friendly account name such as “claire@example.com”. user_display_name is the persons chosen way to be identified such as “Claire”. Both can change at any time on the client side, and MUST NOT be used as primary keys. They are not present in authentication, these are only present to allow client facing work flows to display human friendly identifiers.

exclude_credentials ensures that a set of credentials may not participate in this registration. You should provide the list of credentials that are already registered to this user’s account to prevent duplicate credential registrations. These credentials can be from different authenticator classes since we only require the CredentialID

Returns

This function returns a CreationChallengeResponse which you must serialise to json and send to the user agent (e.g. a browser) for it to conduct the registration. You must persist on the server the PasskeyRegistration which contains the state of this registration attempt and is paired to the CreationChallengeResponse.

Finally you need to call finish_passkey_registration to complete the registration.

WARNING ⚠️ YOU MUST STORE THE PasskeyRegistration VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

// you must store this user's unique id with the account. Alternatelly you can
// use an existed UUID source.
let user_unique_id = Uuid::new_v4();

// Initiate a basic registration flow, allowing any cryptograhpic authenticator to proceed.
let (ccr, skr) = webauthn
    .start_passkey_registration(
        user_unique_id,
        "claire",
        "Claire",
        None, // No other credentials are registered yet.
    )
    .expect("Failed to start registration.");

pub fn start_google_passkey_in_google_password_manager_only_registration( &self, user_unique_id: Uuid, user_name: &str, user_display_name: &str, exclude_credentials: Option<Vec<CredentialID>>, ) -> WebauthnResult<(CreationChallengeResponse, PasskeyRegistration)>

Available on crate feature workaround-google-passkey-specific-issues only.

Initiate the registration of a ‘Google Passkey stored in Google Password Manager’ on an Android device with GMS Core.

This function is required as Android’s support for Webauthn/Passkeys is broken and does not correctly perform authenticator selection for the user. Instead of Android correctly presenting the choice to users to select between a security key, or a ‘Google Passkey stored in Google Password Manager’, Android expects the Relying Party to pre-select this and send a correct set of options for either a security key or a ‘Google Passkey stored in Google Password Manager’.

If you choose to use this function you MUST ensure that the device you are contacting is an Android device with GMS Core, and you MUST provide the user the choice on your site ahead of time to choose between a security key / screen unlock (triggered by start_passkey_registration) or a ‘Google Passkey stored in Google Password Manager’ (triggered by this function).

pub fn finish_passkey_registration( &self, reg: &RegisterPublicKeyCredential, state: &PasskeyRegistration, ) -> WebauthnResult<Passkey>

Complete the registration of the credential. The user agent (e.g. a browser) will return the data of RegisterPublicKeyCredential, and the server provides its paired PasskeyRegistration. The details of the Authenticator based on the registration parameters are asserted.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

The returned Passkey must be associated to the users account, and is used for future authentications via start_passkey_authentication.

You MUST assert that the registered CredentialID has not previously been registered. to any other account.

pub fn start_passkey_authentication( &self, creds: &[Passkey], ) -> WebauthnResult<(RequestChallengeResponse, PasskeyAuthentication)>

Given a set of Passkey’s, begin an authentication of the user. This returns a RequestChallengeResponse, which should be serialised to json and sent to the user agent (e.g. a browser). The server must persist the PasskeyAuthentication state as it is paired to the RequestChallengeResponse and required to complete the authentication.

Finally you need to call finish_passkey_authentication to complete the authentication.

WARNING ⚠️ YOU MUST STORE THE PasskeyAuthentication VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

pub fn finish_passkey_authentication( &self, reg: &PublicKeyCredential, state: &PasskeyAuthentication, ) -> WebauthnResult<AuthenticationResult>

Given the PublicKeyCredential returned by the user agent (e.g. a browser), and the stored PasskeyAuthentication complete the authentication of the user.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

On success, AuthenticationResult is returned which contains some details of the Authentication process.

As per https://www.w3.org/TR/webauthn-3/#sctn-verifying-assertion 21:

If the Credential Counter is greater than 0 you MUST assert that the counter is greater than the stored counter. If the counter is equal or less than this MAY indicate a cloned credential and you SHOULD invalidate and reject that credential as a result.

From this AuthenticationResult you should update the Credential’s Counter value if it is valid per the above check. If you wish you may use the content of the AuthenticationResult for extended validations (such as the presence of the user verification flag).

pub fn start_securitykey_registration( &self, user_unique_id: Uuid, user_name: &str, user_display_name: &str, exclude_credentials: Option<Vec<CredentialID>>, attestation_ca_list: Option<AttestationCaList>, ui_hint_authenticator_attachment: Option<AuthenticatorAttachment>, ) -> WebauthnResult<(CreationChallengeResponse, SecurityKeyRegistration)>

Initiate the registration of a new security key for a user. A security key is any cryptographic authenticator acting as a single factor of authentication to supplement a password or some other authentication factor.

Some examples of security keys include Yubikeys, Feitian ePass, and others.

We don’t recommend this over Passkey or AttestedPasskey, as today in Webauthn most devices due to their construction require userVerification to be maintained for user trust. What this means is that most users will require a password, their security key, and a pin or biometric on the security key for a total of three factors. This adds friction to the user experience but is required due to a consistency flaw in CTAP2.0 and newer devices. Since the user already needs a pin or biometrics, why not just use the device as a self contained MFA?

You MUST pair this authentication with another factor. A security key may opportunistically allow and enforce user-verification (MFA), but this is NOT guaranteed.

user_unique_id may be stored in the authenticator. This may allow the credential to identify the user during certain client side work flows.

user_name and user_display_name may be stored in the authenticator. user_name is a friendly account name such as “claire@example.com”. user_display_name is the persons chosen way to be identified such as “Claire”. Both can change at any time on the client side, and MUST NOT be used as primary keys. They may not be present in authentication, these are only present to allow client work flows to display human friendly identifiers.

exclude_credentials ensures that a set of credentials may not participate in this registration. You should provide the list of credentials that are already registered to this user’s account to prevent duplicate credential registrations.

attestation_ca_list contains an optional list of Root CA certificates of authenticator manufacturers that you wish to trust. For example, if you want to only allow Yubikeys on your site, then you can provide the Yubico Root CA in this list, to validate that all registered devices are manufactured by Yubico.

Extensions may ONLY be accessed if an attestation_ca_list is provided, else they ARE NOT trusted.

Returns

This function returns a CreationChallengeResponse which you must serialise to json and send to the user agent (e.g. a browser) for it to conduct the registration. You must persist on the server the SecurityKeyRegistration which contains the state of this registration attempt and is paired to the CreationChallengeResponse.

Finally you need to call finish_securitykey_registration to complete the registration.

WARNING ⚠️ YOU MUST STORE THE SecurityKeyRegistration VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

// you must store this user's unique id with the account. Alternatelly you can
// use an existed UUID source.
let user_unique_id = Uuid::new_v4();

// Initiate a basic registration flow, allowing any cryptograhpic authenticator to proceed.
let (ccr, skr) = webauthn
    .start_securitykey_registration(
        user_unique_id,
        "claire",
        "Claire",
        None,
        None,
        None,
    )
    .expect("Failed to start registration.");

// Initiate a basic registration flow, hinting that the device is probably roaming (i.e. a usb),
// but it could have any attachement in reality
let (ccr, skr) = webauthn
    .start_securitykey_registration(
        Uuid::new_v4(),
        "claire",
        "Claire",
        None,
        None,
        Some(AuthenticatorAttachment::CrossPlatform),
    )
    .expect("Failed to start registration.");

// Only allow credentials from manufacturers that are trusted and part of the webauthn-rs
// strict "high quality" list.

use webauthn_rs_device_catalog::Data;
let device_catalog = Data::strict();

let attestation_ca_list = (&device_catalog)
    .try_into()
    .expect("Failed to build attestation ca list");

let (ccr, skr) = webauthn
    .start_securitykey_registration(
        Uuid::new_v4(),
        "claire",
        "Claire",
        None,
        Some(attestation_ca_list),
        None,
    )
    .expect("Failed to start registration.");

pub fn finish_securitykey_registration( &self, reg: &RegisterPublicKeyCredential, state: &SecurityKeyRegistration, ) -> WebauthnResult<SecurityKey>

Complete the registration of the credential. The user agent (e.g. a browser) will return the data of RegisterPublicKeyCredential, and the server provides its paired SecurityKeyRegistration. The details of the Authenticator based on the registration parameters are asserted.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

The returned SecurityKey must be associated to the users account, and is used for future authentications via (start_securitykey_authentication)crate::Webauthn::start_securitykey_authentication.

You MUST assert that the registered CredentialID has not previously been registered. to any other account.

Verifying specific device models

If you wish to assert a specific type of device model is in use, you can inspect the SecurityKey attestation() and its associated metadata. You can use this to check for specific device aaguids for example.

pub fn start_securitykey_authentication( &self, creds: &[SecurityKey], ) -> WebauthnResult<(RequestChallengeResponse, SecurityKeyAuthentication)>

Given a set of SecurityKey, begin an authentication of the user. This returns a RequestChallengeResponse, which should be serialised to json and sent to the user agent (e.g. a browser). The server must persist the SecurityKeyAuthentication state as it is paired to the RequestChallengeResponse and required to complete the authentication.

Finally you need to call finish_securitykey_authentication to complete the authentication.

WARNING ⚠️ YOU MUST STORE THE SecurityKeyAuthentication VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

pub fn finish_securitykey_authentication( &self, reg: &PublicKeyCredential, state: &SecurityKeyAuthentication, ) -> WebauthnResult<AuthenticationResult>

Given the PublicKeyCredential returned by the user agent (e.g. a browser), and the stored SecurityKeyAuthentication complete the authentication of the user.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

On success, AuthenticationResult is returned which contains some details of the Authentication process.

You should use SecurityKey::update_credential on the returned AuthenticationResult and ensure it is persisted.

impl Webauthn

pub fn start_attested_passkey_registration( &self, user_unique_id: Uuid, user_name: &str, user_display_name: &str, exclude_credentials: Option<Vec<CredentialID>>, attestation_ca_list: AttestationCaList, ui_hint_authenticator_attachment: Option<AuthenticatorAttachment>, ) -> WebauthnResult<(CreationChallengeResponse, AttestedPasskeyRegistration)>

Available on crate feature attestation only.

Initiate the registration of a new attested_passkey key for a user. A attested_passkey key is a cryptographic authenticator that is a self-contained multifactor authenticator. This means that the device (such as a yubikey) verifies the user is who they say they are via a PIN, biometric or other factor. Only if this verification passes, is the signature released and provided.

As a result, the server only requires this attested_passkey key to authenticate the user and assert their identity. Because of this reliance on the authenticator, attestation of the authenticator and its properties is strongly recommended.

The primary difference to a passkey, is that these credentials must provide an attestation certificate which will be cryptographically validated to strictly enforce that only certain devices may be registered.

This attestation requires that private key material is bound to a single hardware authenticator, and cannot be copied or moved out of it. At present, all widely deployed Hybrid authenticators (Apple iCloud Keychain and Google Passkeys in Google Password Manager) are synchronised authenticators which can roam between multiple devices, and so can never be attested.

As of webauthn-rs v0.5.0, this creates a registration challenge with credential selection hints that only use ClientDevice or SecurityKey devices, so a user-agent supporting Webauthn L3 won’t offer to use Hybrid credentials. On user-agents not supporting Webauthn L3, and on older versions of webauthn-rs, user-agents would show a QR code and a user could attempt to register a Hybrid authenticator, but it would always fail at the end – which is a frustrating user experience!

You should recommend to the user to register multiple attested_passkey keys to their account on separate devices so that they have fall back authentication in the case of device failure or loss.

You should have a workflow that allows a user to register new devices without a need to register other factors. For example, allow a QR code that can be scanned from a phone, or a one-time link that can be copied to the device.

You must have a recovery workflow in case all devices are lost or destroyed.

user_unique_id may be stored in the authenticator. This may allow the credential to identify the user during certain client side work flows.

user_name and user_display_name may be stored in the authenticator. user_name is a friendly account name such as “claire@example.com”. user_display_name is the persons chosen way to be identified such as “Claire”. Both can change at any time on the client side, and MUST NOT be used as primary keys. They may not be present in authentication, these are only present to allow client work flows to display human friendly identifiers.

exclude_credentials ensures that a set of credentials may not participate in this registration. You should provide the list of credentials that are already registered to this user’s account to prevent duplicate credential registrations.

attestation_ca_list contains a required list of Root CA certificates of authenticator manufacturers that you wish to trust. For example, if you want to only allow Yubikeys on your site, then you can provide the Yubico Root CA in this list, to validate that all registered devices are manufactured by Yubico.

ui_hint_authenticator_attachment provides a UX/UI hint to the browser about the types of credentials that could be used in this registration. If set to None all authenticator attachement classes are valid. If set to Platform, only authenticators that are part of the device are used such as a TPM or TouchId. If set to Cross-Platform, only devices that are removable from the device can be used such as yubikeys.

Returns

This function returns a CreationChallengeResponse which you must serialise to json and send to the user agent (e.g. a browser) for it to conduct the registration. You must persist on the server the AttestedPasskeyRegistration which contains the state of this registration attempt and is paired to the CreationChallengeResponse.

Finally you need to call finish_attested_passkey_registration to complete the registration.

WARNING ⚠️ YOU MUST STORE THE AttestedPasskeyRegistration VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

use webauthn_rs_device_catalog::Data;
// you must store this user's unique id with the account. Alternatively you can
// use an existed UUID source.
let user_unique_id = Uuid::new_v4();

// Create a device catalog reference that contains a list of known high quality authenticators
let device_catalog = Data::all_known_devices();

let attestation_ca_list = (&device_catalog)
    .try_into()
    .expect("Failed to build attestation ca list");

// Initiate a basic registration flow, allowing any attested cryptograhpic authenticator to proceed.
// Hint (but do not enforce) that we prefer this to be a token/key like a yubikey.
// To enforce this you can validate the properties of the returned device aaguid.
let (ccr, skr) = webauthn
    .start_attested_passkey_registration(
        user_unique_id,
        "claire",
        "Claire",
        None,
        attestation_ca_list,
        Some(AuthenticatorAttachment::CrossPlatform),
    )
    .expect("Failed to start registration.");

// Only allow credentials from manufacturers that are trusted and part of the webauthn-rs
// strict "high quality" list.
// Hint (but do not enforce) that we prefer this to be a device like TouchID.
// To enforce this you can validate the attestation ca used along with the returned device aaguid

let device_catalog = Data::strict();

let attestation_ca_list = (&device_catalog)
    .try_into()
    .expect("Failed to build attestation ca list");

let (ccr, skr) = webauthn
    .start_attested_passkey_registration(
        Uuid::new_v4(),
        "claire",
        "Claire",
        None,
        attestation_ca_list,
        Some(AuthenticatorAttachment::Platform),
    )
    .expect("Failed to start registration.");

pub fn finish_attested_passkey_registration( &self, reg: &RegisterPublicKeyCredential, state: &AttestedPasskeyRegistration, ) -> WebauthnResult<AttestedPasskey>

Available on crate feature attestation only.

Complete the registration of the credential. The user agent (e.g. a browser) will return the data of RegisterPublicKeyCredential, and the server provides its paired AttestedPasskeyRegistration. The details of the Authenticator based on the registration parameters are asserted.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

The returned AttestedPasskey must be associated to the users account, and is used for future authentications via crate::Webauthn::start_attested_passkey_authentication.

Verifying specific device models

If you wish to assert a specific type of device model is in use, you can inspect the AttestedPasskey attestation() and its associated metadata. You can use this to check for specific device aaguids for example.

pub fn start_attested_passkey_authentication( &self, creds: &[AttestedPasskey], ) -> WebauthnResult<(RequestChallengeResponse, AttestedPasskeyAuthentication)>

Available on crate feature attestation only.

Given a set of AttestedPasskey’s, begin an authentication of the user. This returns a RequestChallengeResponse, which should be serialised to json and sent to the user agent (e.g. a browser). The server must persist the AttestedPasskeyAuthentication state as it is paired to the RequestChallengeResponse and required to complete the authentication.

Finally you need to call finish_attested_passkey_authentication to complete the authentication.

WARNING ⚠️ YOU MUST STORE THE AttestedPasskeyAuthentication VALUE SERVER SIDE.

Failure to do so may open you to replay attacks which can significantly weaken the security of this system.

pub fn finish_attested_passkey_authentication( &self, reg: &PublicKeyCredential, state: &AttestedPasskeyAuthentication, ) -> WebauthnResult<AuthenticationResult>

Available on crate feature attestation only.

Given the PublicKeyCredential returned by the user agent (e.g. a browser), and the stored AttestedPasskeyAuthentication complete the authentication of the user. This asserts that user verification must have been correctly performed allowing you to trust this as a MFA interfaction.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

On success, AuthenticationResult is returned which contains some details of the Authentication process.

As per https://www.w3.org/TR/webauthn-3/#sctn-verifying-assertion 21:

If the Credential Counter is greater than 0 you MUST assert that the counter is greater than the stored counter. If the counter is equal or less than this MAY indicate a cloned credential and you SHOULD invalidate and reject that credential as a result.

From this AuthenticationResult you should update the Credential’s Counter value if it is valid per the above check. If you wish you may use the content of the AuthenticationResult for extended validations (such as the user verification flag).

impl Webauthn

pub fn start_discoverable_authentication( &self, ) -> WebauthnResult<(RequestChallengeResponse, DiscoverableAuthentication)>

Available on crate feature conditional-ui only.

This function will initiate a conditional ui authentication for discoverable credentials.

Since this relies on the client to “discover” what credential and user id to use, there are no options required to start this.

pub fn identify_discoverable_authentication<'a>( &self, reg: &'a PublicKeyCredential, ) -> WebauthnResult<(Uuid, &'a [u8])>

Available on crate feature conditional-ui only.

Pre-process the clients response from a conditional ui authentication attempt. This will extract the users Uuid and the Credential ID that was used by the user in their authentication.

You must use this information to locate the relavent credential that was used to allow you to finish the authentication.

pub fn finish_discoverable_authentication( &self, reg: &PublicKeyCredential, state: DiscoverableAuthentication, creds: &[DiscoverableKey], ) -> WebauthnResult<AuthenticationResult>

Available on crate feature conditional-ui only.

Given the PublicKeyCredential returned by the user agent (e.g. a browser), the stored DiscoverableAuthentication and the users DiscoverableKey, complete the authentication of the user. This asserts that user verification must have been correctly performed allowing you to trust this as a MFA interfaction.

Errors

If any part of the registration is incorrect or invalid, an error will be returned. See WebauthnError.

Returns

On success, AuthenticationResult is returned which contains some details of the Authentication process.

As per https://www.w3.org/TR/webauthn-3/#sctn-verifying-assertion 21:

If the Credential Counter is greater than 0 you MUST assert that the counter is greater than the stored counter. If the counter is equal or less than this MAY indicate a cloned credential and you SHOULD invalidate and reject that credential as a result.

From this AuthenticationResult you should update the Credential’s Counter value if it is valid per the above check. If you wish you may use the content of the AuthenticationResult for extended validations (such as the user verification flag).

impl Webauthn

pub fn start_attested_resident_key_registration( &self, user_unique_id: Uuid, user_name: &str, user_display_name: &str, exclude_credentials: Option<Vec<CredentialID>>, attestation_ca_list: AttestationCaList, ui_hint_authenticator_attachment: Option<AuthenticatorAttachment>, ) -> WebauthnResult<(CreationChallengeResponse, AttestedResidentKeyRegistration)>

Available on crate feature resident-key-support only.

TODO

pub fn finish_attested_resident_key_registration( &self, reg: &RegisterPublicKeyCredential, state: &AttestedResidentKeyRegistration, ) -> WebauthnResult<AttestedResidentKey>

Available on crate feature resident-key-support only.

TODO

pub fn start_attested_resident_key_authentication( &self, creds: &[AttestedResidentKey], ) -> WebauthnResult<(RequestChallengeResponse, AttestedResidentKeyAuthentication)>

Available on crate feature resident-key-support only.

TODO

pub fn finish_attested_resident_key_authentication( &self, reg: &PublicKeyCredential, state: &AttestedResidentKeyAuthentication, ) -> WebauthnResult<AuthenticationResult>

Available on crate feature resident-key-support only.

TODO

Trait Implementations

impl Clone for Webauthn

fn clone(&self) -> Webauthn

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Webauthn

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.