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).
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.
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. 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
6.3.6. 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: One 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.
6.3.7. 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.7.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.7.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.7.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.8. KeyIdentity Push Token Policies¶
This type of token offers a very convenient way to secure logins and transactions. Genearal information about the push token and the required setup of the push token provider can be found here: Push Provider for KeyIdentity Push Token
6.3.8.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://<FQDN_Challenge-Service>/
6.3.8.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://<FQDN_Challenge-Service>/
6.3.9. 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.10. 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.
6.3.11. 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.
6.3.12. 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.13. 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.
6.3.14. 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.
6.3.15. 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.
Action: sms_dynamic_mobile_number
Client: This is a list of IP addresses or subnets this policy is valid for.
6.3.16. 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.17. 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>
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!
6.3.18. 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>
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!
6.3.19. 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 mail address can then be maintained in the Windows active directory, for example. If the address is changed, the token is not rolled out again.
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: dynamic_email_address
6.3.20. 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.20.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.20.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.
6.3.21. Voice Token Policies¶
6.3.21.1. Choose Voice Provider¶
Multiple Voice Provider can be configured. If no policy exists or no existing policy applies the Voice 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: voice_provider=<NAME_OF_A_CONFIGURED_PROVIDER>
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.
To configure the Voice Provider, see Voice Provider
6.3.21.2. Voice Message content¶
This optional policy defines the text content of the voice message when a user authenticates via voice token. By default the message 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 voice_message=Your OTP is {otp}.
Client: This is a list of IP addresses or subnets this policy is valid for.
The placeholders {otp} will be replaced by the OTP value. <pause> inserts a delay of one second.
6.3.21.3. Voice Language¶
By default English is used to read the message to the user. Different languages can be configured according to the provider’s prospects.
Tip
Configuration values for Twilio can be found here: Twilio
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 voice_language=LANGUAGE.
Client: This is a list of IP addresses or subnets this policy is valid for.
Example
Read the message in German (Twilio):
voice_language=de-DE
6.3.21.4. Voice Dynamic Mobile Number¶
Starting with LinOTP 2.10 the user’s mobile number can be retrieved from the user storage every time a voice message is sent. The number stored in the token information remains as originally configured.
Tip
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.
Action: voice_dynamic_mobile_number
Client: This is a list of IP addresses or subnets this policy is valid for.