YubiKey two-factor OTP authentication

Classification: sf_yubikey
Version: 6.0
Language: en
Description: YubiKey two-factor OTP authentication
Keywords: yubikey, yubico, two-factor, authentication, service
Copyright: 2012 - 2015
Author: Torben Hansen
Email: derhansen@gmail.com
License: This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml
Rendered: Sat, 13 Dec 2025 07:56:47 +0000

The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from www.typo3.org.

Table of Contents

Introduction

What does it do?

This extension is an authentication service for TYPO3 which extends the frontend and backend login process by strong two-factor authentication.

The two-factor authentication is provided by a TYPO3 users username and password combined with a OTP (one time password) which is generated by a YubiKey (a physical USB-key)

A YubiKey enabled user has to enter his username, password and a OTP to login to the TYPO3 backend and/or frontend.

More information about the YubiKey, Yubico and the YubiCloud OTP validation service can be found at http://www.yubico.com

Screenshots

|login-62|

The YubiKey enabled TYPO3 backend login (TYPO3 6.2)

|login-73|

The YubiKey enabled TYPO3 backend login (TYPO3 7.3)

Users manual

The usage of the two-factor authentication is very easy. You can enable each individual backend and frontend user to use the two-factor authentication process.

After the extension is installed, there is a new tab in the user settings where you can enable the YubiKey two-factor authentication.

User settings

To enable the YubiKey two-factor authentication for a user, just edit the user in the TYPO3 backend and enable the checkbox as shown below.

|be-user-settings|

Next you have to enter the YubiKey ID, which is the unique ID of the YubiKey USB key. To get the ID, just insert your YubiKey into a free USB port and press the button on the YubiKey. Now a YubiKey OTP will be inserted in the textfield. Don't care, that the textfield will show the whole YubiKey OPT. The authentication process will automatically extract the YubiKey ID from the OTP.

If you have multiple YubiKey devices, you can save the YubiKey ID of each device in the textfield. Remember to use a new line for each YubiKey ID.

Administration

Setting the Yubico API Key

After installing the extension from the extension repository, you need to configure the extension settings. The authentication process only works, if you provide a Yubico API Key, which can by obtained at https://upgrade.yubico.com/getapikey/

The Yubico API Key is necessary to use the free YubiCloud OTP validation service.

After you have obtained your Yubico API Key, enter the Client ID and the Client Key in the extension settings.

As an alternative, you can also setup your own YubiCloud Service as described here: https://developers.yubico.com/OTP/Guides/Self-hosted_OTP_validation.html

|ext-settings|

Extension settings for the Yubico API Key

Configuring TYPO3 felogin extension to use YubiKey

If you have enables YubiKey Authentication for frontend users, you have to add an extra field to your felogin template.

First you have to overwrite the template Login.html of ext: felogin.

Then you must add the following HTML to the template:

<div>
  <label>
    Yubikey
    <f:form.textfield name="t3-yubikey"/>
  </label>
</div>

Finally, you can add your own CSS Styles to the new field, so it looks like a YubiKey enabled input field.

Configuration

The extension can be configured in the extension settings from the extension manager. Besides the Yubico API Key and the Client ID, there are four other settings that can be configured.

Property:	Data type:	Description:	Default:
yubikeyEnableBE	boolean	Enable YubiKey authentication for TYPO3 backend users	True
yubikeyEnableFE	boolean	Enable YubiKey authentication for TYPO3 backend users	False
devlog	boolean	Writes debugging messages to a logfile in /typo3temp/var/log/sf_yubikey_{date}_{hash}.log	False
yubikeyClientId	string	Your Yubico API Client ID	Empty
yubikeyClientKey	string	Your Yubico API Client Key	Empty
yubikeyApiUrl	string	The Yubico API URL to validate YubiKey OTPs. This may also be an own instance of a YubiKey validation server. Separate multiple endpoints by semicolon.	https://api.yubico.com/wsapi/2.0/verify;https://api2.yubico.com/wsapi/2.0/verify;https://api3.yubico.com/wsapi/2.0/verify;https://api4.yubico.com/wsapi/2.0/verify;https://api5.yubico.com/wsapi/2.0/verify

Known problems

The YubiKey extension does not work with TYPO3 7.2, because you can't add own fields to the backend login in that TYPO3 version.

If you think you've found a bug, please report it on GitHub.

https://github.com/derhansen/sf\_yubikey

Changes

A list of all changes can be found on GitHub https://github.com/derhansen/sf_yubikey/commits/master

Important Changes

Version 1.0.0

YubiKey OTP validation is only handled through the bundled class YubikeyAuth. The usage of PEAR classes has been removed.

Version 4.0.0

The YubiKey validation is performed using the class YubikeyService which uses psr/http-client and psr/http-factory for requests. The disableSslVerification setting has been removed, since this can be configured global in TYPO3 HTTP client settings.

The extension setting yubikeyApiUrl has been renamed to yubikeyApiUrls. Users must adapt this setting manually if configured.