17.1. Managing token in self service

17.1.1. Conditions for use

• Policies allow users to take action

  For details to define a selfservice policy read Selfservice policies and Users in policies.

• Specific actions in the policies are necessary for the function of the tokens

  For details to define a token specific action in selfservice policy read Selfservice policies and Policies for concerned tokens.

17.1.2. Access Selfservice Portal

The Selfservice Portal can be accessed via

https://your-linotp-server/.

Typical user is a user from a UserIdResolver with user@realm and his password. Its allowed actions are set up via policies.

Note

As long as no selfserivce policy is defined, users are not able to do anything in the Selfservice Portal.

17.2. Typical usecases for supported token in self service

17.2.1. Basic actions for tokens

Extract from the complete list in Selfservice policies

• General functions for all tokens

  actions are: assign - unassign - enable - disable - delete - reset - resync - history

• Activities necessary for the function of the token.

  actions are: enroll… - activate…

  The KeyIdentity Push and QR Token as well as the OCRA tokens require a two-level enrollment with enroll and activate. Other tokens come with the enroll, are imported or provided with autoenroll.

  actions are: edit_email - edit_sms

  The action allows the user to customize the mail or SMS text.

• Actions that are caused by the LinOTP configuration and which must be accepted by the users in the self service.

  • The LinOTP administrator defines policiy (otppin) to use a PIN and its length. Or the user’s password is used in its place.

  • For sms and email token providers are defined, which are effective for the users.

  • Many tokens can only be used in a challenge. The necessary policy is set in scope authentication.

  This means that some activities are effective or have no meaning at the moment.

  action: setOTPPIN can be used if set otppin=0

17.2.2. Application Scenario with the KeyIdentity Push Token

The following preparations are necessary to use the KeyIdentity Push Token:

17.2.2.1. Customize the LinOTP configuration

• Setup scenario for KeyIdentity Push Token:

• Set up a challenge-service for Push Provider for KeyIdentity Push Token

• Define policy for the push token KeyIdentity Push Token Policies

• Define policy for the self service Selfservice policies

As a result, we get a push provider

Use ‘push.keyidetity.com’ in your setup as ‘push_url’, you also need the certificates from there. Inquiries can be directed to mailto:support@keyidentity.com.

Apache Certificate

The use of the KeyIdentity QR and PushToken requires an SSL certificate for the Apache, which is certified by a public certification authority, or created by a CA that is verifiable. For the successful authentication of users on a Windows or MacOS client via the user’s smartphone, a complete and certified certificate chain is necessary.

The policy required for this purpose is as follows

Exported policy.cfg

[Selfservice_Push]

scope = selfservice

action = "enrollPUSH, activate_PushToken, delete"

realm = *

user = *

client = *

time = "* * * * * *;"

active = True

[push_callbacks]

scope = authentication

action = pushtoken_pairing_callback_url=https://challenge-service.example.com/

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

[push_callbacks_challenge]

scope = authentication

action = pushtoken_challenge_callback_url=https://challenge-service.example.com/

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

17.2.2.2. Testing the configuration with a Push Token

• Login to SelfService https://<LinOTP>

• Enroll a push token

• Activat this push token

• Verifying authentication https://<LinOTP>/auth/pushtoken

  See also this section: Testing of the KeyIdentity Push Token

17.2.2.3. Prepare Windows or Apple Clients with KeyIdentity Authentication Provider KAP

Configure KAP (KeyIdentity Authentication Provider) to use the push token

KeyIdentity Authentication Provider

The KAP affords 2FA for the Windows or Apple Desktop

• The LinOTP server desired for the authentication of the 2FA is to be configured. For this, the LinOTP Server certificate is installed. The corresponding documentation comes with the product

Detailed documentation on the KeyIdentity Authentication Provider is provided with the KAP license.

17.2.2.4. Provide the KI APP on the smartphone by the user

The KI app is installed on the user’s smartphone. Look here in Goggle Play Store or Apple Store

The use is intuitive, details are contained in the ‘KAP User Guide’, which is part of the documentation of the KAP.

17.2.2.5. Rollout and activate the push token by the user

With enroll and activate the push token, the token is registered here.

Make sure your mobile phone is installed with the installed AI application. Open the app before you start.

