16.2.1.1. API Policies

16.2.1.1.1. Pre Policies

These are the policy decorators as PRE conditions for the API calls. I.e. these conditions are executed before the wrapped API call. This module uses the policy base functions from privacyidea.lib.policy but also components from flask like g.

Wrapping the functions in a decorator class enables easy modular testing.

The functions of this module are tested in tests/test_api_lib_policy.py

privacyidea.api.lib.prepolicy.api_key_required(request=None, action=None)

This is a decorator for check_user_pass and check_serial_pass. It checks, if a policy scope=auth, action=apikeyrequired is set. If so, the validate request will only be performed, if a JWT token is passed with role=validate.

privacyidea.api.lib.prepolicy.auditlog_age(request=None, action=None)

This pre condition checks for the policy auditlog_age and set the “timelimit” parameter of the audit search API.

Check ACTION.AUDIT_AGE

The decorator can wrap GET /audit/

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

Always true. Modified the parameter request

privacyidea.api.lib.prepolicy.auth_timelimit(request, action)

This decorator retrieves the auth timelimit from the policies and adds it to the request data. The auth timelimit is used to limit the time a user has to complete the authentication process.

Parameters:

• request – The request object

• action – The action parameter is not used in this decorator

Returns:

True

privacyidea.api.lib.prepolicy.check_admin_tokenlist(request=None, action='tokenlist')

Depending on the policy scope=admin, action=tokenlist, the allowed_realms parameter is set to define, the token of which realms and administrator is allowed to see.

Sets the allowed_realms None: means the admin has no restrictions []: the admin can not see any realms [“realm1”, “realm2”…]: the admin can see these realms

Parameters:

• request

• action – The action to be checked (tokenlist or container_list)

Returns:

privacyidea.api.lib.prepolicy.check_anonymous_user(request=None, action=None)

This decorator function takes the request and verifies the given action for the SCOPE USER without an authenticated user but the user from the parameters.

This is used with password_reset

Parameters:

• request

• action

Returns:

True otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_application_tokentype(request=None, action=None)

This pre policy checks if the request is allowed to specify the tokentype. If the policy is not set, a possibly set parameter “type” is removed from the request.

Check ACTION.APPLICATION_TOKENTYPE

This decorator should wrap

/validate/check, /validate/samlcheck and /validate/triggerchallenge.

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

Always true. Modified the parameter request

privacyidea.api.lib.prepolicy.check_base_action(request=None, action=None, anonymous=False)

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER.

Parameters:

• request

• action

• anonymous – If set to True, the user data is taken from the request parameters.

Returns:

True otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_client_container_action(request=None, action=None)

This decorator function takes the request and verifies the given action for the SCOPE CONTAINER. This decorator is used for api calls that perform actions on container requested from a client.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

True if action is allowed, otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_client_container_disabled_action(request=None, action=None)

This decorator function takes the request and verifies the given action for the SCOPE CONTAINER. This decorator is used for api calls that perform actions on container requested from a client. It verifies policies that explicitly disable an action.

Example for the action ‘disable_client_container_unregister’: If a policy contains this action, the client is not allowed to unregister the container. This function searches for these policies and raises a PolicyError. If no policy is found defining this action, the client is allowed to unregister containers and hence this function returns True meaning the client is allowed to unregister the container.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

Raises an Exception if the action is enabled, True otherwise

privacyidea.api.lib.prepolicy.check_container_action(request: Request = None, action: str = None)

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER. This decorator is used for api calls that perform actions on container.

If a container_serial is passed in the request and the logged-in user is an admin, the user attributes (username, realm, resolver) are determined from the container. Otherwise, they are determined from the request parameters. If no user attributes are available, they are set to empty strings “”. Therefore, only policies that do not specify the respective parameter in the conditions are matched. Only for the action ‘assign’ the user attributes are set to None if they cannot be determined from the container. Therefore, all policies are matched regardless of the user condition. This allows helpdesk admins to assign their users to containers without any owner. Note that the container realms are still considered.

For admins additionally the container realms are determined and passed as additional_realms to the policy match. That means all policies either matching the user attribute triplet or at least one out of the container realms are considered.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

True if the action is allowed, otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_container_register_rollover(request=None, action=None)

Checks if the user is allowed to register or rollover the container. Checks for the container_rollover action if the parameter ‘rollover’ is set in the request to True. Checks for the container_register action otherwise.

