13.2.1.6. API Policies

13.2.1.6.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 performed, if a JWT token is passed with role=validate.

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

This decorator function takes the request and verifies the given action for the SCOPE ADMIN or USER. :param req: :param action: :return: True otherwise raises an Exception

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:

• req (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

This decorator can wrap:

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

Parameters:

• req –
• 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 in the SCOPE.USER. It is used to decorate the API functions.

The pin is investigated in the params as pin = params.get(“pin”)

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

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. :param request: :param action: :return: True or an Exception is raised

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 :param req: :param filename: :return:

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.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 to set a random OTP PIN during Token enrollment

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>” }

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

privacyidea.api.lib.prepolicy.is_remote_user_allowed(req)

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 Returns:

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.

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

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

13.2.1.6.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.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:response (Response object) – The response of the decorated function Returns:A new (maybe 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:response (Response object) – The response of the decorated function Returns:A new (maybe modified) response

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. :param request: flask request object :param response: flask response object :return: the response

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 Client and Token an offline application is defined, the response is enhanced with the offline information - the hashes of the OTP.

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.

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

Decorator that is supposed to be used with after_request.

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 exist 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.

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

Parameters:

• request – The Request object
• response – The Response object