16.2.1.5. Policy Module

Base function to handle the policy entries in the database. This module only depends on the db/models.py

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

A policy has the attributes

• name
• scope
• action
• realm
• resolver
• user
• client
• active

name is the unique identifier of a policy. scope is the area, where this policy is meant for. This can be values like admin, selfservice, authentication… scope takes only one value.

active is bool and indicates, whether a policy is active or not.

action, realm, resolver, user and client can take a comma separated list of values.

16.2.1.5.1. realm and resolver

If these are empty ‘*’, this policy matches each requested realm.

16.2.1.5.2. user

If the user is empty or ‘*’, this policy matches each user. You can exclude users from matching this policy, by prepending a ‘-‘ or a ‘!’. *, -admin will match for all users except the admin.

You can also use regular expressions to match the user like customer_.* to match any user, starting with customer_.

Note

Regular expression will only work for exact machtes. user1234 will not match user1 but only user1…

16.2.1.5.3. client

The client is identified by its IP address. A policy can contain a list of IP addresses or subnets. You can exclude clients from subnets by prepending the client with a ‘-‘ or a ‘!’. 172.16.0.0/24, -172.16.0.17 will match each client in the subnet except the 172.16.0.17.

16.2.1.5.4. time

You can specify a time in which the policy should be active. Time formats are

<dow>-<dow>:<hh>:<mm>-<hh>:<mm>, … <dow>:<hh>:<mm>-<hh>:<mm> <dow>:<hh>-<hh>

and any combination of it. “dow” being day of week Mon, Tue, Wed, Thu, Fri, Sat, Sun.

class privacyidea.lib.policy.ACTION

This is the list of usual actions.

ADDRESOLVERINRESPONSE = 'add_resolver_in_response'

ADDUSER = 'adduser'

ADDUSERINRESPONSE = 'add_user_in_response'

APIKEY = 'api_key_required'

APPIMAGEURL = 'appimageurl'

ASSIGN = 'assign'

AUDIT = 'auditlog'

AUDIT_AGE = 'auditlog_age'

AUDIT_DOWNLOAD = 'auditlog_download'

AUTHITEMS = 'fetch_authentication_items'

AUTHMAXFAIL = 'auth_max_fail'

AUTHMAXSUCCESS = 'auth_max_success'

AUTH_CACHE = 'auth_cache'

AUTOASSIGN = 'autoassignment'

CACONNECTORDELETE = 'caconnectordelete'

CACONNECTORREAD = 'caconnectorread'

CACONNECTORWRITE = 'caconnectorwrite'

CHALLENGERESPONSE = 'challenge_response'

CHALLENGETEXT = 'challenge_text'

CHALLENGETEXT_FOOTER = 'challenge_text_footer'

CHALLENGETEXT_HEADER = 'challenge_text_header'

CHANGE_PIN_EVERY = 'change_pin_every'

CHANGE_PIN_FIRST_USE = 'change_pin_on_first_use'

CLIENTTYPE = 'clienttype'

CONFIGDOCUMENTATION = 'system_documentation'

COPYTOKENPIN = 'copytokenpin'

COPYTOKENUSER = 'copytokenuser'

CUSTOM_BASELINE = 'custom_baseline'

CUSTOM_MENU = 'custom_menu'

DEFAULT_TOKENTYPE = 'default_tokentype'

DELETE = 'delete'

DELETEUSER = 'deleteuser'

DISABLE = 'disable'

EMAILCONFIG = 'smtpconfig'

ENABLE = 'enable'

ENCRYPTPIN = 'encrypt_pin'

ENROLLPIN = 'enrollpin'

EVENTHANDLINGWRITE = 'eventhandling_write'

GETCHALLENGES = 'getchallenges'

GETRANDOM = 'getrandom'

GETSERIAL = 'getserial'

HIDE_BUTTONS = 'hide_buttons'

HIDE_WELCOME = 'hide_welcome_info'

IMPORT = 'importtokens'

LASTAUTH = 'last_auth'

LOGINMODE = 'login_mode'

LOGIN_TEXT = 'login_text'

LOGOUTTIME = 'logout_time'

LOSTTOKEN = 'losttoken'

