6.3. Authentication Policies

Some authentication policies are also making use of the client field. This is described in the policy.

6.3.1. OTP PIN variants

This policy configures the origin and the handling of the OTP PIN.

The PIN can be:

  • set per token
  • the user’s password from user storage
  • can be completely ignored

Define a policy like this:

  • Policy name: This is the unique name of the policy. Scope: You need to set this to authentication.

  • Realm: Enter the name of the realm here.

  • Action: This field is comma separated. It should contain the keyword otppin = <id>|<name>. <name> is suppported starting with LinOTP 2.9.

    <id> and <name> can have one of the following values:

    • 0 or token_pin: This is the default behavior. In addition to the OTP value the user needs to enter a fixed OTP PIN, that is defined per token (PIN+OTP).
    • 1 or password: In addition to the OTP value the user must enter the password from his user database, e.g. his LDAP or Active Directory password (in case of LDAPUserIdResolver) or his password in the Passwd-File or in the SQL Database (UserPW+OTP).
    • 2 or only_otp: The user does not need to enter any additional OTP PIN and will be authenticated only with the OTP value (OTP).
  • User: This is a list of users or resolvers, for whom this policy will be valid. Please see Users in policies.

  • Client: This is a list of IP addresses or IP subnets.

Note

Using this policy you can setup scenarios, where a user needs to provide a PIN, for log-in from the SSL VPN but does not need to provide an OTP PIN when loggin in from the Radius Credential Provider.

Note

otppin=1 is a useful setting for Auto Assignment and Auto Enrollment.

6.3.2. Authentication Passthrough

When this is activated, users who have no token assigned, will be authenticated against the password in their UserIdResolver.

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: Enter the name of the realm.
  • Action: passthru
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

Note

Using this policy you can setup smooth rollout scenarios. Every user will have to authenticate with her active directory password until the user gets an OTP token enrolled. In such an enrollment scenario you could combine this policy with the OTP PIN policy otppin=1. Thus a user will authenticate with the AD password and will have to add the OTP value to the fixed AD password as soon as she has a token assigned.

6.3.3. Pass on no Token

If there is no token assigned to a user, the authentication request for this user will always be true, no matter which password is provided.

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: Enter the name of the realm.
  • Action: passOnNoToken
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

6.3.4. Challenge Response

LinOTP can authenticate the user in a challenge response way. I.e. in the first authentication request only the OTP PIN will be passed and in the second authentication request only the OTP value will be passed. This behaviour can be activated on a per token, per realm and per client basis using this policy.

Set up the policy like this:

  • Policy name: This is a unique name of the policy.

  • Scope: authentication

  • Realm: One realm, a comma separated list of realms or ‘*’

  • Action: challenge_response= <Token type list>

    Available token types are:

    • HMAC - event based token
    • TOTP - time based token
    • PW - password token (as used in the lost token scenario)
    • “*” - all token capable of challenge response mode
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

The Token type list is a white space separated list of token types, which can also contain the ‘*’. This policy will be valid for the corresponding token types.

6.3.5. Forward request to remote server

Starting with LinOTP 2.8.1 authentication requests can be forwarded either to other LinOTP instances or other RADIUS server. This can e.g. be used instead of Remote Token to minimize configuration effort.

  • Policy name: this is a unique name of the policy.

  • Scope: You need to set this to authentication.

  • Realm: Enter the name of the realm.

  • Action for remote LinOTP server:

    forward_server=https://REMOTE_LINOTP/validate/check

  • Action for remote RADIUS server (please mind to configure LinOTP as valid client in the remote RADIUS server):

    forward_server=radius://RADIUSSERVER:PORT/?secret=SECRET

  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.

  • Client: This is a list of IP addresses or subnets this policy is valid for.

Please be aware: once the RADIUS secret is set it is not displayed anymore when looking at the forward policy. Instead - for security reasons - only encsecret is displayed.


Example remote LinOPT server:

Scope: authentication
Action: forward_server=https://remote_linotp/validate/check
Realm: financials

Example remote RADIUS server:

Scope: authentication
Action: forward_server=radius://radius_server:1812/?secret=kjD28fSER9cW#SS1VlsCCE$#SAGH#$RRVE
Realm: *
Client: 10.1.1.0/24

6.3.6. Setup KeyIdentity QR Token

Starting with LinOTP 2.9 a new type of QR Token was implemented which can be used to secure transactions and supports offline authentication. The token is paired during the rollout procedure with the KeyIdentity APP (available for Android and iOS) at the smart phone of the user. For authentication the user scans a QR code generated e.g. by the KeyIdentity Authentication Provider (KAP). In case the mobile and the KAP are online the login is approved by the user via the APP and the login is successful. If either the KAP and/or the mobile are offline an OTP is displayed and to be entered in KAP to perform the login. This requires offline authentication configured for the user accordingly.