Note

You will only see the Android version of the app. Users with an iPhone will find that their APP works analog.

If your KI-APP is already configured with a QR or Push token, which is no longer required, reset the KI-APP. Under the Settings icon (gear), you will find ‘Reset App’.

To use with the push token, the mobile phone must be online, best suited for this is wifi. Details are described in the user documentation also supplied with the KAP.

• Login at SelfService Portal to manage your token in LinOTP

To make the KI APP usable, roll out a push token. This requires two steps. Beginn in Selfservice Portal to enroll an push token, the corresponding qr-code is scanned with the app. Step 2 uses the self-service activate an push token, which confirms the app on success.

17.2.2.5.1. Step 1 Enroll your Push Token

To initialize the new Push token, select the tab “Enroll your Push Token” in the SelfService and fill the fields:

Token description:

“With a suitable description of the token, visible in the” User View”

Token PIN:

Appears when action ‘otppin=0’ (default) is used in a policy scope ‘authentication’.

If this block is missing, the password of the user ‘otppin=1’ is used.

In accordance with the policy used, this information must also be used in the activation in step 2.

enroll pushtoken

The roll-out starts, a QR code is displayed. This QR code is scanned with the smartphone’s KI APP.

To scan with the smartphone the following QR code is displayed.

The smartphone, reset and ready to scan the QR codes.

After the scan, the phone waits for confirmation of the registration of the push token.

17.2.2.5.2. Step 2 Activate your Push Token

For step two, in the Selfservice Portal:

select the tab ‘Activate Push Token’.

Select Push Token:

In the tab first, select the token from the list on the left.

Enter activation credetians:

This is the one to enter step 1, ie the same PIN or the password (if no PIN was used).

Activate token

The activation begins, the smartphone shows the success and changes the screen, indicates willingness to work with the push token.

17.2.2.6. Test for KI Push Token

A push message can be triggered to test the function of an activated push token.

For details, please follow the link below: Testing of the KeyIdentity Push Token.

17.2.3. Application Scenario with the KeyIdentity QR Token

The following preparations are necessary to use the KeyIdentity QR Token:

17.2.3.1. Customize the LinOTP configuration

• Announcing the Apache Certificate for the World. Issuing Certificate Authority,

• Define policy for the qr token Setup KeyIdentity QR Token

• Define policy for the self service Selfservice policies

Apache Certificate

The use of the KeyIdentity QR and PushToken requires an SSL certificate for the Apache, which is certified by a public certification authority, or created by a CA that is verifiable. For the successful authentication of users on a Windows or MacOS client via the user’s smartphone, a complete and certified certificate chain is necessary.

The policy required for this purpose is as follows

[Selfservice_QR]

scope = selfservice

action = "delete, enrollQR, activate_QRToken, "

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

[qr_callbacks]

scope = authentication

action = qrtoken_pairing_callback_url=https://linotp-srv.my.domain/validate/pair

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

[qr_callbacks_challenge]

scope = authentication

action = qrtoken_challenge_callback_url=https://linotp-srv.my.domain/validate/check_t

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

[offline]

scope = authentication

action = support_offline=qr

user = *

realm = *

client = *

time = "* * * * * *;"

active = True

17.2.3.2. Prepare Windows or Apple Clients with KeyIdentity Authentication Provider KAP

The same procedure as with the push or other token and a bit more for offline.

Configure KAP (KeyIdentity Authentication Provider) to use the keyidentity qr token

KeyIdentity Authentication Provider

The KAP affords 2FA for the Windows or Apple Desktop

• The LinOTP server desired for the authentication of the 2FA is to be configured. For this, the LinOTP Server certificate is installed. The corresponding documentation comes with the product

To use the offline function, the permission must be given under ‘Offline Support’.

Detailed documentation on the KeyIdentity Authentication Provider is provided with the KAP license.

17.2.3.3. Provide the KI APP on the smartphone by the user

The KI app is installed on the user’s smartphone. Look here in Goggle Play Store or Apple Store

The use is intuitive, details are contained in the ‘KAP User Guide’, which is part of the documentation of the KAP.

17.2.3.4. Rollout and activate the keyidentity qr token by the user

With enroll and activate the qr token, the token is registered here.

