Authentication Policies

1.6.4. Authentication Policies#

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

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 supported 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).

      So the authentication will be successful with:

      • PINOTP

      • OTP (if no PIN has been set for the token)

    • 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).

      So the authentication will be successful with:

      • USERPASSWORDOTP

    • 2 or only_otp: The user must not enter any additional OTP PIN and will be authenticated only with the OTP value (OTP).

      So the authentication will be successful with:

      • OTP

    • 3 or ignore_pin: The user may or may not enter a PIN. Any characters additionally to the OTP will be ignored for authentication and only the OTP value will be processed by LinOTP.

      So the authentication will be successful with:

      • PINOTP

      • OTP

      • SOMETHINGOTP

  • 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. Please see Clients in policies.

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.

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.

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.

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: A single 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.

Scope: authentication
Action: challenge_response=HMAC TOTP PW,
Realm: *

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. By default, every authentication covered by the conditions of the policy (e.g. name, realm, client etc.) is forwarded. Especially in migration scenarios it might be useful to combine this policy with an additional policy - Forward Request to Remote Server for User without Token only. This will limit the forwarding to users without token only.

  • 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

Forward Request to Remote Server for User without Token only#

This policy can only be used in conjunction with a configured remote server (Forward Request to Remote Server). It changes the condition: the forwarding applies only for users without assigned tokens. This is especially useful for migration scenarios where LinOTP is configured as general authentication backend. Users already having enrolled a token in LinOTP will be authenticated by LinOTP itself while the requests for other users are forwarded to the solution to be replaced. In this situation LinOTP acts as authentication relay.

Set up the policy like this:

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

  • Scope: authentication

  • Realm: A single realm, a comma-separated list of realms or ‘*’

  • Action: forward_on_no_token=1

  • 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.

Setup LinOTP 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 LinOTP Authenticator 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 LinOTP Authentication Provider (LAP). In case the mobile and the LAP are online the login is approved by the user via the APP and the login is successful. If either the LAP and/or the mobile are offline an OTP is displayed and to be entered in LAP 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 LinOTP QR Token is fully supported by the LinOTP Authentication Provider (LAP).

Note

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

Callback Pairing URL for Activation of LinOTP 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: A single realm, a comma-separated list of realms or ‘*’

  • Action: qrtoken_pairing_callback_url= <URL> The URL should be something like https://<LINOTP>/validate/pair

Callback Challenge URL for Authentication with LinOTP 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: A single 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.

Support for Offline QR Tokens#

The LinOTP QR Token supports optional offline authentication. If this action is enabled, and the service requests the parameter “use_offline” at /validate/check_status, the response includes the token public key if authentication was successful. This allows the service (e.g. the LinOTP Authentication Provider) to generate their own challenges if the service or LinOTP is offline.

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 - LinOTP QR token

    • u2f - FIDO U2F token

    • forward - Forwarding token pointing to qr or u2f tokens.

  • 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.

LinOTP Push Token Policies#

This type of token offers a very convenient way to secure logins and transactions. General information about the push token and the required setup of the push token provider can be found here: Push Provider for LinOTP Push Token

Callback Pairing URL for Activation of LinOTP PushTokens#

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: A single realm, a comma-separated list of realms or ‘*’

  • Action: pushtoken_pairing_callback_url= <URL>

    The URL should be something like https://<FQDN_Challenge-Service>/

Callback Challenge URL for Authentication with LinOTP PushTokens#

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: A single realm, a comma-separated list of realms or ‘*’

  • Action: pushtoken_challenge_callback_url= <URL>

    The URL should be something like https://<FQDN_Challenge-Service>/

URL for OCRA2 Tokens#

The OCRA2 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: A single realm, a comma-separated list of realms or ‘*’

  • Action: qrtanurl= <URL> The URL should be something like https://yourserver/validate/check_t

Tip

Please do not confuse the OCRA2 Token with the LinOTP QR Token as described above.

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_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.

SMS Provider Failover#

Starting with LinOTP 2.10.4 failover SMS Providers can be configured.

Please make sure to use exactly the SMS Provider names as configured. If the first server can not be reached, LinOTP will stay with the failover server for an increasing time before retrying the first server again.

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

  • Scope: You need to set this to authentication.

  • Action contains a list of SMS Providers separated by a blank: sms_provider=PROVIDER_A PROVIDER_B_USED_AS_FAILOVER

  • 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.

Example:

Scope: authentication
Action: sms_provider=providerA providerB providerC
Realm: *
User: *
Client: *
Time: *

Tip

It is possible to mix different kind of SMS Providers, for example a SMTP Provider could be used as failover for a HTTP Provider.

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.

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>

Tip

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!

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

Enforce SMS Text#

By default a &data= parameter in the authentication API call (like from RADIUS) overrules any configured smstext policy. Starting with LinOTP 2.10.1 the new policy action enforce_smstext changes this behaviour. If the option is set the data parameter will be ignored and LinOTP will use applicable smstext policies.

Tip

The enforce_smstext action is only reasonable in conjunction with at least one smstext action.

  • 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 enforce_smstext

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

SMS Dynamic Mobile Number#

Starting with LinOTP 2.10 the user’s mobile number can be retrieved from the user storage every time a SMS is sent. The number stored in the token information remains as originally configured.

Please mind: an attacker with access to the user storage can change the number and could compromise the second factor if this feature is activated.

  • 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.

  • Realm: A single realm, a comma-separated list of realms or ‘*’. Dynamic phone number handling is applied to users of the given realms

  • Action: sms_dynamic_mobile_number

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

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.

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: A single realm, a comma-separated list of realms or ‘*’. These users will get the customized subject.

  • Action: Use the format emailsubject=Your OTP for your token <serial>

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

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!

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: A single realm, a comma-separated list of realms or ‘*’. These users will get the customized text.

  • Action: Use the format emailtext=Your OTP <otp> for your token <serial>

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

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!

Email dynamic address#

This policy is used to dynamically adjust the mail address of the user in his e-mail token in case of changes in the UserIdResolver. The user’s email address can then be maintained in the Windows active directory, for example. If the address changes, the token doesn’t need to be rolled out again.

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

  • Scope: You need to set this to authentication.

  • Realm: A single realm, a comma-separated list of realms or ‘*’. Dynamic address handling is applied to users of the given realms

  • Action: dynamic_email_address

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).

Disable Token#

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

  • Scope: You need to set this to authentication.

  • Realm: A single realm, a comma-separated list of realms or ‘*’.

  • Action: disable_on_authentication_exceed.

Delete Token#

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

  • Scope: You need to set this to authentication.

  • Realm: A single realm, a comma-separated 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.