Parameters:

request – The request object

Returns:

True if the action is allowed, otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_custom_user_attributes(request=None, action=None)

This pre condition checks for the policies delete_custom_user_attributes and set_custom_user_attributes, if the user or admin is allowed to set or deleted the requested attribute.

It decorates POST /user/attribute and DELETE /user/attribute/…

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action – An optional action, (would be set/delete)

Returns:

Raises a PolicyError, if the wrong attribute is given.

privacyidea.api.lib.prepolicy.check_external(request=None, action='init')

This decorator is a hook to an external check function, that is called before the token/init or token/assign API.

Parameters:

• request (flask Request object) – The REST request

• action (basestring) – This is either “init” or “assign”

Returns:

either True or an Exception is raised

privacyidea.api.lib.prepolicy.check_max_token_realm(request=None, action=None)

Pre Policy This checks the maximum token per realm. Check ACTION.MAXTOKENREALM

This decorator can wrap:

/token/init (with a realm and user) /token/assign /token/tokenrealms

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

True otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_max_token_user(request=None, action=None)

Pre Policy This checks the maximum token per user policy. Check ACTION.MAXTOKENUSER Check ACTION.MAXACTIVETOKENUSER

This decorator can wrap:

/token/init (with a realm and user) /token/assign

Parameters:

• request

• action

Returns:

True otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_otp_pin(request=None, action=None)

This policy function checks if the OTP PIN that is about to be set follows the OTP PIN policies ACTION.OTPPINMAXLEN, ACTION.OTPPINMINLEN and ACTION.OTPPINCONTENTS and token-type-specific PIN policy actions in the SCOPE.USER or SCOPE.ADMIN. It is used to decorate the API functions.

The pin is investigated in the params as “otppin” or “pin”

In case the given OTP PIN does not match the requirements an exception is raised.

privacyidea.api.lib.prepolicy.check_token_action(request: Request = None, action: str = None)

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER. This decorator is used for api calls that perform actions on a single token or a list of tokens in the request. The action is verified for each token in the list. In case of a list of tokens it does not throw an exception if the action is not allowed for a token, but removes the token from the list and writes it to the log. Additionally, a list of the not authorized serials is added to the request with the key ‘not_authorized_serials’.

If a serial is passed in the request and the logged-in user is an admin, the user attributes (username, realm, resolver) are determined from the token. Otherwise, they are determined from the request parameters. If no user attributes are available, they are set to empty strings “”. Therefore, only policies that do not specify the respective parameter in the conditions are matched. Only for the action ‘assign’ the user attributes are set to None if they cannot be determined from the token. Therefore, all policies are matched regardless of the user condition. This allows helpdesk admins to assign their users to tokens without any owner. Note that the token realms are still considered.

Additionally, for admins, the token realms are determined and passed as additional_realms to the policy match. That means all policies either matching the user attribute triplet or at least one out of the token realms are considered.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

True otherwise raises an Exception

privacyidea.api.lib.prepolicy.check_token_init(request=None, action=None)

This decorator function takes the request and verifies if the requested tokentype is allowed to be enrolled in the SCOPE ADMIN or the SCOPE USER.

Parameters:

• request

• action

Returns:

True or an Exception is raised

privacyidea.api.lib.prepolicy.check_token_list_action(request: Request = None, action: str = None)

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER. It expects a serial list of tokens in the request. The action is verified for each token in the list. It does not throw an exception if the action is not allowed for a token, but removes the token from the list and writes it to the log. Additionally, a list of the not authorized serials is added to the request with the key ‘not_authorized_serials’.

Additionally, for admins, the token realms are determined and passed as additional_realms to the policy match. That means all policies either matching the user attribute triplet or at least one out of the token realms are considered.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

True

privacyidea.api.lib.prepolicy.check_token_upload(request=None, action=None)

This decorator function takes the request and verifies the given action for scope ADMIN

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.check_user_params(request=None, action=None)

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER. This decorator verifies if the logged-in user is allowed to set the passed user attributes. With the role USER, the user is only allowed to set its own attributes. For the role ADMIN, policy matching is done with the user attributes from the parameters in the request.

Parameters:

• request – The request object

• action – The action to check if the user is allowed to perform it

Returns:

True if action is allowed, otherwise raises an Exception

privacyidea.api.lib.prepolicy.container_registration_config(request, action=None)

