This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.
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.
What about passkeys?
"Passkey" is the user-friendly term for WebAuthn credentials. Use this guide to configure FusionAuth’s WebAuthn systems to allow your users to log in with passkeys.
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: An Essentials or Enterprise plan is required to utilize WebAuthn.
See the Licensing guide for information about activating a license for your FusionAuth instance.
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.
This toggle must be enabled to use WebAuthn on this tenant.
- Relying party Id
The Relying Party Id controls the scope of WebAuthn passkeys (i.e. which sites a WebAuthn passkey can be used to authenticate). More on this below.
- Relying party name
The Relying Party name is a human-readable name that may be displayed by the browser or operating system during a WebAuthn ceremony. The value should be something that your users will recognize such as the name of your company or service. If the field is left blank, FusionAuth will default the value to Issuer from the tab during WebAuthn ceremonies.
- Debug enabled
Enable this toggle to create event logs with detailed information on WebAuthn failures. This can be useful for troubleshooting WebAuthn integration issues.
Relying Party Id
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.
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.
Continuing with the example from the previous section, let’s say your login page is at
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
m.auth.piedpiper.com, but it would prevent users from registering or using passkeys on the
piedpiper.com- this value functions the same as using
auth.piedpiper.comwith the added benefit that users would be allowed to register and use passkeys on
login.piedpiper.comand continue using those same passkeys once they are migrated to the new
Each WebAuthn workflow has the same set of configuration options.
Enabling this toggle will enable the associated workflow for all applications belonging to this tenant. The availability of a workflow can be overridden at the application level using the Application Configuration.
- Authenticator attachment
This setting controls which authenticator attachments are allowed for registration ceremonies when using the associated workflow. See the section below for recommendations on configuring this option.
- User verification
This setting controls whether user verification is required for registration and authentication ceremonies when using the associated workflow. See the section below for recommendations on configuring this option.
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:
Any. The bootstrap workflow can be used to authenticate on any supported device. The
Anyoption allows signing in with WebAuthn across the broadest set of devices.
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.
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.
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.
How helpful was this page?
See a problem?
Have a question or comment to share?
Visit the FusionAuth community forum.