LinOTP 2.7 documentation
previous | next | index

6.6. Enrolling tokens

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

  • eToken NG-OTP,
  • mOTP tokens,
  • HOTP, TOTP and OCRA tokens,
  • QR-TAN tokens,
  • LSE simple Pass tokens,
  • SMS OTP / Mobile TAN,
  • Remote Tokens,
  • RADIUS Tokens,
  • Yubikeys,
  • E-Mail Tokens.

6.6.1. Enroll eToken NG-OTP

Note

An eToken NG-OTP can only be enrolled using the GTK client or 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.

  1. Push the button enroll token.

  2. You may choose a user as you did during token assignment, but you may also leave the user blank. This enables you to mass-enroll eToken NG-OTP tokens and assign the tokens to users later.

    ../../_images/enroll-etng.png

    Enroll an eToken NG-OTP using the GTK client

  3. Leave the Tokentype as it is.

  4. Plugin one eToken NG-OTP. Be sure to have no other eTokens connected!

  5. Push the button OK.

  6. After enrolling the token you may also want to set the OTP PIN.

Note

During enrollment the eToken NG-OTP gets initialized.

Warning

All data on the token will be lost!

In the management client configuration you may choose, if the eToken NG-OTP should be initialized with random User PINs and SO PINs or if you want to set the PINs manually. The SO PIN is stored in the tokenbase for later use, for example resetting the User PIN.

6.6.2. 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, you can do this in the GTK client by choosing an mOTP token and right-clicking the token and select “set mOTP pin”. In the Web UI click “set PIN” a 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

6.6.3. Enroll HOTP / OATH Token

You may realize, that there are several softtokens (e.g. for mobile phones) around that use the HOTP algorithm defined in RFC4226. Some of these tokens generate the HMAC secret key during an initialization process. For these tokens, you may choose to enroll “HOTP token” and than enter the HMAC key in this dialog.

  1. Choose tokentype as “OATH”
  2. Enter the secret, that was generated by the token.

This looks pretty much the same in the GTK client and in the Web UI.

../../_images/enroll_oath_gtk.png

Enroll an OATH token with the GTK client

../../_images/enroll_oath_webui.png

Enroll an OATH token with the Web UI

As a matter of fact the Web UI offers an additional functionality to enroll a soft OATH token. 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/enroll_oath_webui_google.png

Enroll a Google Authenticator using a QR code

6.6.4. Enroll LSE Simple Pass Token

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.

To enroll a Simple Pass token

  1. choose the tokentype “SPass”
  2. push the button “OK”.

If you do not set an OTP PIN now, the user will get successfully authenticated ALWAYS! So you now should set an OTP PIN for this token. The user may now authenticate against LinOTP by providing only this PIN.

6.6.5. 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.

6.6.6. 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.

6.6.7. 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.

6.6.8. Enroll QR-TAN Token

A QR-TAN Token is a special OCRA 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 QR Token via the management web UI.

Note

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

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

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

Start enrolling a QR 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 .... 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 QR Token enrollment

Now the QR Token is enrolled and ready for use.

6.6.9. Enroll Yubikeys

Note

If you want to enroll Yubikeys on Windows, you first need to install additional software as described in Installing Yubikey components.

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.

6.6.9.1. 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.

../../_images/enroll_yubikey.png

Enroll Yubikey in OATH mode in the management GUI

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.

6.6.9.2. 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.

6.6.9.3. 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.

6.6.9.4. 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/enroll_yubikey_cloud.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.

6.6.9.5. 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

[1]The Yubikey has two slots, that can hold different content. The first slot is used by pressing the button shortly, the second slot is used by pressing the button for about 3 seconds.
[2]The token type “pw” is a static password that can be prepended with an OTP PIN. This token type is also used in the lost token scenario.

6.6.10. 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

Table Of Contents

Search

Enter search terms or a module, class or function name.

previous | next | index
Show Source
© Copyright 2014, LSE Leading Security Experts GmbH. Created using Sphinx 1.1.3.