8.4. Authorization policies¶
The scope authorization provides means of granting permission, independently of the actual authentication process.
Authorization policies can evaluate a wide range of parameters, such as the user, the token type, the IP address of the request or even custom request parameters.
The following actions are available in the scope authorization:
8.4.1. authorized¶
type: string
allowed values: grant_access, deny_access
This is the basic authorization, that either grants the user access or denies access via the /validate
endpoints (see Validate endpoints).
The default behavior is to grant access, if and after the user has authenticated successfully.
Using authorized=deny_access specific authentication requests can be denied, even if the user has provided
the correct credentials.
In combination with different IP addresses and policy priorities the administrator can generically deny_access with the lowest policy priority and grant_access for specific requests e.g. originating from specific IP addresses to certain users by defining higher policy priorities.
Note
Since authorized is checked as a postpolicy the OTP value used during an authentication attempt will be invalidated even if the authorized policy denies the access.
Note
The actual “success” of the authentication can be changed to “failed” by this postpolicy.
Meaning pre-event handlers (Pre and Post Handling) would still
see the request as successful before it would be changed by this policy and
match the event handler condition result value == True.
8.4.2. tokentype¶
type: string
Users will only be authorized with this very tokentype. The string can hold a space separated list of case sensitive tokentypes. It should look like:
hotp totp spass
This is checked after the authentication request, so a valid OTP value will be used up, even if the user was not authorized with this request.
Note
Combining this with the client IP you can use this to allow remote access to sensitive areas only with one special token type while allowing access to less sensitive areas with other token types.
8.4.3. application_tokentype¶
type: bool
If this policy is set, an application may add a parameter type as
tokentype in the authentication request like validate/check
or validate/triggerchallenge.
Then the application can determine via this parameter, which tokens of a user should be checked.
E.g. when using this in triggerchallenge, an application could assure that only SMS tokens are used for authentication.
8.4.4. serial¶
type: string
Users will only be authorized with the serial number. The string can hold a regular expression as serial number.
This is checked after the authentication request, so a valid OTP value will be used up, even if the user was not authorized with this request.
Note
Combining this with the client IP you can use this to allow remote access to sensitive areas only with hardware tokens like the YubiKey, while allowing access to less secure areas also with a Google Authenticator.
8.4.5. tokeninfo¶
type: string
Users will only be authorized if the tokeninfo field of the token matches this regular expression.
This is checked after the authentication request, so a valid OTP value will be used up, even if the user was not authorized with this request.
A valid action could look like:
action = key/regexp/
Example:
action = last_auth/^2018.*/
This would mean the tokeninfo field needs to start with “2018”.
8.4.6. setrealm¶
type: string
This policy is checked before the user authenticates. The realm of the user matching this policy will be set to the realm in this action.
This policy is only applied to POST /validate/check and POST /validate/radiuscheck.
Priorities are not evaluated for setrealm: if the matching policies name more than one realm, the request fails
with “Conflicting policies exist”. If an authentication set_realm policy matched, setrealm is not
evaluated at all.
Note, that this policy is evaluated, after the parameters of the request have been processed. This means,
that the parameters like user and realm would already have to result in a valid user object. And thereafter this
policy is applied.
However, this means, that it is also possible to use the original user object in the policy conditions.
This policy can be used to move users from one original realm to a different realm, e.g. for authorization reasons. For this policy, the user has to be available in both realms!
Note
Please check if you might actually want to use the policy set_realm from the authentication scope instead. That is applied before user resolving and thus it is not necessary to have the user in both realms.
Note
The mangle policy is still executed after this policy and can change the realm again.
For in depth information about user and realm mapping read Realms.
8.4.7. no_detail_on_success¶
Deprecated since version 3.12: Please use the ResponseMangler Handler Module to delete the detail section.
type: bool
Usually an authentication response returns additional information like the serial number of the token that was used to authenticate or the reason why the authentication request failed.
If this action is set and the user authenticated successfully this additional information will not be returned.
8.4.8. no_detail_on_fail¶
Deprecated since version 3.12: This policy breaks challenge-response authentication.
type: bool
Usually an authentication response returns additional information like the serial number of the token that was used to authenticate or the reason why the authentication request failed.
If this action is set and the user fails to authenticate this additional information will not be returned.
Note
This policy does not mask an error message configured for
Conditional Access. Such a message exists only because an
administrator wrote it on a stage or enabled
show_default_ca_error_message, so it is the one thing left in
the detail object of a rejected request. A conditional access rejection
with no message of its own carries no detail at all once this policy strips
it. See Interaction with the masking policies.
8.4.9. api_key_required¶
type: bool
Deprecated since version 3.14: This policy and its Authorization JWT (minted by pi-manage api
createtoken) are deprecated and will be removed in a future release. The
API clients and “remember this device” feature (X-API-Key) is intended to replace them — API
clients are stored, individually revocable and rotatable — but it does not
yet cover this /validate gating use case.
This policy is checked before the user is validated.
You can create an API key that needs to be passed to use the validate API. If an API key is required, but no key is passed, the authentication request will not be processed. This is used to avoid denial of service attacks by a rogue user sending arbitrary requests, which could result in the token of a user being locked.
You can also define a policy with certain IP addresses without issuing API keys. This would result in “blocking” those IP addresses from using the validate endpoint.
You can issue API keys like this:
pi-manage api createtoken -r validate -u <name>
The API key (Authorization token) which is generated is valid for 365 days by
default; -d sets another number of days. See API Keys.
The authorization token has to be used as described in Authentication endpoints.
8.4.10. auth_max_success¶
type: string
Here you can specify how many successful authentication requests a user is allowed to perform during a given time. If this value is exceeded, the authentication attempt is canceled.
Specify the value like 2/5m meaning 2 successful authentication requests
per 5 minutes. If during the last 5 minutes 2 successful authentications were
performed the authentication request is refused, and the OTP value stays valid.
Allowed time specifiers are s (second), m (minute) and h (hour).
This policy applies to /auth and /validate/check and holds for both admins and users. The policy is
evaluated before checking the password or OTP value.
Note
This policy depends on reading the audit log. If you use a non-readable audit log like Logger Audit this policy will not work.
In case a local admin and a user in the default realm exist with the same username, we can not distinguish them before the authentication if no realm is passed. The policy is first checked for local admins; hence, if the admin reaches the time limit of successful authentications, the user will not be able to authenticate anymore. This can be avoided by explicitly passing the user’s realm. Anyway, local admins are not affected by the number of successful user authentications.
8.4.11. auth_max_fail¶
type: string
Here you can specify how many failed authentication requests a user is allowed to perform during a given time.
If this value is exceeded, authentication is not possible anymore. The user will have to wait.
If this policy is not defined, the normal behavior of the failcounter applies. (see FailCount)
Specify the value like 2/1m meaning 2 failed authentication requests per minute. If during the last minute 2
failed authentications were performed the authentication request is refused, and the OTP value stays valid.
Allowed time specifiers are s (second), m (minute) and h (hour).
This policy applies to /auth and /validate/check and holds for both admins and users. The policy is
evaluated before checking the password or OTP value.
Note
This policy depends on reading the audit log. If you use a non-readable audit log like Logger Audit this policy will not work.
In case a local admin and a user in the default realm exist with the same username, we can not distinguish their failed authentications. Hence, if the admin reaches the time limit of failed authentications, the user will not be able to authenticate anymore, and vice versa.
8.4.12. last_auth¶
type: string
You can define if an authentication should fail, if the token was not successfully used for a certain time. A token without a recorded successful authentication (e.g. not used since its enrollment) is not refused; its first successful authentication starts the period.
Specify a value like 12h, 123d or 2y to disallow authentication,
if the token was not successfully used for 12 hours, 123 days or 2 years.
The date of the last successful authentication is stored in the tokeninfo
field last_auth with its UTC offset (in the server’s local time; in UTC for
passkey authentications).
8.4.13. add_user_in_response¶
type: bool
In case of a successful authentication additional user information is added
to the response. A dictionary containing user information is added in
detail->user.
Note
This policy only fires on a successful authentication. There is
no equivalent of the removed ReturnSamlAttributesOnFail option that
returned user attributes on a failed authentication; relying parties that
need user data after a failed authentication must look the user up
themselves.
8.4.14. add_resolver_in_response¶
type: bool
In case of a successful authentication the resolver and realm of the user are added
to the response. The names are added in
detail->user-resolver and detail->user-realm.
8.4.15. webauthn_authenticator_selection_list¶
type: string
This action configures a whitelist of authenticator models which may be authorized. It is a space-separated list of AAGUIDs. An AAGUID is a hexadecimal string (usually grouped using dashes, although these are optional) identifying one particular model of authenticator. To limit authentication to a few known-good authenticator models, specify the AAGUIDs for each model of authenticator that is acceptable. The AAGUID recorded at the enrollment of the token is checked when the token authenticates. If multiple policies with this action apply, the set of acceptable authenticators will be the union of all authenticators allowed by the various policies.
If this action is not configured, all authenticators will be deemed acceptable, unless limited through some other action.
Note
If you configure this, you will likely also want to configure webauthn_authenticator_selection_list
8.4.16. webauthn_req¶
type: string
This action allows filtering of WebAuthn tokens by the fields of the attestation certificate.
The action can be specified like this:
webauthn_req=subject/.*Yubico.*/
The keyword can be “subject”, “issuer” or “serial”, followed by a regular expression. When a WebAuthn token authenticates, the attestation certificate data recorded at its enrollment is checked, and the token is only accepted if the field matches. A token enrolled without attestation certificate data is refused while such a policy applies. If several values apply (from one or several policies), every one of them must match.
Note
If you configure this, you will likely also want to configure webauthn_req
8.4.17. require_auth_for_resolver_details¶
type: bool
Usually, /healthz/resolversz will include in its response the name and status
of each resolver individually, as well as the total status of all resolvers;
without requiring any form of authentication.
If this policy is set, admin credentials must be provided to receive the individual resolver details. The total status will be included either way.
Note
In order to limit the amount of information exposed to third parties, it is recommended to activate this policy.
