1.5.7. Enrolling tokens#

LinOTP is able to enroll several different tokens. These can be:

  • eToken NG-OTP

  • mOTP Tokens

  • HOTP and TOTP Tokens

  • Static Password Tokens

  • QR Tokens

  • Push Tokens

  • SMS OTP / Mobile TAN

  • Remote Tokens

  • Forwarding Tokens

  • RADIUS Tokens

  • YubiKeys

  • E-Mail Tokens

  • Day OTP Tokens

Enroll eToken NG-OTP#

Note

An eToken NG-OTP can only be enrolled using the command line client.

An eToken NG-OTP is a USB based token, that does not have a preinstalled HMAC key. The secret HMAC key is generated by the management client and installed to the token and stored in the token database without any person seeing this HMAC key.

For enrolling eToken NG-OTP you need to have the Aladdin/SafeNet PKI Client installed.

Enroll mOTP Token#

LinOTP is also capable of using other OTP algorithms and thus supports many different tokens. So it is also possible to enroll mOTP Tokens which you can download at http://motp.sourceforge.net. These are time based open source OTP tokens that can be installed on a mobile phone. mOTP token apps exist for Android phones, the iPhone and also for older feature phones. You can find recommended mOTP apps for Android and iPhone in the section Recommended Mobile Apps.

Please refer to the project website on how to install the mOTP on your feature phone.

As to the app for the feature phone you may initialize the mOTP application at any time anew. Initializing mOTP means, that a new OTP key – in this case it is called Init-Key – is created on the mobile phone. This can be done by entering ‘0000’ when the mOTP application asks ‘Enter PIN:’. When you have installed the mOTP to your mobile or to the mobiles of all your users, each mobile needs to create its secret key.

  1. In the LinOTP management client press the button “enroll”.

  2. Choose the tokentype “mOTP”.

  3. You need to enter the OTP key, that was generated on the mobile phone.

  4. The user needs to make up a 4 digit passphrase, that he enters each time, when he wants to generate an OTP value on his mobile.

    Note

    This is the mOTP PIN. The mOTP PIN is the PIN that gets entered on the phone and is also used to calculate the OTP value. When you enter a wrong mOTP PIN on the phone, the phone will calculate a wrong OTP value. This must not be confused with the OTP PIN.

  5. You may now press “OK” and the management client will generate a serial number for the token for you.

  6. If you need to change the mOTP PIN later click “set PIN” in the WEB UI and choose “mOTP PIN”.

    ../../_images/setmotppin-webui.png

    Setting the mOTP PIN in the Web UI#

  7. You may also want to set an “OTP PIN”, that the user needs to enter in front of the generated OTP value when he wants to authenticate.

The OTP value of mOTP tokens are validated by the epoch time. You may verify the epoch time on the LinOTP server to compare it to the time on the mobile phones using the command:

date +%s
1268661055

Enroll HOTP, TOTP and OCRA2 Tokens#

You may realize, that there are several softtokens (e.g. for mobile phones) around that use the HOTP HMAC-Based One-Time Password Algorithm defined in RFC4226, TOTP (a variation of HOTP) Time-Based One-Time Password Algorithm defined in RFC6238 and OCRA OATH Challenge-Response Algorithm defined in RFC6287.

Some of these tokens generate the HMAC secret key during an initialization process.

Select one of these tokens to register and create an HMAC secret key/Seed during initialization.

  1. If necessary, select the user in userview for whom the token should be rolled out.

  2. Choose one tokentype:
    • HOTP - HMAC eventbased

    • TOTP - HMAC time based

    • OCRA2 Token

  3. Enter the secret, that was generated by the token. Or generate a random seed.

  4. For HOTP and TOTP, you can use: Google Authenticator compliant. This sets some defaults like the OTP-Length which are known to work well with the Google Authenticator app.

  5. Enter Token Pin to secure your Token (optional, you can change them later)

../../_images/webui_token_popup_enroll_event-timebased.png

Enroll OATH token with the Web UI#

../../_images/webui_token_popup_enroll_ocra0.png

Enroll OCRA2 token with the Web UI#

But the Web UI offers additional functionalities and is the recommended management tool. The Web UI can have the LinOTP server generate the HMAC seed. Some Apps like the Google Authenticator, the Android token or OATH token can import this seed using a QR code.

The LinOTP server can generate such a QR code.

../../_images/webui_token_popup_rolledout_qr_eventbased.png

Enroll a Google Authenticator using a QR code#

The QR code is scanned with the app on the mobile phone and the mobile can be used as token.