LOSTTOKENPWCONTENTS = 'losttoken_PW_contents'

LOSTTOKENPWLEN = 'losttoken_PW_length'

LOSTTOKENVALID = 'losttoken_valid'

MACHINELIST = 'machinelist'

MACHINERESOLVERDELETE = 'mresolverdelete'

MACHINERESOLVERWRITE = 'mresolverwrite'

MACHINETOKENS = 'manage_machine_tokens'

MANAGESUBSCRIPTION = 'managesubscription'

MANGLE = 'mangle'

MAXTOKENREALM = 'max_token_per_realm'

MAXTOKENUSER = 'max_token_per_user'

NODETAILFAIL = 'no_detail_on_fail'

NODETAILSUCCESS = 'no_detail_on_success'

OTPPIN = 'otppin'

OTPPINCONTENTS = 'otp_pin_contents'

OTPPINMAXLEN = 'otp_pin_maxlength'

OTPPINMINLEN = 'otp_pin_minlength'

OTPPINRANDOM = 'otp_pin_random'

PASSNOTOKEN = 'passOnNoToken'

PASSNOUSER = 'passOnNoUser'

PASSTHRU = 'passthru'

PASSWORDRESET = 'password_reset'

PERIODICTASKWRITE = 'periodictask_write'

PINHANDLING = 'pinhandling'

POLICYDELETE = 'policydelete'

POLICYTEMPLATEURL = 'policy_template_url'

POLICYWRITE = 'policywrite'

PRIVACYIDEASERVERWRITE = 'privacyideaserver_write'

RADIUSSERVERWRITE = 'radiusserver_write'

REALM = 'realm'

REALMDROPDOWN = 'realm_dropdown'

REGISTERBODY = 'registration_body'

REMOTE_USER = 'remote_user'

REQUIREDEMAIL = 'requiredemail'

RESET = 'reset'

RESETALLTOKENS = 'reset_all_user_tokens'

RESOLVER = 'resolver'

RESOLVERDELETE = 'resolverdelete'

RESOLVERWRITE = 'resolverwrite'

RESYNC = 'resync'

REVOKE = 'revoke'

SEARCH_ON_ENTER = 'search_on_enter'

SERIAL = 'serial'

SET = 'set'

SETHSM = 'set_hsm_password'

SETPIN = 'setpin'

SETREALM = 'setrealm'

SETTOKENINFO = 'settokeninfo'

SHOW_SEED = 'show_seed'

SMSGATEWAYWRITE = 'smsgateway_write'

SMTPSERVERWRITE = 'smtpserver_write'

STATISTICSDELETE = 'statistics_delete'

STATISTICSREAD = 'statistics_read'

SYSTEMDELETE = 'configdelete'

SYSTEMWRITE = 'configwrite'

TIMEOUT_ACTION = 'timeout_action'

TOKENINFO = 'tokeninfo'

TOKENISSUER = 'tokenissuer'

TOKENLABEL = 'tokenlabel'

TOKENPAGESIZE = 'token_page_size'

TOKENREALMS = 'tokenrealms'

TOKENTYPE = 'tokentype'

TOKENWIZARD = 'tokenwizard'

TOKENWIZARD2ND = 'tokenwizard_2nd_token'

TRIGGERCHALLENGE = 'triggerchallenge'

UNASSIGN = 'unassign'

UPDATEUSER = 'updateuser'

USERDETAILS = 'user_details'

USERLIST = 'userlist'

USERPAGESIZE = 'user_page_size'

class privacyidea.lib.policy.ACTIONVALUE

This is a list of usual action values for e.g. policy action-values like otppin.

DISABLE = 'disable'

NONE = 'none'

TOKENPIN = 'tokenpin'

USERSTORE = 'userstore'

class privacyidea.lib.policy.AUTOASSIGNVALUE

This is the possible values for autoassign

NONE = 'any_pin'

USERSTORE = 'userstore'

class privacyidea.lib.policy.GROUP

These are the allowed policy action groups. The policies will be grouped in the UI.

ENROLLMENT = 'enrollment'

GENERAL = 'general'

MACHINE = 'machine'

PIN = 'pin'

