FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    Configure WebAuthn

    FusionAuth Reactor logo

    This feature is only available in an Essentials or Enterprise plan. Please visit our pricing page to learn more.

    Available since 1.41.0

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

    • Tenant Configuration

      • Relying Party Id

      • Workflow settings

    • Application Configuration

    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.

    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.

    Tenant Configuration - WebAuthn

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

    Enabled

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

    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

    Tenant Configuration - WebAuthn workflow settings

    Each WebAuthn workflow has the same set of configuration options.

    Enabled

    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.

    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.

    Application Configuration - WebAuthn

    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Subscribe for developer updates