This decorator gets the configuration for the container registration from the policies.

Parameters:

• request – The request object

• action – The action parameter is not used in this decorator

Returns:

True on success, otherwise raises a PolicyError

privacyidea.api.lib.prepolicy.disabled_token_types(request, action)

This decorator retrieves the disabled token types from the policies and adds them to the request data, to disable them for the authentication in check_token_list.

Parameters:

• request – The request object

• action – The action parameter is not used in this decorator

Returns:

True

privacyidea.api.lib.prepolicy.encrypt_pin(request=None, action=None)

This policy function is to be used as a decorator for several API functions. E.g. token/assign, token/setpin, token/init If the policy is set to define the PIN to be encrypted, the request.all_data is modified like this: encryptpin = True

It uses the policy SCOPE.ENROLL, ACTION.ENCRYPTPIN

privacyidea.api.lib.prepolicy.enroll_pin(request=None, action=None)

This policy function is used as decorator for init token. It checks, if the user or the admin is allowed to set a token PIN during enrollment. If not, it deleted the PIN from the request.

privacyidea.api.lib.prepolicy.fido2_auth(request, action)

Add policy values for FIDO2 tokens to the request. The following policy values are added: - WEBAUTHNACTION.ALLOWED_TRANSPORTS - ACTION.CHALLENGETEXT for WebAuthn and Passkey token - PasskeyAction.EnableTriggerByPIN

privacyidea.api.lib.prepolicy.fido2_enroll(request, action)

This is a token specific wrapper for FIDO2 token and the endpoint /token/init.

This will enrich the initialization request for WebAuthn tokens with the necessary configuration information from policy actions with scope=SCOPE.ENROLL. The request will be augmented with a name and id for the relying party, as specified by the with actions WEBAUTHNACTION.RELYING_PARTY_NAME and WEBAUTHNACTION.RELYING_PARTY_ID, respectively, authenticator attachment preference, public key credential algorithm preferences, authenticator attestation requirement level, authenticator attestation requirement form, allowed AAGUIDs, and the text to display to the user when asking to confirm the challenge on the token, as specified by the actions WEBAUTHNACTION.AUTHENTICATOR_ATTACHMENT, WEBAUTHNACTION.PUBLIC_KEY_CREDENTIAL_ALGORITHM_PREFERENCE, WEBAUTHNACTION.AUTHENTICATOR_ATTESTATION_LEVEL, WEBAUTHNACTION.AUTHENTICATOR_ATTESTATION_FORM, WEBAUTHNACTION.AVOID_DOUBLE_REGISTRATION, WEBAUTHNACTION.AUTHENTICATOR_SELECTION_LIST, and ACTION.CHALLENGETEXT, respectively.

Setting WEBAUTHNACTION.RELYING_PARTY_NAME and WEBAUTHNACTION.RELYING_PARTY_ID is mandatory, and if either of these is not set, we bail out.

Parameters:

• request

• action

Returns:

Return type:

privacyidea.api.lib.prepolicy.force_server_generate_key(request: Request, action=None)

Checks if for the given token type a policy to force the server to generate the key is set.

Parameters:

• request

• action

Returns:

True

privacyidea.api.lib.prepolicy.get_first_policy_value(policy_action: str, default: str, scope: str, user: User | None = None, allowed_values: list | None = None) → str

Get the first policy value for the given policy action and scope, using Match.user. If the policy does not exist, return the default value. If allowed_values is provided, check if the policy value is in the allowed values.

privacyidea.api.lib.prepolicy.hide_audit_columns(request=None, action=None)

This pre condition checks for the policy hide_audit_columns and sets the “hidden_columns” parameter for the audit search. The given columns will be removed from the returned audit dict.

Check ACTION.HIDE_AUDIT_COLUMNS

The decorator should wrap GET /audit/

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

Always true. Modified the parameter request

privacyidea.api.lib.prepolicy.hide_container_info(request=None, action=None)

This decorator checks for the policy hide_container_info and sets the hide_container_info parameter in the request object containing a list of container info keys that shall be hidden in the response.

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action – An optional action (not used in this decorator)

Returns:

Always true. Modifies the parameter request

Return type:

bool

privacyidea.api.lib.prepolicy.hide_tokeninfo(request=None, action=None)

This decorator checks for the policy hide_tokeninfo and sets the hidden_tokeninfo parameter.

