Managing token in self service
---------------------------------
Conditions for use
...................
* Policies allow users to take action
For details to define a selfservice policy read
:ref:`self_service_policies`
and :ref:`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 :ref:`self_service_policies` and :ref:`policies` for concerned tokens.
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.
.. For more information on the Selfservice Portal see part :ref:`user_manual`.
.. note:: As long as no selfserivce policy is defined, users are not able to do
anything in the Selfservice Portal.
Typical usecases for supported token in self service
-----------------------------------------------------
Basic actions for tokens
..........................
Extract from the complete list in :ref:`self_service_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
.. _KeyIdentity Authentication Provider: https://www.keyidentity.com/products/keyidentity-authentication-provider
.. _Goggle Play Store: https://play.google.com/store/apps/details?id=com.keyidentity.authenticator&hl=en
.. _Apple Store: https://itunes.apple.com/de/app/keyidentity-authenticator/id1156019084?mt=8
.. _Application-Scenario-Push-Token:
Application Scenario with the KeyIdentity Push Token
.....................................................
The following preparations are necessary to use the KeyIdentity Push Token:
Customize the LinOTP configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Setup scenario for :ref:`keyidentity_push_token`:
+ Set up a challenge-service for :ref:`pushprovider`
+ Define policy for the push token :ref:`policy_ki_push_token`
+ Define policy for the self service :ref:`self_service_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.
|
.. image:: ../images/webui_popup_pushprovider_filled_keyidentity.png
:scale: 75%
|
*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``
|
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: :ref:`Testing of the KeyIdentity Push Token`
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
.. image:: images/LinOTP-authprov-cpl-page1-pic1.png
|
Detailed documentation on the KeyIdentity Authentication Provider is provided
with the KAP 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 'KAP User Guide', which is
part of the documentation of the KAP.
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.
|
.. image:: images/selfservice0-1_handy_KI-App.png
:scale: 25 %
:align: center
|
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.
|
.. image:: images/selfservice2_login2.png
:scale: 50 %
|
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.
|
.. image:: images/selfservice3_enroll_push1.png
:scale: 50 %
|
To scan with the smartphone the following QR code is displayed.
|
.. image:: images/selfservice4_enroll_push2.png
:scale: 75%
|
The smartphone, reset and ready to scan the QR codes.
|
.. image:: images/selfservice4_enroll2.S6_KI-APP_init-Push-Enroll1.png
:scale: 25%
|
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.
|
.. image:: images/selfservice6_activate_push1.png
:scale: 75%
|
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: :ref:`Testing of the KeyIdentity Push Token`.
.. _Application-Scenario-QR-Token:
Application Scenario with the KeyIdentity QR Token
....................................................
The following preparations are necessary to use the KeyIdentity QR Token:
Customize the LinOTP configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Announcing the Apache Certificate for the World. :ref:`issuing_ca`,
* Define policy for the qr token :ref:`policy_ki_qr_offline_token`
* Define policy for the self service :ref:`self_service_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``
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
.. image:: images/LinOTP-authprov-cpl-page1-pic1.png
|
To use the offline function, the permission must be given under 'Offline
Support'.
|
.. image:: images/LinOTP-authprov-cpl-page3-pic1.png
|
Detailed documentation on the KeyIdentity Authentication Provider is provided
with the KAP 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 'KAP User Guide', which is
part of the documentation of the KAP.
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.
|
.. image:: images/selfservice0-1_handy_KI-App.png
:scale: 25 %
:align: center
|
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.
|
.. image:: images/selfservice2_login2.png
:scale: 50 %
|
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.
|
.. image:: images/selfservice3_enroll_qr1.png
:scale: 50 %
|
To scan with the smartphone the following QR code is displayed.
|
.. image:: images/selfservice4_enroll_qr2.png
:scale: 50 %
|
The smartphone, reset and ready to scan the QR codes.
|
.. image:: images/selfservice4_enroll2.S6_KI-APP_init-QR-Enroll1.png
:scale: 25 %
:align: center
|
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.
|
.. image:: images/selfservice6_activate_qr1.png
:scale: 50 %
|
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.
|
.. image:: images/selfservice6_activate_qr2.png
:scale: 50 %
|
The scanning process starts as soon as the camera is touched on the display.
|
.. image:: images/selfservice4_enroll2.S6_KI-APP_init-QR-Enroll2.png
:scale: 25 %
:align: center
|
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.
|
.. image:: images/selfservice6_activate2.S6_KI-APP_QR-Token1.png
:scale: 25 %
:align: center
|
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.
|
.. image:: images/authetication_QR-Token_create_challenge1.png
:scale: 50 %
|
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.
|
.. image:: images/authetication_QR-Token_create_challenge2.png
:scale: 50 %
|
Das Scannen wird mit "Scannen starten" in der KI-APP eingeleitet.
|
.. image:: images/authetication_QR-Token_create_challenge2_s61.png
:scale: 15 %
:align: center
|
In the following dialog, the text from the *message/data:* field can be seen.
The authentication process continues with the **Confirm** key.
|
.. image:: images/authetication_QR-Token_create_challenge2_s62.png
:scale: 15 %
:align: center
|
Immediately before and after *Confirm*, the status display shows the state of
the authentication.
|
.. image:: images/authetication_QR-Token_create_challenge3.png
:scale: 50 %
|
The indented window shows success: *"User succesfully authenticated!"*
|
.. image:: images/authetication_QR-Token_create_challenge4.png
|
The app shows the successful completion in the following picture.
|
.. image:: images/authetication_QR-Token_create_challenge3_s61.png
:scale: 15 %
:align: center
|
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.
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.
.. figure:: 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.
.. figure:: 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.
.. figure:: 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.
.. figure:: 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:
.. figure:: 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.
.. .. figure:: images/selfservice3.png
*Enter all 16 characters of the init secret.*
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.
.. figure:: 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.
.. figure:: 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”.
.. figure:: images/motp-auth.png
.. figure:: images/mOTP_validate_check.png
*Generated One Time Password.*
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!
.. figure:: 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.
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.
.. figure:: 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”.
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.
.. figure:: 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”.
Individualize the Selfservice Portal
--------------------------------------
.. _selfservice_imprint:
Selfservice Portal Imprint
............................
.. index::
Imprint for Selfservice Portal
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.