Struct webauthn_rs::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 preview-features enabled as the current form of the Attestation CA List may change in the future.

–> You should use start_passwordlesskey_registration

I want users to have their identites 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 resources of the users devices, and may result in failures, so you should only use it in tightly controlled environments where you supply devices to your users.

–> You should use start_devicekey_registration (still in development)

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

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

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

Implementations

impl Webauthn

pub fn get_origin(&self) -> &Url

Get the currently configured origin

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 pass key for a user. A pass key is any cryptographic authenticator acting as a single factor of authentication, far stronger than a password or email-reset link.

Some examples of pass keys 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 all cases passkeys are better than passwords!

You should NOT pair this authentication with another factor. A passkey may opportunistically allow and enforce user-verification (MFA), but this is NOT guaranteed with all authenticator types.

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. 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.

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.");

// Only allow credentials from manufacturers that are trusted and part of the webauthn-rs
// strict "high quality" list.
let (ccr, skr) = webauthn
    .start_passkey_registration(
        Uuid::new_v4(),
        "claire",
        "Claire",
        None, // No other credentials are registered yet.
    )
    .expect("Failed to start registration.");

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 it’s 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 credential id 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.

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, Solokeys, and others.

We don’t recommend this over Passkeys or PasswordlessKeys, 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 can 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.

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.
let (ccr, skr) = webauthn
    .start_securitykey_registration(
        Uuid::new_v4(),
        "claire",
        "Claire",
        None,
        Some(AttestationCaList::strict()),
        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 it’s 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.

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

Verifying specific device models

If you wish to assert a specifc type of device model is in use, you can inspect the PasswordlessKey attestation() and it’s 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’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 SecurityKeyAuthentication state as it is paired to the RequestChallengeResponse and required 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.

Trait Implementations

impl Debug for Webauthn

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

Formats the value using the given formatter.