The given tokeninfo keys will be removed from the response.

The decorator wraps GET /token/

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (str) – An optional Action

Returns:

Always true. Modifies the parameter request

Return type:

bool

privacyidea.api.lib.prepolicy.increase_failcounter_on_challenge(request=None, action=None)

This is a decorator for /validate/check, validate/triggerchallenge and auth which sets the parameter increase_failcounter_on_challenge

privacyidea.api.lib.prepolicy.indexedsecret_force_attribute(request, action)

This is a token specific wrapper for indexedsecret token for the endpoint /token/init The otpkey is overwritten with the value from the user attribute specified in policy scope=SCOPE.USER and SCOPE.ADMIN, action=PIIXACTION.FORCE_ATTRIBUTE. :param request: :param action: :return:

privacyidea.api.lib.prepolicy.init_ca_connector(request=None, action=None)

This is a pre decorator for the endpoint ‘/token/init’. It reads the policy scope=enrollment, action=certificate_ca_connector and sets the API parameter “ca” accordingly.

Parameters:

request – The request to enhance

Returns:

None, but we modify the request

privacyidea.api.lib.prepolicy.init_ca_template(request=None, action=None)

This is a pre decorator for the endpoint ‘/token/init’. It reads the policy scope=enrollment, action=certificate_template and sets the API parameter “template” accordingly.

Parameters:

request – The request to enhance

Returns:

None, but we modify the request

privacyidea.api.lib.prepolicy.init_random_pin(request=None, action=None)

This policy function is to be used as a decorator in the API init function If the policy is set accordingly it adds a random PIN to the request.all_data like.

It uses the policy SCOPE.ENROLL, ACTION.OTPPINRANDOM and ACTION.OTPPINCONTENTS to set a random OTP PIN during Token enrollment

privacyidea.api.lib.prepolicy.init_subject_components(request=None, action=None)

This is a pre decorator for the endpoint ‘/token/init’. It reads the policy scope=enrollment, action=certificate_request_subject_component and sets the API parameter “subject_component” accordingly.

Parameters:

request – The request to enhance

Returns:

None, but we modify the request

privacyidea.api.lib.prepolicy.init_token_defaults(request=None, action=None)

This policy function is used as a decorator for the API init function. Depending on policy settings it can add token specific default values like totp_hashlib, hotp_hashlib, totp_otplen…

privacyidea.api.lib.prepolicy.init_token_length_contents(request=None, action=None)

This policy function is to be used as a decorator in the API token init function.

It can set the parameters for automatic code or password created in regards to length and contents for the tokentypes ‘registration’ and ‘pw’.

If there is a valid policy set the action values of REGISTRATIONCODE_LENGTH / PASSWORD_LENGTH and REGISTRATIONCODE_CONTENTS / PASSWORD_CONTENTS are added to request.all_data as

{ ‘registration.length’: ‘10’, ‘registration.contents’: ‘cn’ } or { ‘pw.length’: ‘10’, ‘pw.contents’: ‘cn’ }

privacyidea.api.lib.prepolicy.init_tokenlabel(request=None, action=None)

This policy function is to be used as a decorator in the API init function. It adds the tokenlabel definition to the params like this: params : { “tokenlabel”: “<u>@<r>” }

In addition, it adds the tokenissuer to the params like this: params : { “tokenissuer”: “privacyIDEA instance” }

It also checks if the force_app_pin policy is set and adds the corresponding value to params.

It uses the policy SCOPE.ENROLL, ACTION.TOKENLABEL and ACTION.TOKENISSUER to set the tokenlabel and tokenissuer of Smartphone tokens during enrollment and this fill the details of the response.

privacyidea.api.lib.prepolicy.is_remote_user_allowed(req, write_to_audit_log=True)

Checks if the REMOTE_USER server variable is allowed to be used.

Note

This is not used as a decorator!

Parameters:

• req – The flask request, containing the remote user and the client IP

• write_to_audit_log (bool) – whether the policy name should be added to the audit log entry

Returns:

Return a value or REMOTE_USER, can be “disable”, “active” or “force”.

Return type:

str

privacyidea.api.lib.prepolicy.jwt_validity(request, action)

This is a decorator for the /auth endpoint to adapt the validity period of the issued JWT. :param request: :param action: :return:

privacyidea.api.lib.prepolicy.load_challenge_text(request, action)

Checks if the policy CHALLENGE_TEXT is active, and if so, add the value to the request data.