Make sure your mobile phone is installed with the installed AI application. Open the app before you start.

Note

You will only see the Android version of the app. Users with an iPhone will find that their APP works analog.

If your KI-APP is already configured with a QR or Push token, which is no longer required, reset the KI-APP. Under the Settings icon (gear), you will find ‘Reset App’.

To use with the qr token, the mobile phone must be online, best suited for this is wifi. Details are described in the user documentation also supplied with the KAP.

• Login at SelfService Portal to manage your token in LinOTP

To make the KI APP usable, roll out a qr token. This requires two steps. Beginn in self-service enroll an push token, the corresponding qr-code is scanned with the app. Step 2 uses the self-service activate an qr token, which confirms the app on success.

17.2.3.4.1. Step 1 Enroll your QR Token

To initialize the new QR token, select the tab “Enroll your QR Token” in the SelfService and fill the fields:

Token description:

“With a suitable description of the token, visible in the” User View”

Token PIN:

Appears when action ‘otppin=0’ (default) is used in a policy scope ‘authentication’.

If this block is missing, the password of the user ‘otppin=1’ is used.

In accordance with the policy used, this information must also be used in the activation in step 2.

enroll qrtoken

The roll-out starts, a QR code is displayed. This QR code is scanned with the smartphone’s KI APP.

To scan with the smartphone the following QR code is displayed.

The smartphone, reset and ready to scan the QR codes.

After the scan, the phone waits for confirmation of the registration of the qr token.

17.2.3.4.2. Step 2 Activate your QR Token

For step two, in the Selfservice Portal:

select the tab ‘Activate QR Token’.

Select QR Token:

In the tab first, select the token from the list on the left.

Enter activation credetians:

This is the one to enter step 1, ie the same PIN or the password (if no PIN was used).

Activate token

The activation begins, the smartphone shows the success and changes the screen, indicates willingness to work with the push token.

The QR code now displayed is also scanned in step 2/2 with the KI APP of the smartphone.

OTP Value:

This field remains empty. It is only used if the KI App of the mobile phone should show an OTP value after scanning the QR code.

finalize activation

The key has only one function when an OTP value has been entered. Otherwise, it results in a wrong message.

The scanning process starts as soon as the camera is touched on the display.

If this step is successful, the following screen appears on the mobile phone and the QR Token in the KI-APP is available for authentication with the 2-factor.

17.2.3.5. Test for KI QR Token function with /auth/qrtoken

An active KeyIdetity QR token can be test at https://<linotp-srv.my.domain>/auth/qrtoken.

This portal allows the function test of its KeyIdentiy QR Token.

Enter the necessary data under “Create challenge:”

username:

Hier den Anmeldenamen wie im Selfservice Portal verwenden

OTP PIN:

The PIN that was given when the token was enrollment. Depending on the application, this is the PIN or the user password. This is the same value that is used for normal login.

message /data:

A message that is displayed in the KI-APP. (Optional)

get challenge

Initiates communication for authentication between LinOTP and the token in the KI App. You will receive a QR code, which is scanned with the KI-APP.

The QR code is scanned with the configured KI-App. For every further step, the button “checkStatus” can be used to query the current status during ongoing authentication.

Das Scannen wird mit “Scannen starten” in der KI-APP eingeleitet.

In the following dialog, the text from the message/data: field can be seen. The authentication process continues with the Confirm key.

Immediately before and after Confirm, the status display shows the state of the authentication.

The indented window shows success: “User succesfully authenticated!”

The app shows the successful completion in the following picture.

17.2.4. Enrolling OATH Token for Google Authenticator

LinOTP also supports the Google Authenticator, that is available for Android phones and iPhones and the “OATH Token” for iPhones.

These tokens can be easily enrolled using the two dimensional QR code. Install the Google Authenticator or OATH Token via app store. In the Selfservice Portal either choose “Enroll OATH Token” or “Enroll Google Authenticator”, click on enroll and use the camera of your phone to scan the QR code picture.

17.2.5. Using mOTP Token

LinOTP provides a self service interface that can be used by the user to register a new mOTP 31 token completely on his own. mOTP is a one time password algorithm. For this algorithm many different applications to run on mobile phones, smart phones and iPhone and iPad are available. Your Administration or IT department should have provided you the download link from where to install the mOTP application to your smartphone. In this workflow the MobileOTP.jar Java Midlet from http://motp.sourceforge.net is used.

