6.5. Enrollment Policies¶
Enrollment Policies are checked during the enrollment process of a token. This applies for administrative enrollment or user self enrollment.
6.5.1. Token limits per Realm¶
You may limit the number of tokens that are managed within a realm. This is done by defining a policy consisting of
Policy name: This is the unique name of the policy.
Scope: You need to set this to enrollment.
Realm: Enter the name of the realm here.
Action: This field is comma separated. It should contain the keyword tokencount = <tokennumber>.
Using the action tokencount you may allocate specified numbers of tokens to your different realms.
You may for example have a license with 1000 tokens, but one of your five realms should only be able to manage a maximum of 80 tokens, since this realm is managed by another department.
Note
Each realm, for which no tokencount is defined, may use as many tokens as possible.
6.5.2. Token limits per user¶
You may limit the number of tokens that can be assigned to a user. It is possible to limit the number of tokens per user in total and the numbers of tokens per user by type.
6.5.2.1. Total number of tokens per user:¶
Policy name: This is the unique name of the policy.
Scope: You need to set this to enrollment.
Realm: Enter the name of the realm, that contains the users who should be restricted in the number of tokens owned.
Action: This field is comma separated. It should contain the keyword maxtoken = <tokennumber>.
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Note
If there is no maxtoken defined for a realm, then you may enroll as many tokens as possible for a single user.
6.5.2.2. Number of tokens per user by type:¶
Starting with LinOTP 2.10 it is possible to limit the number of tokens per user by type. Any additionally configured maxtoken action as described above will limit the total number of tokens per user.
Policy name: This is the unique name of the policy.
Scope: You need to set this to enrollment.
Realm: Enter the name of the realm, that contains the users who should be restricted in the number of tokens owned.
Action: This field is comma separated. It should contain the keyword maxtoken<TokenTyp> = <tokennumber>.
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Example:
Allow every user to have maximal 1 SMS, 2 HMAC token and 5 in total:
[maxtoken]
action = "maxtokenSMS=1, maxtokenHMAC=2, maxtoken=5,"
user = *
realm = *
time = * * * * * *;
client = *
scope = enrollment
active = True
6.5.3. Random OTP PIN¶
During enrollment a random OTP PIN may be set. This is done per realm by defining the policy:
Policy name: This is the unique name of the policy.
Scope: You need to set this to enrollment.
Realm: Enter the name of the realm, that contains the users who should be restricted in the number of tokens owned.
Action: This field is comma separated. It should contain the keyword otp_pin_random = <length>. This will create a random OTP PIN with the given length during token initialization.
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Note
If there is no otp_pin_random defined for a realm, than no PIN is set during enrollment. If a random OTP PIN is set, it is not possible to view this PIN. This means, that the user or the administrator has to reset the OTP PIN.
6.5.4. Encrypted OTP PIN¶
During setting an OTP PIN this policy defines, if the OTP PIN will be stored as hashed value or as an encrypted value. The default behavior is to store the OTP PIN as a hashed value.
Policy name: This is the unique name of the policy.
Scope: You need to set this to enrollment.
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for.
Action: This field is a comma separated list. It should contain the keyword otp_pin_encrypt = 1.
Note
The encrypted value can be decrypted again. This is used in case of getOtp function. Usually it is a good idea to leave this untouched.
6.5.5. Token issuer¶
It is possible to set a token issuer for OATH token which is displayed e.g. in the Google Authenticator or other token apps.
You may define a policy which defines the token issuer.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm the policy should be valid for. Newly generated tokens in this realm will be labeled accordingly.
Action: This is a comma separated list. It should contain tokenissuer=<string>, where <string> may contain arbitrary characters/strings and placeholders:
<u> will be replaced with the name of the user
<r> will be replaced with the name of the realm
<s> will be replaced with the serial number of the token.
<d> will be replaced with the token description.
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Example: issuer=my_company will result in an issuer my_company and will be displayed in the token applications accordingly.
6.5.6. Token labels¶
It is possible to set a token label for the Google Authenticator and OATH token. This policy defines the content of the token label - it may contain arbitrary text and variables.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
Action: This is a comma separated list. It should contain tokenlabel=<string>, where <string> may contain arbitrary characters/strings and placeholders:
<u> will be replaced with the name of the user
<r> will be replaced with the name of the realm
<s> will be replaced with the serial number of the token.
<d> will be replaced with the token description.
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
If no policy can be found or the token is not assigned to any user, then the token will be labeled with the serial number.
Example: tokenlabel=<u>@<r> will result in a label like username@realm1. tokenlabel=ourtokens_<s> will result in something like outtokens_oath1278489.
6.5.7. Auto Assignment¶
Enrolling tokens to users can be a time consuming process. With auto assignment LinOTP provides an easy way to assign existing tokens to users which don’t have a token yet. One can configure auto assignment like this:
First you need to import the token seed file and set the token realm of these tokens.
Then you need to configure an auto assignment policy.
After having done so, the enrollment workflow is as follows:
Tokens are set to realmA but not assigned.
The user, who is in realmA, grabs any of those realmA tokens.
Now he authenticates against LinOTP using his user store password, which will be either the passwd-password, the LDAP-password or his SQL-password and an OTP value from the token he just grabbed.
Note
Please have a look at the Autoassigment without Password Check if no password should be required.
LinOTP will check, - if the auto assignment policy is set for this realm,
if the user has not yet any token assigned,
if the user provided the right password,
and then look up the token for the given OTP value in the tokens of realmA that are not yet assigned.
LinOTP then will assign the found token to the user and set the user store password as OTP PIN.
The user is successfully authenticated and will have to use this very token for all future logins.
The auto assignment policy is defined like this:
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
- Action: This is a comma separated list. It should contain:
autoassignment (LinOTP version >=2.8) or autoassignment=<int>, where <int> is either 1 for active or 0 for deactivated. (LinOTP version <=2.7.2.1)
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Note
Please be aware: If a token is auto assigned the password from the UserIdResolver is stored as PIN in the LinOTP database. This will happen even if policies are configured like otp_pin_random or otppin=1 or otppin=2. You can avoid this behaviour with a policy ignore_autoassignment_pin as described below. Otherwise we recommend for security reasons to request the users to set in individual PIN in the Selfservice Portal after the auto assignment. The necessary policy setOTPPIN is described in Selfservice policies
Note
Auto assignment only works for users without tokens.
6.5.8. Ignore Auto Assignment Pin¶
When using the auto assignment feature the user is identified by his login name and by the password (PIN), while the token is identified by the otp value. If the identification of user and token was successful, by default the password of the user will be used as PIN of the token. To prevent this behaviour the ignore_autoassignment_pin policy can be set.
6.5.9. Autoassigment without Password Check¶
Starting with LinOTP 2.10 a new action is available for auto assignment: autoassignment_without_password. In difference to the regular auto assignment the user’s password is not required for the token assignment. So the user authenticates with name and OTP value only and the auto assignment is performed. This is useful for environments where the user’s password has already been validated otherwise.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
- Action: This is a comma separated list. It should contain:
autoassignment_without_password
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
6.5.10. Lost token¶
When a user looses a token, the help desk can enroll a temporary token that will replace the lost token. The lost token will be disabled. The OTP PIN of the lost token will be used for the new temporary token. The administrator or the help desk employee do not know the token PIN - it is transfered by LinOTP to the new token. The temporary token will be a long static password and will only be valid for a restricted period of time. The length of the password and the validity period can be configured using a enrollment policies:
Scope: enrollment
Action: lostTokenPWLen=<length of password> (default = 10)
Action: lostTokenValid=<length of validity period> (in days, hours, minutes, seconds, defaults to 10 days)
Action: lostTokenPWContents=<contents of the temporary password>
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
Explanation for lostTokenValid:
The following time units can be used:
d: days (default)
h: hours (LinOTP 2.10+)
m: minutes (LinOTP 2.10+)
s: seconds (LinOTP 2.10+)
Examples:
lostTokenValid=12h
lostTokenValid=5d
lostTokenValid=1d12h
lostTokenValid=5h30m30s
Explanation of lostTokenPWContents
The contents is described by these characters:
C: The password will contain upper characters.
c: The password will contain lower characters.
n: The password will contain digits/numbers.
s: The password will contain special characters.
Example: A temporary token with lostTokenPWLen=10, lostTokenValid=30 will get a 10 characters static password created and will be valid for the next 30 days.
6.5.11. Purge rollout tokens¶
Starting with LinOTP 2.10.3 a token can be marked as rollout token. In consequence this token can only be used for the login to the self service portal. This can be very useful for the initial token rollout in combination with a MFA protected self service. The user gets the rollout token, logs into the self service and enrolls the actual token.
This policy will delete the rollout token automatically after the user has successfully authenticated with another token. So this is a clean up function for unnecessary (because successfully used) rollout token.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
- Action: This is a comma separated list. It should contain:
purge_rollout_token
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
6.5.12. U2F App ID¶
This policy defines which application IDs can be validated via FIDO U2F in LinOTP.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
- Action: This is a comma separated list. It should contain:
u2f_app_id=APPID
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
More details about U2F can be found here: https://www.linotp.org/doc/latest/part-management/managingtokens/fido_u2f.html
6.5.13. U2F Valid Facet¶
This policy defines which URLs can be validated via FIDO U2F in LinOTP.
Policy name: This is the unique name of the policy.
Scope: enrollment
Realm: Enter the name of the realm, that contains the tokens, the policy should be valid for. The tokens of users in this realm will be labeled accordingly.
- Action: This is a comma separated list. It should contain:
u2f_valid_facets=URL1;URL2
User: Here you can enter a list of usernames or resolvers. See Users in policies for more details.
More details about U2F can be found here: https://www.linotp.org/doc/latest/part-management/managingtokens/fido_u2f.html