U2F Walk-Through

This walk-through describes how to integrate the Yubico Universal Second Factor (U2F) protocol with your application or framework.

Implementation Methods

There are three methods for integrating Yubico authentication using the U2F protocol. For the purposes of this walk-through we describe the Plugin method.

Plugins for Content Management Systems (CMS).

Plugin modules for PAM (pluggable authentication module) and for Git.

Standalone Authentication Server

Use the Yubico REST API and a U2F validation server, U2FVAL.

Libraries for Programming Languages

Store and access U2F artifacts yourself.

Plugin Implementation

On your product or company server, configure for using Yubico U2F with a plugin. See Plugins.

Git Plugin

Select from the listed Github options and follow the steps for the plugin you choose.

PAM Plugin

The PAM plugin requires Yubico U2F libu2f-host-dev and libu2f-server-dev libraries.

Step 1: Build the project

Debian

apt-get install autoconf automake libtool pkg-config libu2f-host-dev libu2f-server-dev --no-install-recommends

From a tarball

./configure
make

Build from Git

Check out sources:

git clone git://github.com/Yubico/pam-u2f.git

Create directory, for example: pam-u2f

cd pam-u2f

Install libraries

Debian

apt-get install autoconf automake libtool libpam-dev libu2f-host-dev libu2f-server-dev asciidoc xsltproc libxml2-utils docbook-xml --no-install-recommends

Generate build system

autoreconf --install

Step 2: Install files

Copy the file, pam_u2f to the /lib/…/security directory.

./configure --with-pam-dir=

Create a file for the new service

auth sufficient pam_u2f.so debug

Step 3: Create mapping between YubiKey token and usernames

Choose between individually manged by user, or centrally-managed.

Individually managed by user

Each user performs these steps on their home directory.

Create directory and file

 .config/Yuibico/u2f_keys

Add content to file

<username>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

Centrally managed users

Create mapping file, for example: /etc/u2f_mappings

<username1>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...
<username2>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>:...

Add file to PAM configuration line

auth sufficient pam_u2f.so authfile=/etc/u2f_mappings

Step 4: Register the token device

pamu2fcfg -uusername -opam://myorigin -ipam://myappid

Available Plug-ins for Creating your YubiKey U2F Module

View and download the relevant plug-in components.

Available Libraries for Creating your YubiKey U2F Module

View and download the relevant Yubico library components.

U2F Server Libraries

Client Connector Libraries

Host Libraries

Attestation and Metadata

All Yubico devices attestation certificates are signed by the Yubico root CA.

Yubico devices provide additional device information in the mapping attestation certificate. This is used by several of the U2F server libraries.See Attestation and metadata.

App ID

Specify the Facet ID, that is the platform-specific identifier (URI) for your application, where the Facet is how an application is implemented on a platform, such as Android app or Web app.

  • Single-facet app

Example

https://example.com
  • Multi-facet app

Include all facets in and HTTPS resolvable file.

Example

https://example.com/app-id.json

Sample JSON file

{ "trustedFacets" : [{
"version": { "major": 1, "minor" : 0 },
"ids": [
"https://login.example.com",
"https://secure.example.com",
"android:apk-key-hash:585215fd5153209a7e246f53286035838a0be227"
]
}]
}

Module Validation

Submit your module to YubiKey OTP Validation Server, https:..developers.yubico.com/yubikey-val.