How do I use FIDO U2F to allow users to authenticate with my website? How do I use FIDO U2F to allow users to authenticate with my website? google-chrome google-chrome

How do I use FIDO U2F to allow users to authenticate with my website?


What you are trying to do is implement a so called "relying party", meaning that your web service will rely on the identity assertion provided by the FIDO U2F token.

You will need to understand the U2F specifications to do that. Especially how the challenge-response paradigm is to be implemented and how app ids and facets work. This is described in the spec in detail.

You are right: The actual code necessary to work with FIDO U2F from the front end of you application is almost trivial (that is, if you use the "high-level" JavaScript API as opposed to the "low-level" MessagePort API). Your application will however need to work with the messages generated by the token and validate them. This is not trivial.

To illustrate how you could pursue implementing a relying party site, I will give a few code examples, taken from a Virtual FIDO U2F Token Extension that I have programmed lately for academic reasons. You can see the page for the full example code.


Before your users can use their FIDO U2F tokens to authenticate, they need to register it with you.In order to allow them to do so, you need to call window.u2f.register in their browser. To do that, you need to provide a few parameters (again; read the spec for details).Among them a challenge and the id of your app. For a web app, this id must be the web origin of the web page triggering the FIDO operation. Let's assume it is example.org:

window.u2f.register([    {        version : "U2F_V2",        challenge : "YXJlIHlvdSBib3JlZD8gOy0p",        appId : "http://example.org",        sessionId : "26"    }], [], function (data) {});

Once the user performs a "user presence test" (e.g. by touching the token), you will receive a response, which is a JSON object (see spec for more details)

dictionary RegisterResponse {    DOMString registrationData;    DOMString clientData;};

This data contains several elements that your application needs to work with.

Register Map of a FIDO U2F Registration Response Message

  1. The public key of the generated key pair -- You need to store this for future authentication use.
  2. The key handle of the generated key pair -- You also need to store this for future use.
  3. The certificate -- You need to check whether you trust this certificate and the CA.
  4. The signature -- You need to check whether the signature is valid (i.e. confirms to the key stored with the certificate) and whether the data signed is the data expected.

I have prepared a rough implementation draft for the relying party server in Java that shows how to extract and validate this information lately.


Once the registration is complete and you have somehow stored the details of the generated key, you can sign requests.

As you said, this can be initiated short and sweet through the high-level JavaScript API:

window.u2f.sign([{    version : "U2F_V2",    challenge : "c3RpbGwgYm9yZWQ/IQ",    app_id : "http://example.org",    sessionId : "42",    keyHandle: "ZHVtbXlfa2V5X2hhbmRsZQ"}], function (data) {});

Here, you need to provide the key handle, you have obtained during registration.Once again, after the user performs a "user presence test" (e.g. by touching the token), you will receive a response, which is a JSON object (again, see spec for more details)

dictionary SignResponse {    DOMString keyHandle;    DOMString signatureData;    DOMString clientData;};

You the need to validate the signature data contained herein.

Register Map of a FIDO U2F Authentication Response Message

  1. You need to make sure that the signature matches the public key you have obtained before.
  2. You also need to validate that the string signed is appropriate.

Once you have performed these validations, you can consider the user authenticated. A brief example implementation of the server side code for that is also contained in my server example.


I have recently written instructions for this, as well as listing all U2F server libraries (most of them bundles a fully working demo server), at developers.yubico.com/U2F. The goal is to enable developers to implement/integrate U2F without having to read the specifications.

Disclaimer: I work as a developer at Yubico.