.. _policy-authentication: Authentication Policies ------------------------ Some authentication policies are also making use of the client field. This is described in the policy. .. _policy-authentication-pin: 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** = |. is suppported starting with LinOTP 2.9. **** and **** 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 :ref:`users_in_policies`. * Client: This is a list of IP addresses or IP subnets. Please see :ref:`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 :ref:`policy_autoassignment` 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 :ref:`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 :ref:`users_in_policies`. * Client: This is a list of IP addresses or subnets this policy is valid for. .. _cr_policy: 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=** 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 :ref:`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. .. _policy_forward_to_remote_server: 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 - :ref:`policy_forward_on_no_token`. 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 :ref:`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:** .. code:: Scope: authentication Action: forward_server=https://remote_linotp/validate/check Realm: financials | **Example remote RADIUS server:** .. code:: Scope: authentication Action: forward_server=radius://radius_server:1812/?secret=kjD28fSER9cW#SS1VlsCCE$#SAGH#$RRVE Realm: * Client: 10.1.1.0/24 .. _policy_forward_on_no_token: Forward Request to Remote Server for User without Token only ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This policy can only be used in conjunction with a configured remote server (:ref:`policy_forward_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 :ref:`users_in_policies`. * Client: This is a list of IP addresses or subnets this policy is valid for. .. _policy_ki_qr_offline_token: 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. 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=** The URL should be something like ``https:///validate/pair`` 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=** The URL should be something like ``https:///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 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 :ref:`users_in_policies`. * Client: This is a list of IP addresses or subnets this policy is valid for. .. _policy_ki_push_token: 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: :ref:`pushprovider` 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=** The URL should be something like ``https:///`` 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=** The URL should be something like ``https:///`` 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=** 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. .. _policy_sms_provider: Choose SMS Provider ~~~~~~~~~~~~~~~~~~~~~~ Starting with LinOTP 2.9 more than one SMS Provider can be configured: :ref:`smsprovider` 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 :ref:`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. .. _policy_sms_failover: 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 :ref:`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:** .. code:: 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 for your token * .. tip:: You may use text, that can be send via SMS. The place holders and 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. .. _dynamic_mobile_number: 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. .. _policy_email_provider: Choose E-mail Provider ~~~~~~~~~~~~~~~~~~~~~~~~~ Starting with LinOTP 2.9 more than one E-mail Provider can be configured: :ref:`emailprovider`. 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 :ref:`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. .. _policy_auth_email_subject: Email Subject ~~~~~~~~~~~~~ Using this policy you may customize the subject of the email. A default subject ist set in the email config, see :doc:`/part-management/emailprovider` * 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 * * Client: This is a list of IP addresses or subnets this policy is valid for. The placeholders and will be replaced by the OTP value and the serial number of the token. Both and 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: One realm, a comma seperated list of realms or '*'. These users will get a customized text. * Action: Use the format **emailtext**\=\ *Your OTP for your token * * Client: This is a list of IP addresses or subnets this policy is valid for. The placeholders and 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 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 .. 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: One realm, a comma seperated 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: 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. .. _policies_voice: Voice Token Policies ~~~~~~~~~~~~~~~~~~~~~ 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**\=\ ** * User: This is a comma separated list of usernames or resolver names. Please see :ref:`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 :ref:`voiceprovider` .. _voice_message: 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. inserts a delay of one second. .. _voice_lang: 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): .. code:: voice_language=de-DE .. _dynamic_mobile_number_voice: 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.