17.2.5.1. Initializing the mOTP Token

After installing the midlet to your phone, you need to initialize the application. Start the MobileOTP application.

The icon to start the application on your phone.

The OTP token can be initialized by entering the PIN “0000”. This can be repeated at any time afterwards.

By entering the PIN ‘0000’ the token can be initialized any time.

Now you need to put in 25 random numbers, that are used to create the init secret.

Now the init secret is displayed. You should not write this down and not show it to any other, since this is the very secret that is used to calculate the OTP values. This secret is only displayed once. As soon as you enter the PIN, the secret can not be displayed anymore.

The init-secret is only displayed once.

17.2.5.2. Registering the mOTP Token

You now need to open the LinOTP Selfservice Portal. Open your web browser and go to the address that was given to you by your IT department. It should be something like: https://linotp.yourdomain.com/ Then you need to login to the Selfservice Portal.

LinOTP Selfservice Portal login screen.

Here you should login using the credentials. This will be probably your domain credentials. For more details consult your IT department.

When successfully logged in, you are presented this screen:

LinOTP Selfservice Portal registering screen.

At the start no tokens will be displayed on the left hand side. On the right hand side, you need to enter the Init-Secret, that is displayed on your phone. Also enter an mOTP PIN, that you will enter into the MobileOTP application on your phone, each time you want to generate an OTP value. This mOTP PIN needs to be a 4 digit number.

When you press the button “register Token” your token data gets registered in the backend and assigned to your user. You will now see a token identifier on the left hand side.

A token is assigned to the user.

You may now set an additional OTP PIN.

This OTP PIN a fixed password, that is entered in front of the OTP value, each time you will authenticate. The OTP PIN can be an alpha numerical value. For this click on “set OTP PIN” and click on the token identifier on the left hand side.

Setting the OTP PIN for a token.

Press the Button “set PIN” and log out.

17.2.5.3. Authenticating using mOTP Token

Probably you will use the mOTP Token to authenticate to a web site, a VPN connection or to a terminalserver.

When doing so, you need to:

1. Enter your username into the login dialog username field

2. Enter your OTP PIN (the alpha numerical value) into the login dialog password field 3. Enter your mOTP PIN (the 4 digit number) into your MobileOTP application on your phone.

3. Your phone will display a one time password.

4. Now enter this one time password (0caa10) right behind the OTP PIN in the password field in the login dialog. 6. Press a button like “login”.

Generated One Time Password.

17.2.6. Disable lost token

If you lost your token or left it somewhere so that someone else might probably use your token, you should go to the Selfservice Portal to disable your token. Please note, that only an administrator can enable the token again!

Disabling a lost token.

Choose “Disable Token” and select the token from the left side. Press the button “disable Token”. Logging in with this token will not be possible until it gets enabled by an administrator.

17.2.7. Change OTP PIN

If you forgot your OTP PIN or if you think, that someone spied on you and knows your OTP PIN, you can go to the Selfservice Portal to reset your OTP PIN.

Reset OTP PIN.

Select “set PIN” and choose the token of which you want to reset the OTP PIN from the left side. The serial number of the token will be displayed in the field “selected Token”. Enter a new OTP PIN two times and press the button “set PIN”.

17.2.8. Resynchronize Token

As these tokens are event based tokens, you might get out of sync, if the button on a token is pressed to often without having authenticated successfully. In this case you can go to the Selfservice Portal to resynchronize your token.

Resynchronizing an eToken PASS.

Choose “resync Token” and select the token from the left side. Now you need to generate two successive OTP values with your token. Enter the first 6 digit OTP value in the field “OTP 1” and the second 6 digit OTP value in the field “OTP 2” and press the button “resync Token”.

17.3. Individualize the Selfservice Portal

17.3.1. Selfservice Portal Imprint

You may define an imprint or contact information page for your self service portal. This can be different for each realm. Therefor you can create a different file and thus different information for each realm. The files have to be located at:

/etc/linotp2/imprint/<realm name>.imprint

This file may contain HTML code, so that you can add styles and links.