SYSTEM = 'system'

TOKEN = 'token'

TOOLS = 'tools'

USER = 'user'

class privacyidea.lib.policy.LOGINMODE

This is the list of possible values for the login mode.

DISABLE = 'disable'

PRIVACYIDEA = 'privacyIDEA'

USERSTORE = 'userstore'

class privacyidea.lib.policy.MAIN_MENU

These are the allowed top level menu items. These are used to toggle the visibility of the menu items depending on the rights of the user

AUDIT = 'audit'

COMPONENTS = 'components'

CONFIG = 'config'

MACHINES = 'machines'

TOKENS = 'tokens'

USERS = 'users'

class privacyidea.lib.policy.PolicyClass

The Policy_Object will contain all database policy entries for easy filtering and mangling. It will be created at the beginning of the request and is supposed to stay alive unchanged during the request.

static check_for_conflicts(policies, action)

Given a (not necessarily sorted) list of policy dictionaries and an action name, check that there are no action value conflicts.

This raises a PolicyError if there are multiple policies with the highest priority which define different values for action.

Otherwise, the function just returns nothing.

Parameters:

• policies – list of dictionaries
• action – string

get_action_values(action, scope='authorization', realm=None, resolver=None, user=None, client=None, unique=False, allow_white_space_in_action=False, adminrealm=None, audit_data=None)

Get the defined action values for a certain action like

scope: authorization action: tokentype

would return a dictionary of {tokentype: policyname}

scope: authorization action: serial

would return a dictionary of {serial: policyname}

Parameters:

• unique – if set, the function will only consider the policy with the highest priority and check for policy conflicts.
• allow_white_space_in_action (bool) – Some policies like emailtext would allow entering text with whitespaces. These whitespaces must not be used to separate action values!
• audit_data – This is a dictionary, that can take audit_data in the g object. If set, this dictionary will be filled with the list of triggered policynames in the key “policies”. This can be useful for policies like ACTION.OTPPIN - where it is clear, that the found policy will be used. I could make less sense with an aktion like ACTION.LASTAUTH - where the value of the action needs to be evaluated in a more special case.

Return type:

dict

get_policies(name=None, scope=None, realm=None, active=None, resolver=None, user=None, client=None, action=None, adminrealm=None, time=None, all_times=False, sort_by_priority=True, audit_data=None)

Return the policies of the given filter values.

Parameters:

• name – The name of the policy
• scope – The scope of the policy
• realm – The realm in the policy
• active – Only active policies
• resolver – Only policies with this resolver
• user (basestring) – Only policies with this user
• client –
• action – Only policies, that contain this very action.
• adminrealm – This is the realm of the admin. This is only evaluated in the scope admin.
• time (datetime) – The optional time, for which the policies should be fetched. The default time is now()
• all_times (bool) – If True the time restriction of the policies is ignored. Policies of all time ranges will be returned.
• sort_by_priority – If true, sort the resulting list by priority, ascending

by their policy numbers. :type sort_by_priority: bool :param audit_data: A dictionary with audit data collected during a request. This

method will add found policies to the dictionary.

Returns:list of policies Return type:list of dicts

reload_from_db()

Read the timestamp from the database. If the timestamp is newer than the internal timestamp, then read the complete data :return:

ui_get_enroll_tokentypes(client, logged_in_user)

Return a dictionary of the allowed tokentypes for the logged in user. This used for the token enrollment UI.

It looks like this:

{“hotp”: “HOTP: event based One Time Passwords”,

“totp”: “TOTP: time based One Time Passwords”, “spass”: “SPass: Simple Pass token. Static passwords”, “motp”: “mOTP: classical mobile One Time Passwords”, “sshkey”: “SSH Public Key: The public SSH key”, “yubikey”: “Yubikey AES mode: One Time Passwords with Yubikey”, “remote”: “Remote Token: Forward authentication request to another server”, “yubico”: “Yubikey Cloud mode: Forward authentication request to YubiCloud”, “radius”: “RADIUS: Forward authentication request to a RADIUS server”, “email”: “EMail: Send a One Time Passwort to the users email address”, “sms”: “SMS: Send a One Time Password to the users mobile phone”, “certificate”: “Certificate: Enroll an x509 Certificate Token.”}

