Selfservice policies

1.6.11. Selfservice policies#

If you want to define policies for users accessing the Selfservice Portal, you need to enter:

  • Policy name : “your policy name”

  • Scope : “selfservice”

  • User : “*, username, regex” for details show Users in policies

  • Realm : “*, realmname”

    You need to put a realm name into the realm field. Then this policy will work for all users within this realm logging in to the Selfservice Portal. You can also put a * into the realm field, thus the policy will be valid for all realms.

  • Client : “FQDN, IP-Addr, Network”

    You may add clients in this policy so that you can define a different behaviour within the Selfservice Portal depending on from where the user will log in to the Selfservice Portal. For details show Clients in policies.

  • Time : Empty means any time

You can now add actions to the resulting users from the realms.

Valid actions are:

mfa_login

Starting with LinOTP 2.10 the login to the Selfservice Portal can be protected with a second factor. This requires the user to have at least one working token for the log in. If the user have multiple tokens a selection menu is displayed. Auto Assignment of tokens works for the log in to the Selfservice Portal Auto Assignment.

mfa_3_fields

This options alters the MFA Selfservice Portal login dialog to show 3 fields (username, password, OTP). The action can only be used as extension to mfa_login.

mfa_passOnNoToken

If the user does not have a token, this action allows the login without OTP. If the user has a token assigned, the OTP of the token is required.

enrollPUSH

The user is allowed to enroll LinOTP Push Tokens. To use the token, the activation is necessary.

activate_PushToken

The user is allowed to activate his Push Token.

enroll_QR

The user is allowed to enroll LinOTP QR Tokens. To use the token, the activation is necessary.

activate_QRToken

The user is allowed to activate his QR token.

enrollEMAIL

The user is allowed to enroll email tokens.

edit_email=<0|1>

Set to ‘1’ to allow the user to set their own mail address for a self enrolled email token (this is the default). If set to ‘0’, the address is received from the UserIdResolver.

enrollSMS

The user is allowed to enroll SMS tokens.

edit_sms=<0|1>

Set to ‘1’ to allow the user to set the mobile number for a self enrolled SMS token (this is the default). If set to ‘0’, the number is received from the UserIdResolver.

enrollHMAC

The user is allowed to enroll HMAC based HOTP tokens.

hmac_hashlib=<int>

Configures the hash library that is used for new HOTP tokens. Possible values are 1 (for sha1), 2 (for sha256) or 3 (for sha512).

hmac_otplen=<int>

Configures the otp length of new HOTP tokens. Allowed values are 6 and 8.

max_count_hotp=<int>

User may retrieve future OTP values of HOTP tokens. Please refer to Retrieving OTP values for details.

enrollMOTP

The user is allowed to enroll mOTP tokens.

setMOTPPIN

The user is allowed to reset/set the mOTP PIN of his mOTP tokens.

enrollOCRA2

The user is allowed to enroll OCRA2 tokens. To use the OCRA2 token, the activation is necessary.

activate_OCRA2

The user is allowed to activate his OCRA2 token.

enrollTOTP

The user is allowed to enroll TOTP tokens.

totp_hashlib=<int>

Configures the hash library that is used for new TOTP tokens. Possible values are 1 (for sha1), 2 (for sha256) or 3 (for sha512).

totp_otplen=<int>

Configures the otp length of new TOTP tokens. Allowed values are 6 and 8.

totp_timestep=<int>

Configures the timestep that is used for new TOTP tokens. Allowed values are 30 and 60.

max_count_totp=<int>

User may retrieve future OTP values of TOTP tokens. Please refer to Retrieving OTP values for details.

enrollU2F

The user is allowed to enroll U2F tokens.

enrollYUBICO

The user is allowed to enroll YUBICO tokens.

max_count_dpw=<int>

User may retrieve future OTP values of Tagespasswort tokens. Please refer to Retrieving OTP values for details.

webprovisionGOOGLE

The user is allowed to enroll HOTP tokens with Google Authenticator compatible presets.

webprovisionGOOGLEtime

The user is allowed to enroll TOTP tokens with Google Authenticator compatible presets.

assign

The user is allowed to assign an already imported token to himself.

unassign

The user is allowed to unassign his own tokens.

enable

The user is allowed to enable his disabled tokens.

disable

The user is allowed to disable his own tokens.

delete

The user is allowed to delete his own token. This token will be removed

completely from the database, but will remain in the audit trail.

reset

The user is allowed to reset the failure counter of his tokens.

resync

The user is allowed to resynchronize his HMAC tokens.

getserial

If this action is active, the token can be assigned by entering the OTP value. You also need to specify the action assign. On the assign tab an additional entry for the OTP value will be displayed.

getotp

The getotp tab will be displayed. Additionally the linotp.ini file needs to be adapted and a policy max_count for the token type needs to be defined.

setOTPPIN

The user is allowed to reset/set the OTP PINs of his tokens.

otp_pin_minlength

Configures the minimal length of the PIN set by the user. For further details see OTP PIN policies.

otp_pin_maxlength

Configures the maximal length of the PIN set by the user. For further details see OTP PIN policies.

otp_pin_contents

Configures allowed characters for the PIN. For further details see OTP PIN policies.

show_landing_page

this action displays a landing page after the successful login of a user in to the selfservice portal. The content of this page can be customized as described here: Customization.

history

