Implement FIDO Authentication

If you are a developer with existing web pages or applications, you must make two changes to your application when you implement FIDO Authentication:

• Modify the sign-in and registration pages of your website or mobile application to use the FIDO protocols.
• Set up a FIDO server to authenticate any FIDO registration or authentication requests.

The following sections give a high-level overview of these steps.

Modify registration and sign-in screens

As long as your application already has capabilities for account registration and sign-in, adding FIDO Authentication only requires that you modify your registration and sign-in screens.

First, determine whether you will use FIDO for first factor authentication (passwordless) or second factor authentication. There are considerations you must account for when making this decision (such as, ease of use, platform availability, application type, and risk tolerance). Refer to the Passkey Roll-Out Guides for more information.

The process to implement FIDO Authentication is similar for both first and second factor authentication.

Registration

To integrate FIDO Authentication with your registration page, you will need to call the registration API.

Registration calls for each FIDO specification

UAF: UAF_OPERATION (iOS, Android) The UAF Client API specification defines an Android Intent and iOS x-callback scheme (respectively) with an operation type of UAF_OPERATION, where one of the first arguments to the UAF_OPERATION tells the authenticator to perform registration.

U2F: register() The U2F specification defines a JavaScript API for performing registration in a browser.

FIDO2/WebAuthn: navigator.credentials.create() The WebAuthn specification (which is part of the FIDO2 project) defines a the navigator.credentials.create() API for creating a new credential (registering) in a browser.

Each of these API calls require that your application fetch a challenge (large random number) from a server and pass it to the corresponding API call. The server makes sure that the challenge sent to the authenticator matches the one that it receives back, so your application will probably need some kind of session management (for example, cookies) to track the challenge and the username/user’s account. After making the API call, the JSON message from the API call is sent back to the server (typically via a REST endpoint that is defined by the server) and the server will validate the challenge, signature, origin, and other key security characteristics of the registration message.

Each FIDO specification has a description of the validations that a server must perform to validate messages:

UAF: The UAF Protocol specification defines how a server should process and validate registration requests and authentication (sign-in) requests U2F: Server validation is defined in the U2F JavaScript API specification FIDO2/WebAuthn: The WebAuthn specification lays out all of the steps that a relying party/server should perform when receiving a registration or sign-in requests.

The server responds with a success or failure depending on whether the registration succeeded or failed.

It is worth mentioning that a user’s account can have multiple authenticators registered with it, so make sure that your UX flows allow users to add multiple authenticators, assigns unique names to differentiate them, and allows them to remove authenticators (for example, if they get lost or stolen).

Sign-in

To integrate FIDO Authentication with your sign-in page, you will need to call the sign-in API.

UAF: UAF_OPERATION (iOS, Android)

U2F: sign() The U2F specification defines a JavaScript API for signing an assertion (signing in) in a browser.

WebAuthn: navigator.credentials.get() The WebAuthn specification defines a the navigator.credentials.get() API for using a credential (signing in) via a browser.

Similar to the registration call, the sign-in API call will need a challenge from the server. Depending on the API, additional information might be required. For example, WebAuthn may require a credential ID for previously registered accounts.

Each of these API calls require that your application fetch a challenge (large random number) from a server and pass it to the corresponding API call. The server makes sure that the challenge sent to the authenticator matches the one that it receives back, so your application will probably need some kind of session management (for example, cookies) to track the challenge and the username/user’s account. After making the API call, the JSON message from the API call is sent back to the server (typically via a REST endpoint that is defined by the server) and the server will validate the challenge, signature, origin, and other key security characteristics of the registration message.

Add a FIDO server

There are far too many ways to integrate a FIDO server with existing authentication flows to comprehensively cover them all here. For example, a FIDO server can be integrated with your web or application server, can be provided as a module within an existing IAM framework, can be a stand-alone server, or for very broad and complex services it can be any combination of the above.

Also, for example, FIDO can be integrated with an application-specific user data store (such as a MySQL or Mongo database), with Lightweight Directory Access Protocol (LDAP)/ActiveDirectory, or provide SSO through an OpenID Connect (OIDC) identity provider (IDP). The wide variety of back-end authentication architectures and use cases makes it difficult to include all the details of FIDO server integration, so what follows are generic tips and considerations for FIDO server deployment. Specific server vendors, and their documentation, should add additional information about how to integrate FIDO into any pre-existing IAM environment.

In addition to setting up the hardware and software for your server, there are several steps that are common across most server deployments:

• Servers typically use REST endpoints to communicate with clients, which requires proper firewall configuration. These endpoints may be part of existing applications (such as web servers or mobile application servers), or a micro-services architecture or ESB may be used to route messages to a stand-alone FIDO server.

• Servers require HTTPS communication. Servers need a valid TLS certificate for HTTPS or require a TLS terminator in front of them.

• Servers might have policy configurations that determine when to allow registration and authentication. For financial or government institutions, this may include use of the FIDO Metadata Service (MDS) to validate the security of authenticators that are accessing services.

• Servers need to integrate with some form of user data store (for example, LDAP, ActiveDirectory, MySQL, or MongoDB). For new services, this is a matter of having some kind of storage associated with each user’s account. For existing applications, this requires modification of the data schema — typically adding some form of one-to-many relationship between user accounts and the authenticators/credentials that they will register.

To find additional forums and resources that offer help with FIDO server architectures and configuration, refer to Developer Documents.

Additional resources

• Developers can implement passkeys, instead of legacy forms of authentication, to provide websites and apps with user-friendly and cryptographically secure sign-ins – all courtesy of the public WebAuthn API. Read more about the Web Authentication API on the W3C site.

• The Mozilla Developer resources guide to the Web Authentication API.

• WebAuthn.io by Duo Labs is a demo of the WebAuthn specification designed to test WebAuthn and passkeys.

• The Yubico Developer Program Learn, connect and integrate with Yubico technology. Covers passkeys, Yubico SDKs, forums, and open source software for integrating authentication.