Parameters:

• client (basestring) – Client IP address
• logged_in_user (dict) – The Dict of the logged in user

Returns:

list of token types, the user may enroll

ui_get_main_menus(logged_in_user, client=None)

Get the list of allowed main menus derived from the policies for the given user - admin or normal user. It fetches all policies for this user and compiles a list of allowed menus to display or hide in the UI.

Parameters:

• logged_in_user – The logged in user, a dictionary with keys “username”, “realm” and “role”.
• client – The IP address of the client

Returns:

A list of MENUs to be displayed

ui_get_rights(scope, realm, username, client=None)

Get the rights derived from the policies for the given realm and user. Works for admins and normal users. It fetches all policies for this user and compiles a maximum list of allowed rights, that can be used to hide certain UI elements.

Parameters:

• scope – Can be SCOPE.ADMIN or SCOPE.USER
• realm – Is either user users realm or the adminrealm
• username – The loginname of the user
• client – The HTTP client IP

Returns:

A list of actions

class privacyidea.lib.policy.REMOTE_USER

The list of possible values for the remote_user policy.

ACTIVE = 'allowed'

DISABLE = 'disable'

class privacyidea.lib.policy.SCOPE

This is the list of the allowed scopes that can be used in policy definitions.

ADMIN = 'admin'

AUDIT = 'audit'

AUTH = 'authentication'

AUTHZ = 'authorization'

ENROLL = 'enrollment'

GETTOKEN = 'gettoken'

REGISTER = 'register'

USER = 'user'

WEBUI = 'webui'

class privacyidea.lib.policy.TIMEOUT_ACTION

This is a list of actions values for idle users

LOCKSCREEN = 'lockscreen'

LOGOUT = 'logout'

privacyidea.lib.policy.delete_all_policies()

privacyidea.lib.policy.delete_policy(name)

Function to delete one named policy. Raise ResourceNotFoundError if there is no such policy.

Parameters:name – the name of the policy to be deleted Returns:the ID of the deleted policy Return type:int

privacyidea.lib.policy.enable_policy(name, enable=True)

Enable or disable the policy with the given name :param name: :return: ID of the policy

privacyidea.lib.policy.export_policies(policies)

This function takes a policy list and creates an export file from it

Parameters:policies (list of policy dictionaries) – a policy definition Returns:the contents of the file Return type:string

privacyidea.lib.policy.get_action_values_from_options(scope, action, options)

This function is used in the library level to fetch policy action values from a given option dictionary.

Returns:A scalar, string or None

privacyidea.lib.policy.get_static_policy_definitions(scope=None)

These are the static hard coded policy definitions. They can be enhanced by token based policy definitions, that can be found in lib.token.get_dynamic_policy_definitions.

Parameters:scope (basestring) – Optional the scope of the policies Returns:allowed scopes with allowed actions, the type of action and a

description. :rtype: dict

privacyidea.lib.policy.import_policies(file_contents)

This function imports policies from a file. The file has a config_object format, i.e. the text file has a header

[<policy_name>] key = value

and key value pairs.

Parameters:file_contents (basestring) – The contents of the file Returns:number of imported policies Return type:int

privacyidea.lib.policy.set_policy(name=None, scope=None, action=None, realm=None, resolver=None, user=None, time=None, client=None, active=True, adminrealm=None, priority=None, check_all_resolvers=False)

Function to set a policy. If the policy with this name already exists, it updates the policy. It expects a dict of with the following keys: :param name: The name of the policy :param scope: The scope of the policy. Something like “admin” or “authentication” :param action: A scope specific action or a comma separated list of actions :type active: basestring :param realm: A realm, for which this policy is valid :param resolver: A resolver, for which this policy is valid :param user: A username or a list of usernames :param time: N/A if type() :param client: A client IP with optionally a subnet like 172.16.0.0/16 :param active: If the policy is active or not :type active: bool :param priority: the priority of the policy (smaller values having higher priority) :type priority: int :param check_all_resolvers: If all the resolvers of a user should be

checked with this policy

Returns:The database ID od the the policy Return type:int