privacyidea.api.lib.prepolicy.mangle(request=None, action=None)

This pre condition checks if either of the parameters pass, user or realm in a validate/check request should be rewritten based on an authentication policy with action “mangle”. See mangle for an example.

Check ACTION.MANGLE

This decorator should wrap

/validate/check

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

Always true. Modified the parameter request

privacyidea.api.lib.prepolicy.mock_fail(req, action)

This is a mock function as an example for check_external. This function creates a problem situation and the token/init or token/assign will show this exception accordingly.

privacyidea.api.lib.prepolicy.mock_success(req, action)

This is a mock function as an example for check_external. This function returns success and the API call will go on unmodified.

privacyidea.api.lib.prepolicy.papertoken_count(request=None, action=None)

This is a token specific wrapper for paper token for the endpoint /token/init. According to the policy scope=SCOPE.ENROLL, action=PAPERACTION.PAPER_COUNT it sets the parameter papertoken_count to enroll a paper token with such many OTP values.

Parameters:

• request

• action

Returns:

class privacyidea.api.lib.prepolicy.prepolicy(function, request, action=None)

This is the decorator wrapper to call a specific function before an API call. The prepolicy decorator is to be used in the API calls. A prepolicy decorator then will modify the request data or raise an exception

Parameters:

• function (function) – This is the policy function the is to be called

• request (Request Object) – The original request object, that needs to be passed

privacyidea.api.lib.prepolicy.pushtoken_add_config(request, action)

This is a token specific wrapper for push token for the endpoint /token/init According to the policy scope=SCOPE.ENROLL, action=SSL_VERIFY or action=FIREBASE_CONFIG the parameters are added to the enrollment step. :param request: :param action: :return:

privacyidea.api.lib.prepolicy.pushtoken_disable_wait(request, action)

This is used for the /auth endpoint and sets the PUSH_ACTION.WAIT parameter to False.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.pushtoken_validate(request, action)

This is an auth specific wrapper to decorate /validate/check According to the policy scope=SCOPE.AUTH, action=push_wait and scope=SCOPE.AUTH, action=push_require_presence

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.realmadmin(request=None, action=None)

This decorator adds the first REALM to the parameters if the administrator, calling this API is a realm admin. This way, if the admin calls e.g. GET /user without realm parameter, he will not see all users, but only users in one of his realms.

TODO: If a realm admin is allowed to see more than one realm,

this is not handled at the moment. We need to change the underlying library functions!

Parameters:

• request – The HTTP reqeust

• action – The action like ACTION.USERLIST

privacyidea.api.lib.prepolicy.require_description(request=None, action=None)

Pre Policy This checks if a description is required to roll out a specific token. scope=SCOPE.ENROLL, action=REQUIRE_DESCRIPTION

An exception is raised, if the tokentypes specified in the REQUIRE_DESCRIPTION policy match the token to be rolled out, but no description is given.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.require_description_on_edit(request=None, action=None)

Pre Policy This checks whether a description is required while editing a specific token. scope=SCOPE.TOKEN, action=REQUIRE_DESCRIPTION_ON_EDIT

An exception is raised, if the token types specified in the REQUIRE_DESCRIPTION_ON_EDIT policy match the token to be edited, but no description is given.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.required_email(request=None, action=None)

This precondition checks if the “email” parameter matches the regular expression in the policy scope=register, action=requiredemail. See requiredemail.

Check ACTION.REQUIREDEMAIL

This decorator should wrap POST /register

Parameters:

• request – The Request Object

• action – An optional Action

Returns:

Modifies the request parameters or raises an Exception

privacyidea.api.lib.prepolicy.required_piv_attestation(request, action=None)

This is a token specific decorator for certificate tokens for the endpoint /token/init According to the policy scope=SCOPE.ENROLL, action=REQUIRE_ATTESTATION an exception is raised, if no attestation parameter is given.

It also checks the policy if the attestation should be verified and sets the parameter verify_attestation accordingly.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.rss_age(request, action)

This is a decorator for the /info/rss endpoint to adapt the age of the displayed news feed

Parameters:

• request – Request object

• action – action value is not used in this decorator

Returns:

True

privacyidea.api.lib.prepolicy.save_client_application_type(request, action)

This decorator is used to write the client IP and the HTTP user agent ( clienttype) to the database.

