We are going to go through integrating the Yubico One-Time Password (OTP) protocol with your application or framework, step by step.
|
Tip
|
This walk-through is designed for people who prefer learning by doing. If you prefer to learn concepts from the ground up, check out our YubiKey Authentication Module Design Guideline. You should find this and the guide are complementary to each other. |
The walk-through is divided into several sections:
Overview provides the fundamentals of OTP
Setup provides you with a starting point to follow the walk-through
Enable your Yubikey API Authenticator
Create your Verification Client
Add Authentication Logic
We recommend you check out https://demo.yubico.com/otp/verify if you are new to OTP.
With One-Time Password (OTP), symmetric-key cryptography is used to authenticate users against a central server, also known as a Relying Party (RP). The OTP is validated by a central server for users logging into your application.
At production a symmetric key is generated and loaded on the YubiKey. This can be done by Yubico if you are using the YubiCloud, or by the user directly.
Then the symmetric key is shared with the validation server prior to being used to generate OTPs. This must be done at programming level since the key cannot be extracted from the YubiKey. Yubico handles uploading keys to the YubiCloud prior to selling YubiKeys.
When your user makes the request to log in, the YubiKey generates an OTP to be sent to the verification server (either the YubiCloud or a services' private verification server). The response from server verifies the OTP is valid.
After the OTP is verified, your application uses the public identity to validate that the YubiKey belongs to the user.
Then your user is allowed to log in to your application.
A computer with browser access and a YubiKey are all you really need to get started.
Incorporating YubiKey authentication into your application or platform uses the following four components. You will be creating, configuring, and using these items throughout this walk-through.
Verification server
YubiKey API authenticator
Verification client
Authentication logic
Verification server
Yubico provides the YubiCloud as a free OTP validation service. We recommend you use it. Optionally, you can self-host a verification server. See YubiCloud Validation Servers for options on creating your own verification server.
The YubiCloud verification server validates the OTPs generated by the YubiKey. The verification server must have the secret uploaded to it prior to verifying OTPs. Every YubiKey is registered to the YubiCloud by default.
If the YubiCloud configuration is overwritten, use the YubiKey Manager to re-register the YubiKey with the YubiCloud.
Your YubiKey API authenticator
Obtain a YubiKey. See The YubiKey
In the steps, you will register your YubiKey to give you access to the Yubico API.
You will also be able to run the OTP demo server to verify your application supports multiple YubiKeys per user.
Your verification client
This is the core task in this walk-through. You will be setting up your verification server (YubiCloud) client. Your YubiCloud client provides the pass-through logic between your users, their YubiKeys, and YubiCloud.
Authentication logic
This is the code you need to create and include in your application or framework. There are specific requirements to ensure one YubiKey provides access to multiple applications on a framework.
Sign up for and acquire your API key.
Optionally, for testing and example purposes, use a browser to view responses and actions in plain text. All the clients are a means to take the action and support applications.
Step 1 Open a browser and insert your YubiKey into the appropriate port on your computer.
The YubiKey connects to the api.yubico.com validation server. The browser displays:
h=string of characters t=timestamp status=MISSING_PARAMETER
Step 2 Follow Keyboard Setup Assistant.
a) Click Continue.
b) Tap the YubiKey. The YubiKey in this case is the keyboard.
c) Select Keyboard Type. Then click Done.
d) Tap the YubiKey again.
The browser page updates and completes an OTP. The first twelve modhex characters of the opt= form the Private Key for the inserted YubiKey.
h=string of characters t=timestamp otp=string of characters nonce=string of characters sl=100 status=OK
Step 1 In a browser window, go to the Yubico API registration URL, Yubico API key signup
a) Enter your email address.
b) Generate an OTP from your API YubiKey in the OTP field.
c) Accept the Terms and Conditions.
d) Click Get API key.
Step 2 Record the Client ID and Secret Key.
These values are used to authenticate your users on the YubiCloud. One Client ID/Secret Key pair is required for every application you create.
Note: These values are never shared again. Do not loose them.
If any there is any reason Yubico needs to shut down your client access to the YubiCloud due to malicious activities, use the YubiKey values to verify your identity.
For this phase of the process, you select a library and embed the Client ID and Secret Key in your library to create your YubiCloud client.
When your users use their YubiKeys for authentication, your client does the following:
• Implements the OTP transport protocol • Parses the response from validation server (YubiCloud)
Step 1 Choose a Yubico OTP library or create your own.
For each client, the hooks for integration are different due to the different syntaxes and structure for each language.
Select from the libraries provided by Yubico
The PHP, dotNet and Java clients are called by an application, and should be imported as you would a standard library. The code to use them is included in the developer.yubico.com pages for each language, in the "Usage" sections.
The C client and perl client need to be integrated into an application by including the libraries in the standard manner. However, you need to build the client functions - this provides much more flexibility in the process, but does require additional work. The comments in the source code for the sample client applications detail the structure and steps.
Optionally, build your own library.
See Creating your own libraryhttps://developers.yubico.com/OTP/Libraries/Creating_your_own_library.html
Step 2 Create your YubiCloud client using your library and set the listed actions.
a) Send requests. Add to your client:
client = Yubico(clientId, secretKey)
Enter the clientId and secretKey you saved from registering your YubiKey for an API Key, at https://upgrade.yubico.com/getapikey.
b) Verify submitted OTPs. Add to your client:
otp_is_valid = client.verify(otp)
The otp= value is the OTP from the YubiKey that the user inserts.
c) Verify user login. Add to your client:
assert otp[:12] == user.yubikey_id
12 indicates the first twelve modhex characters from the otp= field. On the YubiCloud validation server, this value is compared with the YubiKey ID that is associated with the user.
d) Provision user YubiKeys by assigning a YubiKey ID to a User ID.
user.yubikey_id = otp[:12]
Add these association entries to your database. For example:
YubiKeyID : UserID
In your application, add the logic needed to process registration and authentication requests. See OTPs Explained.
Enable users to register with your application or platform.
Step 1 Expose a connection to your UI that accepts the OTP for launching the application. For example, instruct your users to insert the YubiKey. See What is Yubico OTP?. This connection sends the OTP download to the YubiCloud client for validation.
Step 2 Use the YubiKey Public ID and associate it with the registering user.
Step 3 Store the YubiKeyID : UserID pairs in your database.
Step 4 Add logic in in your application to check the UserID for a valid OTP response from the YubiKey validation server.
Do a logic check and ensure your registered users can authenticate with your application. See OTPs Explained.
During authentication:
Step 1 Ensure your application retrieves the OTP from an inserted and tab-touched YubiKey.
For two-factor authentication, add a field or other means to enter credentials. Indicate that the YubiKey must also be inserted and tab-touched.
Step 2 Pass the OTP to your YubiCloud client.
Your YubiCloud client validates the OTP in the YubiCloud. The YubiCloud validation server returns a response.
Step 3 Have your YubiCloud client parse the response.
If a valid response is returned, proceed with the next step in authentication.
If YubiCloud rejects the submitted OTP, forward the YubiCloud validation server error message. This message indicates an OTP/Client error.
Step 4 For a valid YubiCloud response, check the YubiKey public ID against the user ID pair in your database.
If a valid response is returned, authenticate the user and log them in.
If the YubiKey ID and User ID do not match, send an error message. Create an appropriate error message. As the developer, you are responsible for creating the public-facing error messages.
Verify your client is compatible with your application code base and language.
Congratulations! You’ve completed all the steps to enable your users to register and authenticate with an OTP credential.
If you get stuck, you can check Stack Overflow. If you don’t receive an answer, or remain stuck, please file an issue or open a support ticket and we’ll help you out.
View and download the relevant plug-in components.
Yubico PAM module – Pluggable Authentication Modules (PAM) for GNU/Linux, Solaris and macOS for user authentication. — Requires libykclient, libpam-dev, cURL, libyubiky, yubikey-personalization
Yubico Java client – For integrating YubiKey with your Java applications. — Includes JAAS, and demo server
View and download the relevant Yubico library components.
PHP — Includes demo.php, example/db.sql, example/config.php, Modhex_Calculator.php, Modhex Converter
Java — Includes JAAS, and demo server
DotNet — Uses clientId and apiKey from
Yubico API key signup