Besides the very convenient work flow for the user (no OTP must be entered, just scan the QR code and confirm action at the APP) the approval by the user is exactly for the displayed login (or transaction) and can only be used for this purpose. Traditional OTPs are universal - any can be used for any kind of login which makes them potentially vulnerable (e.g. an attacker getting hands on an event based token for a short moment can pregenerate a number of OTPs which can be used for any 2FA secured login procedure of this user+token).

The KeyIdentity QR Token is fully supported by the KeyIdentity Authentication Provider (KAP).

Note

The LinOTP server must provide a web server certificate accepted by the mobile the KeyIdentity Authenticator App is running at. So please make sure the certificate is signed by a trusted certificate authority.

6.3.6.1. Call back Pairing URL for Activation of KeyIdentity QR Tokens

This is the URL addressed by the APP to activate the offline token. The pairing can be performed e.g. via the Selfservice Portal.

The URL is transferred to the APP during the enrollment process. Different URLs can be configured for each realm.

  • Policy name: This is a unique name of the policy.
  • Scope: authentication
  • Realm: One realm, a comma separated list of realms or ‘*’
  • Action: qrtoken_pairing_callback_url= <URL> The URL should be something like https://<LINOTP>/validate/pair

6.3.6.2. Call back Challenge URL for Authentication with KeyIdentity QR Tokens

This is the URL addressed by the APP for the authentication procedure.

The URL is transferred to the APP during the authentication process. Different URLs can be configured for each realm.

  • Policy name: This is a unique name of the policy.
  • Scope: authentication
  • Realm: One realm, a comma separated list of realms or ‘*’
  • Action: qrtoken_challenge_callback_url= <URL> The URL should be something like https://<LINOTP>/validate/check_t

Tip

If no qrtoken_challenge_callback_url is configured or the mobile phone is offline a TAN or OTP is displayed by the APP and can be used for authentication. This allows the secure usage of QR token in offline situations.

6.3.6.3. Support for Offline QR Tokens

The KeyIdentity QR Token supports optional offline authentication. This feature can be selectively activated for certain realms and users.

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: Enter the name of the realm.
  • Action: support_offline=TYPE, while TYPE can be:
    • qr - KeyIdentity QR Token
    • u2f- FIDO U2F Token
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

6.3.7. Setup KeyIdentity Push Token

Starting with LinOTP 2.9.1 the Keyidentity Push Token was implemented which can be used to secure logins and transactions. The token is paired during the rollout procedure with the KeyIdentity APP (available for Android and iOS) at the smart phone of the user. For authentication the user initiates the login (e.g. with the user name and the password). The login procedure contacts the LinOTP server which in turn generates and sends a push messages to the user’s mobile. The user approves the action in the APP. The result is sent back to the LinOTP server. The LinOTP server checks the result and tells the login program whether the login is allowed or not. Besides the very convenient work flow for the user (no OTP must be entered, just confirm action via APP) the approval by the user is exactly for the displayed login (or transaction) and can only be used for this purpose. Traditional OTPs are universal - any can be used for any kind of login which makes them potentially vulnerable (e.g. an attacker getting hands on an event based token for a short moment can pregenerate a number of OTPs which can be used for any 2FA secured login procedure of this user+token).

The KeyIdentity Push Token is fully supported by the KeyIdentity Authentication Provider (KAP).

Note

The LinOTP server must provide a web server certificate accepted by the mobile the KeyIdentity Authenticator App is running at. So please make sure the certificate is signed by a trusted certificate authority.

Note

KeyIdentity GmbH provides the required infrastructure for the Push Token for their customers.

6.3.7.1. Call back Pairing URL for Activation of KeyIdentity Push Tokens

This is the URL addressed by the APP to pair the Push Token. The pairing can be performed e.g. via the Selfservice Portal.

The URL is transferred to the APP during the enrollment process. Different URLs can be configured for each realm.

  • Policy name: This is a unique name of the policy.
  • Scope: authentication
  • Realm: One realm, a comma separated list of realms or ‘*’
  • Action: pushtoken_pairing_callback_url= <URL> The URL should be something like https://<LINOTP>/validate/pair

6.3.7.2. Call back Challenge URL for Authentication with KeyIdentity Push Tokens

This is the URL addressed by the APP for the authentication procedure.