In fact this is not a policy decorator, as it checks no policy. In fact, we could however one day define this as a policy, too. :param req: :return:

privacyidea.api.lib.prepolicy.set_random_pin(request=None, action=None)

This policy function is to be used as a decorator in the API setrandompin function If the policy is set accordingly it adds a random PIN to the request.all_data like.

It uses the policy ACTION.OTPPINSETRANDOM in SCOPE.ADMIN or SCOPE.USER to set a random OTP PIN

privacyidea.api.lib.prepolicy.set_realm(request=None, action=None)

Pre Policy This pre condition gets the current realm and verifies if the realm should be rewritten due to the policy definition. I takes the realm from the request and - if a policy matches - replaces this realm with the realm defined in the policy

Check ACTION.SETREALM

This decorator should wrap

/validate/check

Parameters:

• request (Request Object) – The request that is intercepted during the API call

• action (basestring) – An optional Action

Returns:

Always true. Modified the parameter request

privacyidea.api.lib.prepolicy.smartphone_config(request, action=None)

This decorator gets the smartphone specific configurations from the policies. It is only applied for containers of type smartphone. For all other types or if the type could not be determined, the configuration is not fetched. Raises a PolicyError if conflicting policies exist.

Parameters:

• request – The request object

• action – The action parameter is not used in this decorator

Returns:

True on success, False if the container is not a smartphone

privacyidea.api.lib.prepolicy.sms_identifiers(request=None, action=None)

This is a token specific wrapper for sms tokens to be used with the endpoint /token/init. According to the policy scope=SCOPE.ADMIN or scope=SCOPE.USER action=SMSACTION.GATEWAYS the sms.identifier is only allowed to be set to the listed gateways.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.tantoken_count(request=None, action=None)

This is a token specific wrapper for tan token for the endpoint /token/init. According to the policy scope=SCOPE.ENROLL, action=TANACTION.TANTOKEN_COUNT it sets the parameter tantoken_count to enroll a tan token with such many OTP values.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.twostep_enrollment_activation(request=None, action=None)

This policy function enables the two-step enrollment process according to the configured policies. It is used to decorate the /token/init endpoint.

If a <type>_2step policy matches, the 2stepinit parameter is handled according to the policy. If no policy matches, the 2stepinit parameter is removed from the request data.

privacyidea.api.lib.prepolicy.twostep_enrollment_parameters(request=None, action=None)

If the 2stepinit parameter is set to true, this policy function reads additional configuration from policies and adds it to request.all_data, that is:

• {type}_2step_serversize is written to 2step_serversize

• {type}_2step_clientsize is written to 2step_clientsize

• {type}_2step_difficulty is written to 2step_difficulty

If no policy matches, the value passed by the user is kept.

This policy function is used to decorate the /token/init endpoint.

privacyidea.api.lib.prepolicy.u2ftoken_allowed(request, action)

This is a token specific wrapper for u2f token for the endpoint

/token/init. According to the policy scope=SCOPE.ENROLL, action=U2FACTION.REQ it checks, if the assertion certificate is an allowed U2F token type.

If the token, which is enrolled contains a non allowed attestation certificate, we bail out.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.u2ftoken_verify_cert(request, action)

This is a token specific wrapper for u2f token for the endpoint /token/init According to the policy scope=SCOPE.ENROLL, action=U2FACTION.NO_VERIFY_CERT it can add a parameter to the enrollment parameters to not verify the attestation certificate. The default is to verify the cert. :param request: :param action: :return:

privacyidea.api.lib.prepolicy.verify_enrollment(request=None, action=None)

This is used to verify an already enrolled token. The parameter “verify” is used to do so. If successful, the current rollout_state “verify” of the token will be changed to “enrolled”.

Parameters:

• request

• action

Returns:

privacyidea.api.lib.prepolicy.webauthntoken_allowed(request, action)

This is a token specific wrapper for WebAuthn token for the endpoint /token/init.

According to the policy scope=SCOPE.ENROLL, action=WEBAUTHNACTION.REQ it checks, if the assertion certificate is for an allowed WebAuthn token type. According to the policy scope=SCOPE.ENROLL, action=WEBAUTHNACTION.AUTHENTICATOR_SELECTION_LIST it checks, whether the AAGUID is whitelisted. Note: If self-attestation is allowed, it is – of course – possible to bypass the check for WEBAUTHNACTION.REQ

