2.1. Managing token in self service#

2.1.1. Conditions for use#

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

2.2. Typical usecases for supported token in self service#

2.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 LinOTP Push and QR Token as well as the OCRA2 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

2.2.2. Application Scenario with the LinOTP Push Token#

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

Customize the LinOTP configuration#

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@linotp.de.


../_images/webui_popup_pushprovider_filled1.png

Apache Certificate

The use of the LinOTP 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


Testing the configuration with a Push Token#

Prepare Windows or Apple Clients with LinOTP Authentication Provider LAP#

Configure LAP (LinOTP Authentication Provider) to use the push token

LinOTP Authentication Provider

The LAP 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

../_images/LinOTP-authprov-cpl-page1-pic1.png

Detailed documentation on the LinOTP Authentication Provider is provided with the LAP license.

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 ‘LAP User Guide’, which is part of the documentation of the LAP.

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.


../_images/selfservice0-1_handy_KI-App.png

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

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


../_images/selfservice2_login2.png

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.


../_images/selfservice3_enroll_push1.png

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


../_images/selfservice4_enroll_push2.png

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


../_images/selfservice4_enroll2.S6_KI-APP_init-Push-Enroll1.png

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

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.


../_images/selfservice6_activate_push1.png

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 LinOTP Push Token.

2.2.3. Application Scenario with the LinOTP QR Token#

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

Customize the LinOTP configuration#

Apache Certificate

The use of the LinOTP 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

Prepare Windows or Apple Clients with LinOTP Authentication Provider LAP#

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

Configure LAP (LinOTP Authentication Provider) to use the LinOTP QR token

LinOTP Authentication Provider

The LAP 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

../_images/LinOTP-authprov-cpl-page1-pic1.png

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


../_images/LinOTP-authprov-cpl-page3-pic1.png

Detailed documentation on the LinOTP Authentication Provider is provided with the LAP license.

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 ‘LAP User Guide’, which is part of the documentation of the LAP.

Rollout and activate the LinOTP 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.


../_images/selfservice0-1_handy_KI-App.png

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

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


../_images/selfservice2_login2.png

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.


../_images/selfservice3_enroll_qr1.png

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


../_images/selfservice4_enroll_qr2.png

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


../_images/selfservice4_enroll2.S6_KI-APP_init-QR-Enroll1.png

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

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.


../_images/selfservice6_activate_qr1.png

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.


../_images/selfservice6_activate_qr2.png

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


../_images/selfservice4_enroll2.S6_KI-APP_init-QR-Enroll2.png

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.


../_images/selfservice6_activate2.S6_KI-APP_QR-Token1.png

Test for KI QR Token function with /auth/qrtoken#

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

This portal allows the function test of its LinOTP 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.


../_images/authetication_QR-Token_create_challenge1.png

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.


../_images/authetication_QR-Token_create_challenge2.png

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


../_images/authetication_QR-Token_create_challenge2_s61.png

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


../_images/authetication_QR-Token_create_challenge2_s62.png

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


../_images/authetication_QR-Token_create_challenge3.png

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


../_images/authetication_QR-Token_create_challenge4.png

The app shows the successful completion in the following picture.


../_images/authetication_QR-Token_create_challenge3_s61.png

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

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

Initializing the mOTP Token#

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

../_images/motp-icon.png

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.

../_images/motp-init1.png

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.

../_images/motp-init2.png

The init-secret is only displayed once.#

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.

../_images/selfservice1.png

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:

../_images/selfservice2.png

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.

../_images/selfservice4.png

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.

../_images/selfservice5.png

Setting the OTP PIN for a token.#

Press the Button “set PIN” and log out.

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

../_images/motp-auth.png
../_images/mOTP_validate_check.png

Generated One Time Password.#

2.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!

../_images/disable.png

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.

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

../_images/otppin.png

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

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

../_images/resync.png

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

2.3. Individualize the Selfservice Portal#

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