Enroll LinOTP Static Password Token#

This token allows a users to authenticate with a fixed password instead of an OTP.

In some cases it might be necessary that users authenticate without a one time password, but rather with a fixed password. This may be, if your authentication client is not capable of routing users to OTP authentication and other users to password authentication or in cases, where a user may have lost his OTP generator or to allow temporary logins for externals. A PIN can be set and the PIN policy applies.

Note

Please be aware: this is a very weak second factor and possibly compromises the security.


Choose the static password token:

../../_images/dropdown_passwordtoken.png

Enter the password used as OTP:

../../_images/enroll_passwordtoken.png

Enroll SMS OTP / Mobile TAN#

To enroll an SMS OTP token

  1. choose the tokentype “SMS”.

  2. If you selected a user and this user has a mobile phone number defined in the user store, this phone number will be automatically entered in the phone number field. You may of course change this.

  3. Press OK and the token with this mobile phone number is created and assigned to the selected user.

Note

If you need to change the phone number later, you can do this in the tokeninfo dialog. To be able to change the phone number a policy scope:admin,action:set must be configured. See Admin Policies for more details.

For a convenient rollout of SMS token Linotp provides (starting from version 2.7.2.2) the command line tool linotp-enroll-smstoken. It can be used to rollout and assign token to a single user, to users in a certain realm or even for all users which have a mobile number stored in their UserIdResolvers.

Available parameters for linotp-enroll-smstoken:

--linotp:           the linotp url (required)
--admin:            the token admin user - will prompt for the admin password
--username:         the username filter (optional)
--realm:            the realm filter for the user selection (optional)
--no-ssl-verify     supress the verification of the ssl certificate

Example: rollout SMS token for a single user

linotp-enroll-smstoken --linotp https://LINOTP --admin TOKENMANAGER --username
USER

Example: rollout SMS token for all users in a realm which have a mobile number assigned to

linotp-enroll-smstoken --linotp https://LINOTP --admin TOKENMANAGER --realm
REALM

Note

If you use LinOTP Smart Virtual Appliance 1.2 or older the script will be installed (/usr/bin/linotp-enroll-smstoken) but can not be executed due to library version conflicts. Please copy the script to a machine running a recent distribution of linux and start it from there.

Enroll Remote Token#

A Remote Token forwards the authentication request to another LinOTP server. So the calculation of the One Time Password is not done on the first LinOTP server, where the User is authenticated but on the remote LinOTP server. The Remote Token can be defined this way, that only a serial number and the OTP value is forwarded to the remote server. This token with this serial number needs to be located on the remote server of course.

Thus, a remote server can hold all OTP tokens without knowing any users and without having any tokens assigned to any users. On such a remote server not even a UserIdResolver needs to be defined.

The authenticating LinOTP (first) server will do no OTP calculation and thus will not know any secret keys (HMAC keys) since it forwards all requests to the remote server. To enroll a Remote Token just choose enroll and then the token type “Remote Token”.

Then you need to enter the remote LinOTP server and the serial number of the token on the remote server.

Alternatively you can specify a user on the remote LinOTP server, if the token is assigned to a user.

Note

If you specify “https://localhost” as the remote server, you can assign one single physical token to several users, by pointing the Remote token to a local token of another user.

You may choose if the checking of the PIN is done locally or remotely.

Check PIN remotely

Do not set a PIN on the local LinOTP server. The entered credentials will be completely forwarded to the remote LinOTP server. The PIN that was set on the remote server will be used to authenticate the user.

Check PIN locally

In this case, the PIN on the local LinOTP server is verified. If the PIN on the local server matches, the remaining part of the credentials will be sent to the remote server. On the remote server NO PIN should be set for the token, otherwise authentication might fail. In this scenario a remote server can hold one physical OTP token with no PIN, while all the Remote Token on the local machine get individual PINs and can be assigned to different users.

Enroll Forwarding Token#

The Forwarding Token is the simple form of the Remote Token. It can be used to share the same token between different users. The main difference to the Remote Token is that the referenced token must be at the same LinOTP server. Configuration is very simple - just point to the serial number of the desired token. PIN policy etc. is applied for the authenticated user.

../../_images/popup_forwarding_token.png

If the policy ‘challenge-response’ is activated, the Forwarding Token as well supports the forwarding to challenge response tokens like the qr token. When a challenge is triggered through a Forwarding Token the challenge response detail contains then additional information:

  • the target token type (linotp_forward_tokentype),

  • the target token serial number (linotp_forward_tokenserial) and

  • the target token description (linotp_forward_tokendescription).