If the token, which is being enrolled does not contain an allowed attestation certificate, or does not have an allowed AAGUID, we bail out.

A very similar check (same policy actions, different policy scope) is performed during authorization, however due to architectural limitations, this lives within the token implementation itself.

Parameters:

• request

• action

Returns:

Return type:

privacyidea.api.lib.prepolicy.webauthntoken_authz(request, action)

This is a WebAuthn token specific wrapper for the /auth, and /validate/check endpoints.

This will enrich the authorization request for WebAuthn tokens with the necessary configuration information from policy actions with scope=SCOPE.AUTHZ. This is currently the authorization pendant to webauthntoken_allowed(), but maybe expanded to cover other authorization policies in the future, should any be added. The request will as of now simply be augmented with the policies the attestation certificate is to be matched against.

Parameters:

• request

• action

Returns:

Return type:

privacyidea.api.lib.prepolicy.webauthntoken_request(request, action)

This is a WebAuthn token specific wrapper for all endpoints using WebAuthn tokens.

This wraps the endpoints /token/init, /validate/triggerchallenge, /auth, and /validate/check. It will add WebAuthn configuration information to the requests, wherever a piece of information is needed for several different requests and thus cannot be provided by one of the more specific wrappers without adding unnecessary redundancy.

Depending on the type of request, the request will be augmented with some (or all) of the authenticator timeout, user verification requirement and list of allowed AAGUIDs for the current scope, as specified by the policies with the determined scope and the actions WEBAUTHNACTION.TIMEOUT, WEBAUTHNACTION.USER_VERIFICATION_REQUIREMENT, and WEBAUTHNACTION.AUTHENTICATOR_SELECTION_LIST, respectively.

The value of the ORIGIN http header will also be added to the request for the ENROLL and AUTHZ scopes. This is to make the unit tests not require mocking.

Parameters:

• request

• action

Returns:

Return type:

16.2.1.1.2. Post Policies

These are the policy decorators as POST conditions for the API calls. I.e. these conditions are executed after the wrapped API call. This module uses the policy base functions from privacyidea.lib.policy but also components from flask like g.

Wrapping the functions in a decorator class enables easy modular testing.

The functions of this module are tested in tests/test_api_lib_policy.py

privacyidea.api.lib.postpolicy.add_user_detail_to_response(request, response)

This policy decorated is used in the AUTHZ scope. If the boolean value add_user_in_response is set, the details will contain a dictionary “user” with all user details.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.autoassign(request, response)

This decorator decorates the function /validate/check. Depending on ACTION.AUTOASSIGN it checks if the user has no token and if the given OTP-value matches a token in the users realm, that is not yet assigned to any user.

If a token can be found, it assigns the token to the user also taking into account ACTION.MAXTOKENUSER and ACTION.MAXTOKENREALM. :return:

privacyidea.api.lib.postpolicy.check_serial(request, response)

This policy function is to be used in a decorator of an API function. It checks, if the token, that was used in the API call has a serial number that is allowed to be used.

If not, a PolicyException is raised.

Parameters:

• request – The request object

• response (Response object) – The response of the decorated function

Returns:

A new (maybe modified) response

privacyidea.api.lib.postpolicy.check_tokeninfo(request, response)

This policy function is used as a decorator for the validate API. It checks after a successful authentication if the token has a matching tokeninfo field. If it does not match, authorization is denied. Then a PolicyException is raised.

Parameters:

• request – The request object

• response (Response object) – The response of the decorated function

Returns:

A new modified response

privacyidea.api.lib.postpolicy.check_tokentype(request, response)

This policy function is to be used in a decorator of an API function. It checks, if the token, that was used in the API call is of a type that is allowed to be used.

If not, a PolicyException is raised.

Parameters:

• request – The request object

• response (Response object) – The response of the decorated function

Returns:

A new (maybe modified) response

privacyidea.api.lib.postpolicy.check_verify_enrollment(request, response)

This policy decorator is used in the ENROLL scope to decorate the /token/init It will check for action=verify_enrollment and ask the user in a 2nd step to provide information to verify, that the token was successfully enrolled.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.construct_radius_response(request, response)

This decorator implements the /validate/radiuscheck endpoint. In case this URL was requested, a successful authentication results in an empty response with a HTTP 204 status code. An unsuccessful authentication results in an empty response with a HTTP 400 status code.

This needs to be the last decorator, since the JSON response is then lost.