The URL is transferred to the APP during the enrollment process. Different URLs can be configured for each realm.

  • Policy name: This is a unique name of the policy.
  • Scope: authentication
  • Realm: One realm, a comma separated list of realms or ‘*’
  • Action: pushtoken_challenge_callback_url= <URL> The URL should be something like https://<LINOTP>/validate/check_t

6.3.8. URL for QR-TAN Tokens

The QR-TAN Token provides a half automatic mode, where the APP tries to send the TAN to a configured URL.

This URL is transferred to the APP during the enrollment process. Different URLs can be defined for reach realm.

To do so you can set up a policy like this:

  • Policy name: This is a unique name of the policy.
  • Scope: authentication
  • Realm: One realm, a comma separated list of realms or ‘*’
  • Action: qrtanurl= <URL> The URL should be something like https://yourserver/ocra/check_t

Tip

Please do not confuse the QR-TAN Token with the KeyIdentity QR Token as described above.

6.3.9. Policy to choose SMS Provider

Starting with LinOTP 2.9 more than one SMS Provider can be configured: SMS Provider for SMS OTP Tokens / Mobile TANs

Which one will be used to deliver the SMS can be configured by policies. If no policy exists or no existing policy applies the SMS Provider marked as “(Default)” will be used.

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Action: sms_provider=<NAME_OF_ONE_OF_THE_CONFIGURED_PROVIDERS>
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Realm: Enter the name of the realm.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

6.3.10. Automatic SMS sending

Using this policy you may define, that a new SMS is sent after the user has successfully authenticated with an SMS OTP. This way, the user does not need to do some additional step for triggering the sending of a new SMS. When you use the client parameter, you can define, that an automatic SMS will be triggered when the user logged in to the Terminal Server but not to the SSL VPN.

  • Policy name: This is the unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: Enter the name of the realm here.
  • Action: This field is comma separated. It should contain the keyword autosms. This keyword works as a boolean and takes no parameter.
  • User: This is a list of users or ‘*’ for all users, for whom this policy will be valid.
  • Client: This is a list of IP addresses or IP subnets.

6.3.11. SMS Text

Using this policy you may define the text content of the SMS. Usually the SMS only contains the OTP value. But you may change this per realm.

  • Policy name: This is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: Enter the name of the realm. These users will get a customized text.
  • Action: Use the format smstext= ”Your OTP <otp> for your token <serial>”. You may use text, that can be send via SMS. The place holders <otp> and <serial> will be replaced by the OTP value and the serial number of the token. You do not need to add the serial number!

6.3.12. Policy to choose E-mail Provider

Starting with LinOTP 2.9 more than one E-mail Provider can be configured: E-mail Provider for E-mail Token. Which one will be used to deliver the e-mail can be configured by policies. If no policy exists or no existing policy applies the E-mail Provider marked as “(Default)” will be used.

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Action: email_provider=<NAME_A_CONFIGURED_PROVIDERS>
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Realm: Enter the name of the realm.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

6.3.13. Email Subject

Using this policy you may customize the subject of the email. A default subject ist set in the email config, see E-mail Provider for E-mail Token

  • Policy name: This is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: One realm, a comma seperated list of realms or ‘*’. These users will get a customized subject.
  • Action: Use the format emailsubject= ”Your OTP for your token <serial>”.

The placeholders <otp> and <serial> will be replaced by the OTP value and the serial number of the token. Both <serial> and <otp> are optional!

6.3.14. Email Text

Using this policy you may define the text content of the email which is sent when a user authenticates via email token. Usually the email only contains the OTP value.

  • Policy name: This is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: One realm, a comma seperated list of realms or ‘*’. These users will get a customized text.
  • Action: Use the format emailtext= ”Your OTP <otp> for your token <serial>”.

The placeholders <otp> and <serial> will be replaced by the OTP value and the serial number of the token. You do not need to add the serial number!

6.3.15. Automatically Disable or Delete Token

Beginning with LinOTP 2.9.3 tokens can be either disabled or deleted depending on:

  • validity
  • number of successful logins
  • number of total login trials

All conditions can be configured per token via the Token View in https://LINOTP/manage or API.

The advantage of the new policies is that token which can not be used anymore due to one of the those conditions are cleaned up (deleted) automatically or do not count towards the license anymore (disabled).

6.3.15.1. Disable Token

  • Policy name: This is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: One realm, a comma seperated list of realms or ‘*’.
  • Action: disable_on_authentication_exceed.

6.3.15.2. Delete Token

  • Policy name: This is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Realm: One realm, a comma seperated list of realms or ‘*’.
  • Action: delete_on_authentication_exceed

Tip

Please mind - once a token is deleted it can not be restored without reimporting the seed file.