Enroll RADIUS Token#

A RADIUS Token can forward the authentication request to another RADIUS server. This can be any kind of RADIUS server.

Note

The RADIUS token can be well used for migrating existing RADIUS scenarios.

A RADIUS Token consists of

  • the RADIUS server name

  • plus the port,

  • the username on the RADIUS server and

  • the RADIUS shared secret.

You may also define, if the OTP PIN is checked locally on the LinOTP server or if the complete password is forwarded to the RADIUS server.

Choose “enroll” and then choose the token type “RADIUS Token”. Enter the RADIUS server name including the port and the other required information.

Check PIN locally If the OTP PIN is checked locally, you also need to

specify the length of the potential OTP value, i.e. how many characters of the password will be split and sent to the RADIUS server.

Check PIN on RADIUS server

If you choose to check the PIN on RADIUS server the complete credential will be sent to the RADIUS server.

Enroll LinOTP QR Token#

The LinOTP QR Token can be either enrolled via API or the self service portal. The enrollment consists of two steps:

  • Pairing: The first part of the token is transferred to the user’s mobile via a QR code. This contains the required the information for the activation process.

  • Activation: The token on the user’s phone is activated.

Please see Setup LinOTP QR Token for details.

Note

Please note - the LinOTP Authenticator APP is required which is available for iOS and Android.

Transactions and logins are validated by the user’s phone. The login program (like the LinOTP Authentication Provider) displays a QR code which is scanned with the LinOTP Authenticator APP (available for Android and iOS). The user approves the action on the phone and the login / transaction is validated by LinOTP. The QR Token features an offline mode in case the mobile or the login program can not contact the LinOTP server (e.g. in an airplane).

A case study as a complete example can be found here: Application Scenario with the LinOTP QR Token

Enroll LinOTP Push Token#

The LinOTP Push Token can be either enrolled via API or the self service portal. The enrollment consists of two steps:

  • Pairing: The first part of the token is transferred to the user’s mobile via a QR code. This contains the required the information for the activation process.

  • Activation: The token on the user’s phone is activated.

Please see LinOTP Push Token Policies for details about the required policies and Push Provider for LinOTP Push Token how to configure the needed Push Token Provider.

Note

Please note - the LinOTP Authenticator APP is required which is available for iOS and Android.

Transactions and logins are validated by the user’s phone. The login program (like the LinOTP Authentication Provider) triggers a push message to the LinOTP Authenticator APP (available for Android and iOS). The user approves the action on the phone and the login / transaction is validated by LinOTP.

A case study as a complete example can be seen here: Application Scenario with the LinOTP Push Token

Note

The use of the Push Challenge Service is included in a corresponding support contract. Please contact support@linotp.de for help and documentation netgo GmbH provides the required infrastructure for the Voice Token for their customers.

Enroll OCRA2 Token#

A OCRA2 Token is an ocra algorithm based token that can be enrolled via a QR code process and where the challenge is also transmitted via a QR code. You can either start the QR enrollment via the API (/admin/init) or you can start the enrollment of the OCRA2 Token via the management web UI.

Note

Please note, that you need the LinOTP QR-TAN App which is available on request for iOS and Android.

Select a user and press the button “Enroll Token”.

../../_images/enroll-qr-1.png

Start enrolling an OCRA2 Token#

The displayed QR code needs to be scanned with the users smartphone. Alternatively you can print the QR code and hand it over to the user.

../../_images/enroll-qr-2.png

LinOTP generated the initial shared secret and the QR code#

In a second step the user needs to login to the Selfservice Portal and go to the tab “Activate your OCRA2 token” and select the corresponding token. The user needs to enter the activation code, which is displayed on his smartphone and then needs to scan the second QR code, which is displayed in the selfservice portal.

../../_images/enroll-qr-3.png

Finalize OCRA2 Token enrollment#

Now the OCRA2 Token is enrolled and ready for use.

Enroll YubiKeys#

Note

If you want to enroll YubiKeys on Windows, you first need to install additional software: Yubico Personalization Tools

LinOTP supports the YubiKey in all these modes:

  • OATH/HOTP mode - which outputs a 6 digit number according to RFC 4226,

  • Yubico mode - which uses Yubicos own AES-based mode and outputs a 32 characters long OTP value,

  • Static mode - which outpus a static password,

  • Cloud mode - which is the Yubico mode, that is not validated by LinOTP but the request is forwarded to the Yubico Cloud service.

  • Challenge Response mode - which is used by as TOTP mode by the YubiKey NEO NFC.

