Configure WebAuthn

This feature is available to licensed FusionAuth instances as of version 1.52.0. A free license is available in the Plan tab for any user who registers in the account portal.

Overview

WebAuthn provides the ability for users to authenticate in their browser using the same method they use to unlock their device, like a biometric scan or PIN. WebAuthn has some big security benefits over the traditional username and password. Read on to learn how to configure WebAuthn in your FusionAuth instance. If you’d like more detail on integrating WebAuthn with your FusionAuth instance, check out the WebAuthn Developer Guide.

What is WebAuthn

WebAuthn is a W3C specification that defines an API to create and use public-key credentials in web applications. Check out FusionAuth’s WebAuthn blog post for more information on the basics of WebAuthn and its security benefits.

You can enable WebAuthn in your FusionAuth instance with a few configuration changes. This guide explains these configuration options and provides detail to help you choose the best options for your instance.

Note: A license is required to utilize WebAuthn

See the Licensing guide for information about activating a license for your FusionAuth instance.

Tenant Configuration

The bulk of WebAuthn configuration happens at the tenant level, including Relying Party settings, authenticator attachment, and user verification requirements. Use the WebAuthn tab on the add/edit tenant page to configure these options.

The settings in this first section are applied to all applications in the tenant.

Relying Party Id

The Relying Party Id controls which sites a given passkey can be used on. A passkey can only be used with the same Relying Party Id it was registered with. There are constraints on valid values based on the website where the WebAuthn ceremonies are performed. Leaving this field blank, which causes the WebAuthn JavaScript API to use the browser request origin’s effective domain, should work for most use cases, but overriding the value can provide additional flexibility.

Next, we’ll cover the constraints imposed on this value by the browser and then how and why you may want to override the value.

Constraints

As part of its security requirements, the WebAuthn specification requires that the Relying Party Id for a given ceremony is either:

• The browser request origin’s effective domain
• A registrable domain suffix of the browser request origin’s effective domain

It’s easier to explain with an example. If your login page is at https://auth.piedpiper.com/oauth2/authorize, then the effective domain is auth.piedpiper.com. The following are valid Relying Party Ids:

• auth.piedpiper.com - matches the effective domain
• piedpiper.com - a registrable suffix of the effective domain

But the following values are not valid:

• m.auth.piedpiper.com - a subdomain of the effective domain
• com - this is a suffix of the effective domain but not registrable

Remember, if you are using a proxy or other means to serve up authentication pages for multiple domains, the domain the user sees in the browser is what matters, not the true hostname of the server.

Override

Continuing with the example from the previous section, let’s say your login page is at auth.piedpiper.com. If Relying party Id is left blank, the WebAuthn JavaScript API will default to using auth.piedpiper.com, the browser request origin’s effective domain, to scope passkeys. This means that passkeys will be registered with a Relying Party Id of auth.piedpiper.com, and those passkeys can only be used when the Relying Party Id is auth.piedpiper.com during the authentication ceremony.

The primary use case for overriding the Relying Party Id is to allow users access to their passkeys across multiple subdomains. Let’s expand this scenario and assume you’ve got login pages on a few domains:

• auth.piedpiper.com - the login domain for desktop/laptop users
• m.auth.piedpiper.com - the login domain for mobile browser users
• login.piedpiper.com - a legacy domain that is still in use for some portion of users

If you leave the Relying party Id blank, passkeys will be scoped to these exact domains. This means that a user who registers a passkey on their MacBook at auth.piedpiper.com, which is then synced to their other Apple devices via iCloud, would not be able to use that same passkey on their iPhone at m.auth.piedpiper.com. It also means that a user who registers a passkey on the legacy login.piedpiper.com would not be able to use that passkey on auth.piedpiper.com once they have been migrated to the new login domain.

There are a couple of options to override the Relying Party Id to improve the flexibility and usefulness of WebAuthn. Here are the override options available assuming all three login domains use the same FusionAuth instance and keeping in mind the constraints from the previous section:

• auth.piedpiper.com - this value would allow users to share the same passkey between auth.piedpiper.com and m.auth.piedpiper.com, but it would prevent users from registering or using passkeys on the login.piedpiper.com legacy domain
• piedpiper.com - this value functions the same as using auth.piedpiper.com with the added benefit that users would be allowed to register and use passkeys on login.piedpiper.com and continue using those same passkeys once they are migrated to the new auth.piedpiper.com domain

Workflow settings

Each WebAuthn workflow has the same set of configuration options.

Authenticator attachment

There are two authenticator attachment modalities in WebAuthn.

• platform - the authenticator is integrated with the client device
• cross-platform - the authenticator is removable from the client device and can be used with other client devices

The workflow settings allow limiting the associated workflow to one attachment only or allowing either. The value is used to limit eligible authenticators to those that are best suited for the workflow. The authenticator attachment preference only impacts the WebAuthn registration ceremony. These are the recommended values for available WebAuthn workflows:

• Bootstrap - Any. The bootstrap workflow can be used to authenticate on any supported device. The Any option allows signing in with WebAuthn across the broadest set of devices.
• Re-authentication - Platform only. In order to ensure that the authenticator is available for repeated logins on the same device, it is best to limit authenticator selection to those integrated with the client device.

Note: An Enterprise plan is required to utilize WebAuthn cross-platform authenticators.

User verification

There are three options for the user verification requirement defined by WebAuthn.

• Required - user verification is required to successfully complete the WebAuthn ceremony
• Preferred - user verification is preferred for the WebAuthn ceremony, but it will not fail if user verification is not provided
• Discouraged - user verification should not be provided for the WebAuthn ceremony

The workflow settings allow selecting the preference for user verification. If the workflow allows a user to authenticate, it is highly recommended to require user verification. If user authentication is not required, anyone with access to the authenticator could use it to authenticate as the user that owns the passkey.

Application Configuration

The application-level configuration options for WebAuthn serve as a way to override the availability of WebAuthn workflows that are configured at the tenant level.

In order to override which workflows are enabled for the application, regardless of the tenant configuration, first enable the main toggle. Enabling the toggle in one of the subsections will enable that workflow for the application. Likewise, disabling the toggle in one of the subsections will disable that workflow for the application.