Returns:

privacyidea.api.lib.postpolicy.container_create_via_multichallenge(request: Request, content: dict, container_type: str) → dict

Checks if the user has no registered container of the given type. If not, the container is created and registration is initialized. The registration data is written to the response data as multi challenge. If the according policy is set, the container is created from a template. Any errors that could occur (template not found, max user tokens reached, missing registration policies) are only logged and the content is returned unchanged to not break the authentication flow.

Parameters:

• request – The request object

• content – The content of the response

• container_type – The type of the container to create (e.g., “smartphone”)

Returns:

The modified content with the registration data or unchanged content if no container was created

privacyidea.api.lib.postpolicy.get_webui_settings(request, response)

This decorator is used in the /auth API to add configuration information like the logout_time or the policy_template_url to the response.

Parameters:

• request – flask request object

• response – flask response object

Returns:

the response

privacyidea.api.lib.postpolicy.hide_specific_error_message(request, response)

If hide_specific_error_message policy is enabled and response contains a rejected authentication, overwrite the detail object to contain a generic message and the threadid. # TODO this does not solve the problem that we do not consistently return 401 for failed authentications.

privacyidea.api.lib.postpolicy.is_authorized(request, response)

This policy decorator is used in the AUTHZ scope to decorate the /validate/check and /validate/triggerchallenge endpoint. It will cause authentication to fail, if the policy authorized=deny_access is set.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.mangle_challenge_response(request, response)

This policy decorator is used in the AUTH scope to decorate the /validate/check endpoint. It can modify the contents of the response “detail”->”message” to allow a better readability for a challenge response text.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.multichallenge_enroll_via_validate(request, response)

This is a post decorator to allow enrolling tokens via /validate/check. It checks the AUTH policy ENROLL_VIA_MULTICHALLENGE and enrolls the corresponding token type. It also modifies the response accordingly, so that the client/plugin can display necessary data for the enrollment to the user.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.no_detail_on_fail(request, response)

This policy function is used with the AUTHZ scope. If the boolean value no_detail_on_fail is set, the details will be stripped if the authentication request failed.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.no_detail_on_success(request, response)

This policy function is used with the AUTHZ scope. If the boolean value no_detail_on_success is set, the details will be stripped if the authentication request was successful.

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.offline_info(request, response)

This decorator is used with the function /validate/check. It is not triggered by an ordinary policy but by a MachineToken definition. If for the given Token an offline application is defined, the hashes of OTP values or FIDO2 credential information is added to the response.

class privacyidea.api.lib.postpolicy.postpolicy(function, request=None)

Decorator that allows one to call a specific function after the decorated function. The postpolicy decorator is to be used in the API calls.

Parameters:

• function (function) – This is the policy function the is to be called

• request (Request Object) – The original request object, that needs to be passed

class privacyidea.api.lib.postpolicy.postrequest(function, request=None)

Decorator that is supposed to be used with after_request.

Parameters:

• function (function) – This is the policy function the is to be called

• request (Request Object) – The original request object, that needs to be passed

privacyidea.api.lib.postpolicy.preferred_client_mode(request, response)

This policy function is used to add the preferred client mode. The admin can set the list of client modes in the policy in the same order as he preferred them. The faction will pick the first client mode from the list, that is also in the multichallenge and set it as preferred client mode

Parameters:

• request

• response

Returns:

privacyidea.api.lib.postpolicy.save_pin_change(request, response, serial=None)

This policy function checks if the next_pin_change date should be stored in the tokeninfo table.

1. Check scope:enrollment and ACTION.CHANGE_PIN_FIRST_USE. This action is used, when the administrator enrolls a token or sets a PIN

2. Check scope:enrollment and ACTION.CHANGE_PIN_EVERY is used, if the user changes the PIN.

This function decorates /token/init and /token/setpin. The parameter “pin” and “otppin” is investigated.

Parameters:

• request

• response

• serial

Returns:

privacyidea.api.lib.postpolicy.sign_response(request, response)

This decorator is used to sign the response. It adds the nonce from the request, if it exists and adds the nonce and the signature to the response.

Note

This only works for JSON responses. So if we fail to decode the JSON, we just pass on.

The usual way to use it is to wrap the after_request, so that we can also sign errors, like this:

@postrequest(sign_response, request=request)
def after_request(response):
    ...

Parameters:

• request – The Request object

• response – The Response object