The OATH mode, Yubico mode and the Challenge Response mode can be programmed to either slot 1 or slot 2 [1] of the YubiKey.

Enrolling OATH/HOTP mode#

The OATH/HOTP mode is identified by the token type “HMAC”, since internally the OATH algorithm is used.

The prefix for the serial numbers is “UBOM”. “OM” stands for OATH mode.

The YubiKey in OATH mode can be enrolled either from the management GUI or from the command line client:

linotpadm.py -U https://localhost --admin=admin -C yubikey_mass_enroll --yubimode=OATH --yubislot=1

This will enroll a YubiKey OATH mode to slot 1.

Note

The serial number that is stored in LinOTP’s database is read from the YubiKey hardware. So if you enroll the same token a second time, it will not create a new token object in LinOTP but will overwrite the old token object.

Enrolling Yubico mode#

The Yubico mode is identified by the token type “yubikey”.

The prefix for the serial numbers is “UBAM”. “AM” stands for AES mode, since internally this algorithm uses AES.

The YubiKey in Yubico mode can only be enrolled using the command line client in mass enrollment:

linotpadm.py -U https://localhost --admin=admin -C yubikey_mass_enroll --yubimode=YUBICO \
             --yubislot=2 --yubiprefixserial

You can choose whether the Yubico mode should be programmed to slot 1 or slot 2. In this example the serial number of the YubiKey is also prefixed in front of the output.

Note

The serial number that is stored in LinOTP’s database is read from the YubiKey hardware. So if you enroll the same token a second time, it will not create a new token object in LinOTP but will overwrite the old token object.

Note

You can in fact enroll a YubiKey in OATH mode in one slot and in Yubico mode in the other slot, which will result in two token objects in LinOTP, which also could be assigned to two different users.

Enrolling static mode#

The YubiKey also can emit a static password. The YubiKey static mode is identified by the token type “pw” [2].

The prefix for the serial numbers is “UBSM”. “SM” stands for static mode.

The YubiKey in static mode can only be enrolled using the command line client in mass enrollment:

linotpadm.py -U https://localhost --admin=admin -C yubikey_mass_enroll --yubimode=STATIC \
             --yubislot=1

You can choose whether the static mode should be programmed to slot 1 or slot 2.

Note

The serial number that is stored in LinOTP’s database is read from the YubiKey hardware. So if you enroll the same token a second time, it will not create a new token object in LinOTP but will overwrite the old token object.

Note

You can in fact enroll a YubiKey in OATH mode or YUBICO mode in one slot and in static mode in the other slot, which will result in two token objects in LinOTP, which also could be assigned to two different users.

Enrolling Cloud mode#

The Cloud mode is identified by the token type “yubico”.

The prefix for the serial numbers is “UBCM”. “CM” stands for Cloud mode.

The YubiKey in Cloud mode can be enrolled via the Selfservice Portal or the management web UI. To enroll via the Selfservice Portal the policy action “enrollYUBICO” needs to be set.

../../_images/webui_selfservice_enroll_yubikey.png

Enroll YubiKey in Cloud mode in the Selfservice Portal#

The YubiKey is used as it comes from Yubico’s factory. The authentication is forwarded to the Yubico cloud service. To assign the YubiKey to the user, the user needs to go to the Selfservice Portal and position the cursor in the entry field “TokenId”, insert the YubiKey and just needs to push the button on the YubiKey. The 12 first characters of the usual 44 characters output is the TokenId. LinOTP will only take the first 12 characters, even if 44 characters are entered.

Note

As the token object in LinOTP gets assigned a new random serial number, enrolling the same YubiKey again will create a second token object in LinOTP, which of course could be assigned to a different user.

Enrolling Challenge Response mode#

The Challenge Response mode is identified by the token type “TOTP”.

The prefix of the serial numbers start with “UBOM”, as this is also an OATH mode.

To enroll a Challenge Response mode run:

linotpadm.py -U https://localhost --admin=admin -C yubikey_mass_enroll \
                                  --yubimode=OATH --yubislot=1 --yubiCR

Note

The serial number of the token in the LinOTP database will be read from the YubiKey hardware. So if you enroll the same token a second time, it will overwrite the token object in the token database.

Footnotes

Enroll E-Mail Token#

To enroll an e-mail token

  1. Choose the tokentype “email”.

  2. If you selected a user and this user has an e-mail address defined in the user store, this address will be automatically entered in the e-mail field. You may of course change this.

  3. Press OK and the token with this e-mail address is created and assigned to the selected user.

Note

Make sure you have the appropriate config entries: E-mail Provider for E-mail Token