LinOTP's Rollout Token Feature

This how-to describes a typical use case of the rollout token feature and the required configuration steps.

It's about security...

Multi Factor is about security and so is every step involved. The authentication procedure, the seed storage, encrypted communication protocols. The overall security is just as weak as the weakest point in the process.

The Enrollment Process

One important step is the enrollment or assignment of tokens. So let's assume the user should use OATH soft token. The seed must be placed on the user's mobile. Typically this is achieved by scanning a QR code which contains the shared secret. For security reasons only the user itself should ever see this QR code so it is very sensible that the user enrolls the token himself without any involment of a third party like help desk employees.

LinOTP Self Service Portal

LinOTP provides for this purpose the self service portal. Although the actions - like token enrollment - can be limited to local network clients it might be necessary that users from untusted networks can enroll their tokens as well. By default the username and the user password are requrired to log in to self service portal. This would mean that the enrollment of the second factor depends on the knowledge of the first one. No clean separation and a possible weak link which could be exploited by an attacker. In order to prevent this attack vector the self service should be protected with a second factor. This is very sane and can be configured easily in LinOTP.

The Problem

But wait - what should a user do who has no token yet because the token is to be enrolled via the self service portal?

The Solution - an exclusive rollout token

The user needs a token which can only be used to login to the self service portal and not for any other authentication way. This is the rollout token. Every type of token can be used for this purpose - but during enrollment the token is declared to be for self service only. So for example an IAM system could create a static password token during the onboarding process of the user and mark it as rollout token. This password is transmitted to the user via a secure channel (like encrypted E-Mail). The user logs in to the self service portal with username, password, OTP and enrolls the actual token.

Now the enrollment procedure is better secured. An attacker would need to have access to the password of the user and the encrypted e-mail. It would also be possible to print the OTP-password and hand it personally or via mail to the user or tell the user via phone. In the unlikely case the attacker steals the rollout token it can not be used for any authentication except the self service portal which is addionally secured with the users normal credentials.

As stated before every type of token can be used as rollout token. So be it a soft token, a SMS token or even Yubikey which is sent back by the user after the rollout procedure.

How to appoint a rollout token

Every token can be declared as rollout token. For sake of simplicity we will use a static password token. This token is enrolled via API and a parameter "rollout" is added to the API call.


This parameter is the magic key - it can be combined with any token during enrollment in order to make this token a rollout token.

Explanation of the URL components:

This is the IP or FQDN of the LinOTP server
The controller used for enrollement (and a lot of other interesting staff:
user [optional]
Name of the user for whom the token is enrolled. The token can also be enrolled without a user name and assigned later.
The type of the enrolled token. Different types of token require different additional options.
This parameter contains the password which acts as OTP. This is a specific parameter for tokens of the type "PW"
description [optional]
The description will be displayed in the token management GUI. If it is left out it will contain "rollout token".
rollout [optional]
This parameter declares the enrolled token as rollout token and limits it's usage to the self service portal only.
A valid session cookie is required - not every body should be able to enroll tokens ;)


Details about using LinOTP's API (like session handling) can be found here:

This is what LinOTP returns for a static password token roll out:

  "detail": {
     "serial": "KIPW0001C2BB",
     "otpkey": {
        "img": "<img id=\"challenge_qrcode\"    width=200   src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAABd0lEQVR4nO2YS26EMBBEXwekLOFG+GZzNThKbmAvI4EqC5sZRomU2fAZaC8sq/UkSqZdbreJ/8fw8QIETjnllFNOHZ2yMmoYWoA0R8Kuui5BdZKkCBYAC1SSJD1T2+u6BJVKjqtPNeqBfAz21nUpqtP37DQbfdGpMiykz98l//66zkjNttIISCBSiSz/wFHVn4IazMysLXctMOUyZ29dp6Zy3j9yXKTJyjHYU9cVKHIp2cUqT5LGOTav1B9V/XtTZZ9ptNh29Y1EpzL53q9KdXEyC6mGwWosAJDc7zehUg00I3aLoJ5s+v6uXZNa1Jg2WCVIYF1EtqCOqv69qWLw95FjffO4A9zv16UefUz1QLGg5H3MVal7PSlJscrNzEXKe96vT805btaC9FXn1e66rkSpp7q/aSevMbek7BbBQjNCFytZOIiuM1J/9jFFahFMtfbSdQWKR2UJ2W4q0UWAZsR7CitSv/uYedJT/KjqnXLKKaecepX6AZtl2Yj72/NiAAAAAElFTkSuQmCC\"/>",
        "order": "1",
        "value": "seed://Start123!",
        "description": "OTP seed"
  "version": "LinOTP 2.10.3",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": true
  "id": 1

Now the token can be found in the token management GUI:

Transfer the password (or the QR code in case of a OATH soft token) to the user over a secure channel.

The rollout procedure of the actual token

The self service portal should be protected with 2FA.

This can be achieved by this policy:

The user access the self service portal: https://LINOTP:

The static password is entered in the OTP field. In case of e.g. an OATH token the OTP must be provided.

Now the user is logged in and can enroll the actual token:

The user possesses two token now:

Both tokens can be used to log in to the self service portal but only the new enrolled OATH token works for all other authentication procedures.

Remove unrequired rollout token automatically

By default the rollout token stays until actively delete. For security reasons it might be sensible to remove the rollout token once the user has the final token. This can be configured via policy:

This policy will delete the rollout token automatically after the user has successfully authenticated with another token. So this is a useful to clean up unnecessary (because successfully used) rollout token.

Please mind - the rollout token is not directly delete after the rollout of a new token. It is removed after the first successful usage of another token. This is to mitigate problems during the rollout process of the final token, e.g. if the user forgets to scan the QR code. Because the rollout token is still active the user can try the rollout again. So the user has to prove a successful rollout via authentication with the new token, before the rollout token is purged. This authentication can happen either at the self service portal itself or any other way of authentication.