FIDO Alliance

Passkey Central

Authenticate Conference

Getting Started

For developers with existing web pages or applications that are looking to implement FIDO Authentication there are two changes that you will have to make to your application: 1) modifying the login and registration pages of your website or mobile application to use the FIDO protocols; and 2) setting up a FIDO server to authenticate any FIDO registration or authentication requests. The next two sections give a high-level overview of the steps to take for both of those changes.

Modifying Register and Login

Assuming your application already has the ability to register and login to accounts, adding FIDO Authentication is as simple as modifying your register and login screens.

The first design decision to make is whether to use FIDO for first factor authentication (password-less) or second factor authentication. There are too many considerations that go into that decision to discuss here (ease of use, platform availability, application type, risk tolerance, etc.), but the good news is that regardless of whether using FIDO for first factor or second factor, the implementation looks roughly the same.

Registration

Integrating FIDO with your registration web page is as simple as calling the right registration API call. The registration calls for each FIDO specification are:

  • 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 (a.k.a. – registering) in a browser.

Each of these API calls requires that your application fetch a challenge (large random number) from a server and pass it to the corresponding API call. The server will make 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 (e.g. – cookies) to track the challenge and the username / user’s account. After making the API call, the resulting 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:

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

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

Log in

Logging in with FIDO is very similar to registration. Just like there is a registration call for each FIDO specification, there is a similar log in API:

  • 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 login.
  • U2F: sign() — The U2F specification defines a JavaScript API for signing an assertion (a.k.a. – logging in) in a browser.
  • WebAuthn: navigator.credentials.get() — The WebAuthn specification defines a the navigator.credentials.get() API for using a credential (a.k.a. – logging in) via a browser.

Again, similar to the registration call the login API call will need a challenge from the server. Depending on the API, it may also need additional information — for example, WebAuthn may require a “credential ID” of previously registered accounts. The previous comments of needing some kind of session management also apply here, and the rest of the API flow is essentially the same as registration: pass the challenge to the API call, return the JSON to the server, and await the server’s success / failure response.

Adding a FIDO Server

There are far too many ways to integrate a FIDO server with existing authentication flows to cover them all comprehensively here. For example, a  FIDO server may be integrated with your web or application server, may be provided as a module within an existing IAM framework, may be a stand-alone server, or for very broad and complex services it may be any combination of the above. Also, FIDO may be integrated with an application-specific user data store (such as a MySQL or Mongo database), with LDAP / ActiveDirectory, provide SSO through an OpenID Connect (OIDC) identity provider (IDP), etc. The wide variety of back-end authentication architectures and use cases makes it difficult to talk about 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.

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

  • Servers will typically use REST endpoints to communicate with clients. This will require proper firewall configuration to communicate with clients. As mentioned previously, 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, so they will need a valid TLS certificate for https (or, will require a TLS terminator in front of them).
  • Servers may have policy configurations for determining when to allow registrations and authentications. For financial or government institutions, this may include use the FIDO Metadata Service (MDS) to validate the security of authenticators that are accessing services.
  • Servers will need to integrate with some form of user data store (LDAP, ActiveDirectory, MySQL, MongoDB, etc.). For new services, this is simply a matter of having some kind of storage associated with each user’s account. For existing applications, this will require modifying data schema — typically adding some form of one-to-many relationship between user accounts and the authenticators / credentials that they will register.

Additional forums for help with FIDO server architectures and configuration can be found here [link to community resources page].