8.3. Authentication policies¶
The scope authentication gives you more detailed possibilities to authenticate the user or to define what happens during authentication.
Technically the authentication policies apply to the REST API Validate endpoints and are checked using Policy Module and Policy Decorators.
The following actions are available in the scope authentication:
8.3.1. otppin¶
type: string
This action defines how the fixed password part during authentication should be validated. Each token has its own OTP PIN, but you can choose how the authentication should be processed:
otppin=tokenpin
This is the default behaviour. The user needs to pass the OTP PIN concatenated with the OTP value.
otppin=userstore
The user needs to pass the user store password concatenated with the OTP value. It does not matter if the OTP PIN is set or not. If the user is located in an Active Directory the user needs to pass his domain password together with the OTP value.
Note
The domain password is checked with an LDAP bind right at the moment of authentication. So if the user is locked or the password was changed authentication will fail.
otppin=none
The user does not have to pass any fixed password. Authentication is only done via the OTP value.
8.3.2. passthru¶
type: str
If the user has no token assigned, he will be authenticated against the userstore or against the given RADIUS configuration. I.e. the user needs to provide the LDAP- or SQL-password or valid credentials for the RADIUS server.
Note
This is a good way to do a smooth enrollment. Users having a token enrolled will have to use the token, users not having a token, yet, will be able to authenticate with their domain password.
It is also a way to do smooth migrations from other OTP systems. The authentication request of users without a token is forwarded to the specified RADIUS server.
Note
The passthru policy overrides the authorization policy for tokentype. I.e. a user may authenticate due to the passthru policy (since he has no token) although a tokentype policy is active!
Warning
If the user has the right to delete his tokens in selfservice portal, the user could delete all his tokens and then authenticate with his static password again.
8.3.3. passthru_assign¶
type: str
This policy is only evaluated, if the policy passthru is set.
If the user is authenticated against a RADIUS server, then privacyIDEA
splits the sent password into PIN and OTP value and tries to find an unassigned token,
that is in the user’s realm by using the OTP value. If it can identify this token, it assigns this
token to the user and sets the sent PIN.
The policy is configured with a string value, that contains * the position of the PIN * the OTP length and * the number of OTP values tested for each unassigned token (optional, default=100).
Examples are
8:pinwould be an eight digit OTP value followed by the PINpin:6:10000would be the PIN followed by an 6 digit OTP value, 10.000 otp values would be checked for each token.
Note
This method can be used to automatically migrated tokens from an old system to privacyIDEA. The administrator needs to import all seeds of the old tokens and put the tokens in the user’s realm.
Warning
This can be very time consuming if the OTP values to check is set to high!
8.3.4. passOnNoToken¶
type: bool
If the user has no token assigned an authentication request for this user will always be true.
Warning
Only use this if you know exactly what you are doing.
8.3.5. passOnNoUser¶
type: bool
If the user does not exist, the authentication request is successful.
Warning
Only use this if you know exactly what you are doing.
8.3.6. smstext¶
type: string
This is the text that is sent via SMS to the user trying to authenticate with an SMS token. You can use the tags <otp> and <serial>.
Starting with version 2.20 you can use the tag {challenge}. This will add the challenge data that was passed in the first authentication request in the challenge parameter. This could contain banking transaction data.
Default: <otp>
8.3.7. smsautosend¶
type: bool
A new OTP value will be sent via SMS if the user authenticated successfully with his SMS token. Thus the user does not have to trigger a new SMS when he wants to login again.
8.3.8. emailtext¶
type: string
This is the text that is sent via Email to be used with Email Token. This text should contain the OTP value.
The text can contain the following tags, that will be filled:
- {serial} the serial number of the token.
- {user} the given name of the token owner.
- {givenname} the given name of the token owner.
- {surname} the surname of the token owner.
- {username} the loginname of the token owner.
- {userrealm} the realm of the token owner.
- {tokentype} the type of the token.
- {recipient_givenname} the given name of the recipient.
- {recipient_surname} the surname of the recipient.
- {time} the current server time in the format HH:MM:SS.
- {date} the current server date in the format YYYY-MM-DD
Starting with version 2.20 you can use the tag {challenge}. This will add the challenge data that was passed in the first authentication request in the challenge parameter. This could contain banking transaction data.
Default: <otp>
You can also provide the filename to an email template. The filename must be prefixed with
file: like file:/etc/privacyidea/emailtemplate.html. The template is
an HTML file.
Note
If a message text is supplied directly, the email is sent as plain text. If the email template is read from a file, a HTML-only email is sent instead.
8.3.9. emailsubject¶
type: string
This is the subject of the Email sent by the Email Token.
You can use the same tags as mentioned in emailtext.
Default: Your OTP
8.3.10. emailautosend¶
type: bool
If set, a new OTP Email will be sent, when successfully authenticated with an Email Token.
8.3.11. mangle¶
type: string
The mangle policy can mangle the authentication request data before they
are processed. I.e. the parameters user, pass and realm can be
modified prior to authentication.
This is useful if either information needs to be stripped or added to such a parameter. To accomplish that, the mangle policy can do a regular expression search and replace using the keyword user, pass (password) and realm.
A valid action could look like this:
action: mangle=user/.*(.{4})/user\\1/
This would modify a username like “userwithalongname” to “username”, since it would use the last four characters of the given username (“name”) and prepend the fixed string “user”.
This way you can add, remove or modify the contents of the three parameters. For more information on the regular expressions see [1].
Note
You must escape the backslash as \ to refer to the found substrings.
Example: A policy to remove whitespace characters from the realm name would look like this:
action: mangle=realm/\\s//
Example: If you want to authenticate the user only by the OTP value, no matter what OTP PIN he enters, a policy might look like this:
action: mangle=pass/.*(.{6})/\\1/
Example: If you want to strip a string from the front of a username, for example to have “admin_username” resolve to just “username”, it would look like this:
action: mangle=user/admin_(.*)/\\1/
8.3.12. challenge_response¶
type: string
This is a list of token types for which challenge response can be used during authentication. The list is separated by whitespaces like “hotp totp”.
Note
The TiQR token does not need this setting, since it always works with challenge response.
8.3.13. u2f_facets¶
type: string
This is a white space separated list of domain names, that are trusted to also use a U2F device that was registered with privacyIDEA.
You need to specify a list of FQDNs without the https scheme like:
“host1.example.com host2.exmaple.com firewall.example.com”
For more information on configuring U2F see U2F Token Config.
| [1] | https://docs.python.org/2/library/re.html |
8.3.14. reset_all_user_tokens¶
type: bool
If a user authenticates successfully all failcounter of all of his tokens will be reset. This can be important, if using empty PINs or otppin=None.
8.3.15. auth_cache¶
type: string
The Authentication Cache caches the credentials of a successful authentication and allows to use the same credentials - also with an OTP value - for the specified amount of time.
The time to cache the credentials can be specified like “4h”, “5m”, “2d” (hours, minutes days) or “4h/5m”. The notation 4h/5m means, that credentials are cached for 4 hours, but only may be used again, if every 5 minutes the authentication occurs. If the authentication with the same credentials would not occur within 5 minutes, the credentials can not be used anymore.
In future implementations the caching of the credentials could also be dependent on the clients IP address and the user agent.
Note
The AuthCache only works for user authentication, not for authentication with serials.
8.3.16. push_text_on_mobile¶
type: string
This is the text that should be displayed on the push notification during the login process with a Push Token. You can choose different texts for different users or IP addresses. This way you could customize push notifications for different applications.
8.3.17. push_title_on_mobile¶
type: string
This is the title of the push notification that is displayed on the user’s smartphone during the login process with a Push Token.
8.3.18. push_wait¶
type: int
This can be set to a number of seconds. If this is set, the authentication
with a push token is only performed via one request to /validate/check.
The HTTP request to /validate/check will wait up to this number of
seconds and check, if the push challenge was confirmed by the user.
This way push tokens can be used with any non-push-capable applications.
Sensible numbers might be 10 or 20 seconds.
Note
This behaviour can interfere with other tokentypes. Even if
the user also has a normal HOTP token, the /validate/check request
will only return after this number of seconds.
Warning
Using simple webserver setups like Apache WSGI this actually can block all available worker threads, which will cause privacyIDEA to become unresponsive if the number of open PUSH challenges exceeds the number of available worker threads!