If this action is active, the user will see a tab with a list (like Audit Trail) of all actions he did or all the actions an administrator performed on his tokens.

verify

The user needs to verify new tokens after enrollment. Existing tokens can be tested to verify correct functionality. For further details see Verify policy.

Starting with LinOTP 2.5.2 you can also put users or resolvers in the user field. For an explanation on this take a look at Users in policies.

OTP PIN policies#

Policies on how the OTP PIN should look like can be defined for the self service portal. Thus the administrator can assure, that the user chooses a OTP PIN that is secure enough to his opinion.

OTP PIN policies will be checked whenever a user tries to reset an OTP PIN in the Selfservice Portal. The policies are defined like this:

scope = selfservice
realm

A list of comma separated realms, the policy should apply to.

action

Allowed actions are followed by a number or character codes. The actions can be comma separated.

  • otp_pin_maxlength=12 This action would define that the user is only allowed to set OTP PIN with a maximum length of 12 characters.

  • otp_pin_minlength=4 This action would define that the user needs to set an OTP PIN that is at least 4 characters long.

  • otp_pin_contents=cnso This action defines, what characters need to be contained in the OTP PIN: - c: Only OTP PINs containing at least one letter character will be accepted. - n: Only OTP PINs containing at least one digit character will be accepted. - s: Only OTP PINs containing at least one special character will be accepted. - o: Only OTP PINs containing at least one special character, that is not contained in the other character groups, will be accepted.

Example: So if you want your users to choose OTP PINs, that contain letters and number and that should be between 6 and 8 characters long, you should define an action like this:

otp_pin_maxlength=8, otp_pin_minlength=6, otp_pin_contents=cn

Character groups#

The character groups are defined like this.

The default for characters (letters) “c” is the regular expression:

[a-zA-Z]

The default for digits “n” is the regular expression:

[0-9]

The default for special characters “s” is the regular expression:

[.:,;-_<>+*!/()=?$§%&#~^]

The character group “o” contains all characters, that are not contained in one of the above groups.

Changing the character group definition#

These regular expressions can be changed in the linotp.ini file using these parameters:

linotpPolicy.pin_c = [a-ZA-Z]
linotpPolicy.pin_n = [0-9]
linotpPolicy.pin_s = [.:,;-_<>+*!/()=?$§%&#~\^]

Note

Some characters need to be escaped using the “\”.

So if you want the OTP PIN to have an upper letter at any cost, you may change the linotpPolicy.pin_c = [A-Z] and an otp_pin_contents = c. Then setting the PIN will complain, if it does not contain an upper letter.

Reversing the OTP PIN logic#

The default logic is that the OTP PIN must at least contain the specified characters and may contain any more characters, digits or signs that are not required. There are two prefixes to change this logic

  • -:

    The minus sign will require to contain the specified character groups, but will require, that the characters not specified are not used in the OTP PIN.

    Examples:

    • -cn: This will require the OTP PIN to contain at least a letter and a digit. But as soon as the OTP PIN contains a special character or any other character the OTP PIN will not be valid. A PIN like “a12” or “b12” would be OK, but a PIN like “abc” or “test!” would not be valid.

    • -s: The OTP PIN may only contain the specified special characters, not any digits, letters or other characters.

  • +:

    The plus sign will combine the specified character groups. It will require, that characters from any of the character groups are contained in the PIN, but characters not in the character groups must not be contained in the PIN.

    Example:

    • +cn: The PIN needs to contain letters or digits, but must not contain any special characters. A PIN like “123”, “abc”, “a12” would be OK.

Example: If you want to have the user always use PINs that are exactly 4 digits long, you can set:

otp_pin_maxlength=4, opt_pin_minlength=4, otp_pin_contents=-n

Retrieving OTP values#

In the scope=selfservice you can define the following actions:

  • max_count_dpw=<int> for retrieving OTP values of Tagespasswort tokens.

  • max_count_hotp=<int> for retrieving OTP values of HOTP/HMAC tokens.

  • max_count_totp=<int> for retrieving OTP values of TOTP tokens.

These actions are the equivalent to the gettoken actions (see Gettoken Policies). When these actions are defined, the user in such a realm is allowed to retrieve future OTP values of his own OTP tokens. You need to also specify the policy scope=selfservice, action=getotp and edit the linotp.ini file to enable OTP retrieval.

Verify policy#

With verify policy enabled, users have to verify their newly created token before completing the enrollment process in Selfservice Portal. The goal of this policy is to ensure that users have a fully functional and tested token. This makes the enrollment process smoother for users and reduces the need for additional support from administrators. It is especially important when MFA is required to log in to Service. In such a scenario, users could potentially be locked out of Selfservice, if they discover that the token is not working after logging out of the portal.

After enabling this policy, some parts of the Selfservice UI will be enhanced with additional elements to make the verification process more user-friendly and to ensure that tokens are verified. The enrollment dialog will be extended with a verification section that must be successfully completed in order to enroll the token.

../../_images/selfservice_verify1.png

In addition, unverified tokens are marked with a “verify” button to make them easier to identify and verify. When clicked, the button opens a token verification dialog. If a user has no active verified tokens, they will also see a warning message in the token list view, reminding them to verify at least one token before logging out of Selfservice Portal. To use these two features, “Log usage timestamps in token info” must be enabled in the System Config.

../../_images/selfservice_verify2.png

We strongly recommend enabling this policy to ensure a smooth and secure enrollment process for your users.