16.2.1.7. 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.7.1. realm and resolver¶
If these are empty ‘*’, this policy matches each requested realm.
16.2.1.7.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 matches. user1234 will not match user1 but only user1…
16.2.1.7.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.7.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[source]¶
This is the list of usual actions.
- ADDRESOLVERINRESPONSE = 'add_resolver_in_response'¶
- ADDUSER = 'adduser'¶
- ADDUSERINRESPONSE = 'add_user_in_response'¶
- ADMIN_DASHBOARD = 'admin_dashboard'¶
- APIKEY = 'api_key_required'¶
- APPIMAGEURL = 'appimageurl'¶
- APPLICATION_TOKENTYPE = 'application_tokentype'¶
- ASSIGN = 'assign'¶
- AUDIT = 'auditlog'¶
- AUDITPAGESIZE = 'audit_page_size'¶
- AUDIT_AGE = 'auditlog_age'¶
- AUDIT_DOWNLOAD = 'auditlog_download'¶
- AUTHITEMS = 'fetch_authentication_items'¶
- AUTHMAXFAIL = 'auth_max_fail'¶
- AUTHMAXSUCCESS = 'auth_max_success'¶
- AUTHORIZED = 'authorized'¶
- 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'¶
- CHANGE_PIN_VIA_VALIDATE = 'change_pin_via_validate'¶
- CLIENTTYPE = 'clienttype'¶
- CONFIGDOCUMENTATION = 'system_documentation'¶
- CONTAINER_ADD_TOKEN = 'container_add_token'¶
- CONTAINER_ASSIGN_USER = 'container_assign_user'¶
- CONTAINER_CREATE = 'container_create'¶
- CONTAINER_DELETE = 'container_delete'¶
- CONTAINER_DESCRIPTION = 'container_description'¶
- CONTAINER_INFO = 'container_info'¶
- CONTAINER_LIST = 'container_list'¶
- CONTAINER_REALMS = 'container_realms'¶
- CONTAINER_REMOVE_TOKEN = 'container_remove_token'¶
- CONTAINER_STATE = 'container_state'¶
- CONTAINER_UNASSIGN_USER = 'container_unassign_user'¶
- COPYTOKENPIN = 'copytokenpin'¶
- COPYTOKENUSER = 'copytokenuser'¶
- CUSTOM_BASELINE = 'custom_baseline'¶
- CUSTOM_MENU = 'custom_menu'¶
- DEFAULT_TOKENTYPE = 'default_tokentype'¶
- DELETE = 'delete'¶
- DELETEUSER = 'deleteuser'¶
- DELETE_USER_ATTRIBUTES = 'delete_custom_user_attributes'¶
- DELETION_CONFIRMATION = 'deletion_confirmation'¶
- DIALOG_NO_TOKEN = 'dialog_no_token'¶
- DISABLE = 'disable'¶
- EMAILCONFIG = 'smtpconfig'¶
- EMAILVALIDATION = 'email_validation'¶
- ENABLE = 'enable'¶
- ENCRYPTPIN = 'encrypt_pin'¶
- ENROLLPIN = 'enrollpin'¶
- ENROLL_VIA_MULTICHALLENGE = 'enroll_via_multichallenge'¶
- ENROLL_VIA_MULTICHALLENGE_TEXT = 'enroll_via_multichallenge_text'¶
- EVENTHANDLINGREAD = 'eventhandling_read'¶
- EVENTHANDLINGWRITE = 'eventhandling_write'¶
- FORCE_APP_PIN = 'force_app_pin'¶
- FORCE_CHALLENGE_RESPONSE = 'force_challenge_response'¶
- GDPR_LINK = 'privacy_statement_link'¶
- GETCHALLENGES = 'getchallenges'¶
- GETRANDOM = 'getrandom'¶
- GETSERIAL = 'getserial'¶
- HIDE_AUDIT_COLUMNS = 'hide_audit_columns'¶
- HIDE_BUTTONS = 'hide_buttons'¶
- HIDE_TOKENINFO = 'hide_tokeninfo'¶
- HIDE_WELCOME = 'hide_welcome_info'¶
- IMPORT = 'importtokens'¶
- INCREASE_FAILCOUNTER_ON_CHALLENGE = 'increase_failcounter_on_challenge'¶
- JWTVALIDITY = 'jwt_validity'¶
- LASTAUTH = 'last_auth'¶
- LOGINMODE = 'login_mode'¶
- LOGIN_TEXT = 'login_text'¶
- LOGOUTTIME = 'logout_time'¶
- LOGOUT_REDIRECT = 'logout_redirect'¶
- LOSTTOKEN = 'losttoken'¶
- LOSTTOKENPWCONTENTS = 'losttoken_PW_contents'¶
- LOSTTOKENPWLEN = 'losttoken_PW_length'¶
- LOSTTOKENVALID = 'losttoken_valid'¶
- MACHINELIST = 'machinelist'¶
- MACHINERESOLVERDELETE = 'mresolverdelete'¶
- MACHINERESOLVERREAD = 'mresolverread'¶
- MACHINERESOLVERWRITE = 'mresolverwrite'¶
- MACHINETOKENS = 'manage_machine_tokens'¶
- MANAGESUBSCRIPTION = 'managesubscription'¶
- MANGLE = 'mangle'¶
- MAXACTIVETOKENUSER = 'max_active_token_per_user'¶
- 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'¶
- OTPPINSETRANDOM = 'otp_pin_set_random'¶
- PASSNOTOKEN = 'passOnNoToken'¶
- PASSNOUSER = 'passOnNoUser'¶
- PASSTHRU = 'passthru'¶
- PASSTHRU_ASSIGN = 'passthru_assign'¶
- PASSWORDRESET = 'password_reset'¶
- PASSWORD_CONTENTS = 'pw.contents'¶
- PASSWORD_LENGTH = 'pw.length'¶
- PERIODICTASKREAD = 'periodictask_read'¶
- PERIODICTASKWRITE = 'periodictask_write'¶
- PINHANDLING = 'pinhandling'¶
- POLICYDELETE = 'policydelete'¶
- POLICYREAD = 'policyread'¶
- POLICYTEMPLATEURL = 'policy_template_url'¶
- POLICYWRITE = 'policywrite'¶
- PREFERREDCLIENTMODE = 'preferred_client_mode'¶
- PRIVACYIDEASERVERREAD = 'privacyideaserver_read'¶
- PRIVACYIDEASERVERWRITE = 'privacyideaserver_write'¶
- RADIUSSERVERREAD = 'radiusserver_read'¶
- RADIUSSERVERWRITE = 'radiusserver_write'¶
- REALM = 'realm'¶
- REALMDROPDOWN = 'realm_dropdown'¶
- REGISTERBODY = 'registration_body'¶
- REGISTRATIONCODE_CONTENTS = 'registration.contents'¶
- REGISTRATIONCODE_LENGTH = 'registration.length'¶
- REMOTE_USER = 'remote_user'¶
- REQUIREDEMAIL = 'requiredemail'¶
- REQUIRE_DESCRIPTION = 'require_description'¶
- RESET = 'reset'¶
- RESETALLTOKENS = 'reset_all_user_tokens'¶
- RESOLVER = 'resolver'¶
- RESOLVERDELETE = 'resolverdelete'¶
- RESOLVERREAD = 'resolverread'¶
- RESOLVERWRITE = 'resolverwrite'¶
- RESYNC = 'resync'¶
- RESYNC_VIA_MULTICHALLENGE = 'resync_via_multichallenge'¶
- REVOKE = 'revoke'¶
- SEARCH_ON_ENTER = 'search_on_enter'¶
- SERIAL = 'serial'¶
- SERVICEID_ADD = 'serviceid_add'¶
- SERVICEID_DELETE = 'serviceid_delete'¶
- SERVICEID_LIST = 'serviceid_list'¶
- SET = 'set'¶
- SETDESCRIPTION = 'setdescription'¶
- SETHSM = 'set_hsm_password'¶
- SETPIN = 'setpin'¶
- SETRANDOMPIN = 'setrandompin'¶
- SETREALM = 'setrealm'¶
- SETTOKENINFO = 'settokeninfo'¶
- SET_USER_ATTRIBUTES = 'set_custom_user_attributes'¶
- SHOW_ANDROID_AUTHENTICATOR = 'show_android_privacyidea_authenticator'¶
- SHOW_CUSTOM_AUTHENTICATOR = 'show_custom_authenticator'¶
- SHOW_IOS_AUTHENTICATOR = 'show_ios_privacyidea_authenticator'¶
- SHOW_NODE = 'show_node'¶
- SHOW_SEED = 'show_seed'¶
- SMSGATEWAYREAD = 'smsgateway_read'¶
- SMSGATEWAYWRITE = 'smsgateway_write'¶
- SMTPSERVERREAD = 'smtpserver_read'¶
- SMTPSERVERWRITE = 'smtpserver_write'¶
- STATISTICSDELETE = 'statistics_delete'¶
- STATISTICSREAD = 'statistics_read'¶
- SYSTEMDELETE = 'configdelete'¶
- SYSTEMREAD = 'configread'¶
- SYSTEMWRITE = 'configwrite'¶
- TIMEOUT_ACTION = 'timeout_action'¶
- TOKENGROUPS = 'tokengroups'¶
- TOKENGROUP_ADD = 'tokengroup_add'¶
- TOKENGROUP_DELETE = 'tokengroup_delete'¶
- TOKENGROUP_LIST = 'tokengroup_list'¶
- TOKENINFO = 'tokeninfo'¶
- TOKENISSUER = 'tokenissuer'¶
- TOKENLABEL = 'tokenlabel'¶
- TOKENLIST = 'tokenlist'¶
- TOKENPAGESIZE = 'token_page_size'¶
- TOKENREALMS = 'tokenrealms'¶
- TOKENROLLOVER = 'token_rollover'¶
- TOKENTYPE = 'tokentype'¶
- TOKENWIZARD = 'tokenwizard'¶
- TOKENWIZARD2ND = 'tokenwizard_2nd_token'¶
- TRIGGERCHALLENGE = 'triggerchallenge'¶
- UNASSIGN = 'unassign'¶
- UPDATEUSER = 'updateuser'¶
- USERDETAILS = 'user_details'¶
- USERLIST = 'userlist'¶
- USERPAGESIZE = 'user_page_size'¶
- VERIFY_ENROLLMENT = 'verify_enrollment'¶
- class privacyidea.lib.policy.ACTIONVALUE[source]¶
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[source]¶
This is the possible values for autoassign
- NONE = 'any_pin'¶
- USERSTORE = 'userstore'¶
- class privacyidea.lib.policy.CONDITION_CHECK[source]¶
The available check methods for extended conditions
- CHECK_AND_RAISE_EXCEPTION_ON_MISSING = None¶
- DO_NOT_CHECK_AT_ALL = 1¶
- ONLY_CHECK_USERINFO = ['userinfo']¶
- class privacyidea.lib.policy.CONDITION_SECTION[source]¶
This is a list of available sections for conditions of policies
- HTTP_ENVIRONMENT = 'HTTP Environment'¶
- HTTP_REQUEST_HEADER = 'HTTP Request header'¶
- TOKEN = 'token'¶
- TOKENINFO = 'tokeninfo'¶
- USERINFO = 'userinfo'¶
- class privacyidea.lib.policy.GROUP[source]¶
These are the allowed policy action groups. The policies will be grouped in the UI.
- CONDITIONS = 'conditions'¶
- CONTAINER = 'container'¶
- ENROLLMENT = 'enrollment'¶
- GENERAL = 'general'¶
- MACHINE = 'machine'¶
- MODIFYING_RESPONSE = 'modifying response'¶
- PIN = 'pin'¶
- SERVICEID = 'service ID'¶
- SETTING_ACTIONS = 'setting actions'¶
- SYSTEM = 'system'¶
- TOKEN = 'token'¶
- TOKENGROUP = 'tokengroup'¶
- TOOLS = 'tools'¶
- USER = 'user'¶
- class privacyidea.lib.policy.LOGINMODE[source]¶
This is the list of possible values for the login mode.
- DISABLE = 'disable'¶
- PRIVACYIDEA = 'privacyIDEA'¶
- USERSTORE = 'userstore'¶
- class privacyidea.lib.policy.MAIN_MENU[source]¶
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.Match(g, **kwargs)[source]¶
This class provides a high-level API for policy matching.
It should not be instantiated directly. Instead, code should use one of the provided classmethods to construct a
Match
object. See the respective classmethods for details.A
Match
object encapsulates a policy matching operation, i.e. a call toprivacyidea.lib.policy.PolicyClass.match_policies()
. In order to retrieve the matching policies, one should use one ofpolicies()
,action_values()
andany()
. By default, these functions write the matched policies to the audit log. This behavior can be explicitly disabled.Every classmethod expects a so-called “context object” as its first argument. The context object implements the following attributes:
audit_object
: anAudit
object which is used to write the usedpolicies to the audit log. In case False is passed for
write_to_audit_log
, the audit object may be None.
policy_object
: aPolicyClass
object that is used to retrieve thematching policies.
client_ip
: the IP of the current client, as a stringlogged_in_user
: a dictionary with keys “username”, “realm”, “role”that describes the currently logged-in (managing) user
In our case, this context object is usually the
flask.g
object.- classmethod action_only(g, scope, action)[source]¶
Match active policies solely based on a scope and an action, which may also be None. The client IP is matched implicitly.
- Parameters
g – context object
scope – the policy scope. SCOPE.ADMIN cannot be passed,
admin
must be used instead.action – the policy action, or None
- Return type
Match
- action_values(unique, allow_white_space_in_action=False, write_to_audit_log=True)[source]¶
Return a dictionary of action values extracted from the matching policies.
The dictionary maps each action value to a list of policies which define this action value.
- Parameters
unique – If True, return only the prioritized action value. See
privacyidea.lib.policy.PolicyClass.get_action_values()
for details.allow_white_space_in_action – If True, allow whitespace in action values. See
privacyidea.lib.policy.PolicyClass.get_action_values()
for details.write_to_audit_log – If True, augment the audit log with the names of all policies whose action values are returned
- Return type
dict
- classmethod admin(g, action, user_obj=None)[source]¶
Match admin policies with an action and, optionally, a realm. Assumes that the currently logged-in user is an admin, and throws an error otherwise. Policies will be matched against the admin’s username and adminrealm, and optionally also the provided user_obj on which the admin is acting The client IP is matched implicitly.
- Parameters
g – context object
action – the policy action
user_obj (User or None) – the user against which policies should be matched. Can be None.
- Return type
Match
- classmethod admin_or_user(g, action, user_obj)[source]¶
Depending on the role of the currently logged-in user, match either scope=ADMIN or scope=USER policies. If the currently logged-in user is an admin, match policies against the username, adminrealm and the given user_obj on which the admin is acting. If the currently logged-in user is a user, match policies against the username and the given realm. The client IP is matched implicitly.
- Parameters
g – context object
action – the policy action
user_obj – the user_obj on which the administrator is acting
- Return type
Match
- allowed(write_to_audit_log=True)[source]¶
Determine if the matched action is allowed in the scope
admin
oruser
.- This is the case
either if there are no active policies defined in the matched scope
or the action is explicitly allowed by a policy in the matched scope
Example usage:
is_allowed = Match.user(g, scope=SCOPE.USER, action=ACTION.ENROLLPIN, user=user_object).allowed() # is_allowed is now true # either if there is no active policy defined with scope=SCOPE.USER at all # or if there is a policy matching the given scope, action, user and client IP.
- Parameters
write_to_audit_log – If True, write the list of matching policies to the audit log
- Returns
True or False
- any(write_to_audit_log=True)[source]¶
Return True if at least one policy matches.
- Parameters
write_to_audit_log – If True, write the list of matching policies to the audit log
- Returns
True or False
- classmethod generic(g, scope=None, realm=None, resolver=None, user=None, user_object=None, client=None, action=None, adminrealm=None, adminuser=None, time=None, active=True, sort_by_priority=True, serial=None, extended_condition_check=None)[source]¶
Low-level legacy policy matching interface: Search for active policies and return them sorted by priority. All parameters that should be used for matching have to be passed explicitly. The client IP has to be passed explicitly. See
privacyidea.lib.policy.PolicyClass.match_policies()
for details.- Return type
Match
- policies(write_to_audit_log=True)[source]¶
Return a list of policies. The list is sorted by priority, which means that prioritized policies appear first.
- Parameters
write_to_audit_log – If True, write the list of matching policies to the audit log
- Returns
a list of policy dictionaries
- Return type
list
- classmethod realm(g, scope, action, realm)[source]¶
Match active policies with a scope, an action and a user realm. The client IP is matched implicitly.
- Parameters
g – context object
scope – the policy scope. SCOPE.ADMIN cannot be passed,
admin
must be used instead.action – the policy action
realm – the realm to match
- Return type
Match
- classmethod token(g, scope, action, token_obj)[source]¶
Match active policies with a scope, an action and a token object. The client IP is matched implicitly. From the token object we try to determine the user as the owner. If the token has no owner, we try to determine the tokenrealm. We fallback to realm=None
- Parameters
g – context object
scope – the policy scope. SCOPE.ADMIN cannot be passed,
admin
must be used instead.action – the policy action
token_obj – The token where the user object or the realm should match.
- Return type
Match
- classmethod user(g, scope, action, user_object)[source]¶
Match active policies with a scope, an action and a user object (which may be None). The client IP is matched implicitly.
- Parameters
g – context object
scope – the policy scope. SCOPE.ADMIN cannot be passed,
admin
must be used instead.action – the policy action
user_object (User or None) – the user object to match. Might also be None, which means that the policy attributes
user
,realm
andresolver
are ignored.
- Return type
Match
- class privacyidea.lib.policy.PolicyClass[source]¶
A policy object can be used to query the current set of policies. The policy object itself does not store any policies. Instead, every query uses
get_config_object
to retrieve the request-local config object which contains the current set of policies.Hence, reloading the request-local config object also reloads the set of policies.
- static check_for_conflicts(policies, action)[source]¶
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
- static extract_action_values(policies, action, unique=False, allow_white_space_in_action=False)[source]¶
Given an action, extract all values the given policies specify for that action.
- Parameters
policies (list) – a list of policy dictionaries
action (action) – a policy action
unique (bool) – if True, only consider the policy with the highest priority and check for policy conflicts (in this case, raise a PolicyError).
allow_white_space_in_action – Some policies like emailtext would allow entering text with whitespaces. These whitespaces must not be used to separate action values!
- Returns
a dictionary mapping action values to lists of matching policies.
- filter_policies_by_conditions(policies, user_object=None, request_headers=None, serial=None, extended_condition_check=None)[source]¶
Given a list of policy dictionaries and a current user object (if any), return a list of all policies whose conditions match the given user object. Raises a PolicyError if a condition references an unknown section. :param policies: a list of policy dictionaries :param user_object: a User object, or None if there is no current user :param request_headers: The HTTP headers :type request_headers: Request object :param extended_condition_check: A list of sections to check or None. :return: generates a list of policy dictionaries
- get_action_values(action, scope='authorization', realm=None, resolver=None, user=None, client=None, unique=False, allow_white_space_in_action=False, adminrealm=None, adminuser=None, user_object=None, audit_data=None)[source]¶
Get the defined action values for a certain actions.
Calling the function with parameters like:
scope: authorization action: tokentype
would return a dictionary of
{tokentype: policyname}
.A call with the parameters:
scope: authorization action: serial
would return a dictionary of
{serial: policyname}
All parameters not described below are covered in the documentation of
match_policies
.- 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. It could make less sense with an action like ACTION.LASTAUTH - where the value of the action needs to be evaluated in a more special case.
- Return type
dict
- list_policies(name=None, scope=None, realm=None, active=None, resolver=None, user=None, client=None, action=None, pinode=None, adminrealm=None, adminuser=None, sort_by_priority=True)[source]¶
Return the policies, filtered by the given values.
The following rule holds for all filter arguments:
If
None
is passed as a value, policies are not filtered according to the argument at all. As an example, ifrealm=None
is passed, policies are matched regardless of theirrealm
attribute. If any value is passed (even the empty string), policies are filtered according to the given value. As an example, ifrealm=''
is passed, only policies that have a matching (or empty) realm attribute are returned.The only exception is the
client
parameter, which does not accept the empty string, and throws a ParameterError if the empty string is passed.- Parameters
name – The name of the policy
scope – The scope of the policy
realm – The realm in the policy
active – One of None, True, False: All policies, only active or only inactive policies
resolver – Only policies with this resolver
pinode – Only policies with this privacyIDEA node
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.
adminuser – This is the username of the admin. This in only evaluated in the scope admin.
sort_by_priority (bool) – If true, sort the resulting list by priority, ascending by their policy numbers.
- Returns
list of policies
- Return type
list of dicts
- match_policies(name=None, scope=None, realm=None, active=None, resolver=None, user=None, user_object=None, pinode=None, client=None, action=None, adminrealm=None, adminuser=None, time=None, sort_by_priority=True, audit_data=None, request_headers=None, serial=None, extended_condition_check=None)[source]¶
Return all policies matching the given context. Optionally, write the matching policies to the audit log.
In order to retrieve policies matching the current user, callers can either pass a user(name), resolver and realm, or pass a user object from which login name, resolver and realm will be read. In case of conflicting parameters, a ParameterError will be raised.
This function takes all parameters taken by
list_policies
, plus some additional parameters.- Parameters
name – see
list_policies
scope – see
list_policies
realm – see
list_policies
active – see
list_policies
resolver – see
list_policies
user – see
list_policies
client – see
list_policies
action – see
list_policies
adminrealm – see
list_policies
adminuser – see
list_policies
pinode – see
list_policies
sort_by_priority –
user_object (User or None) – the currently active user, or None
time (datetime or None) – return only policies that are valid at the specified time. Defaults to the current time.
audit_data (dict or None) – A dictionary with audit data collected during a request. This method will add found policies to the dictionary.
request_headers – A dict with HTTP headers
- Returns
a list of policy dictionaries
- property policies¶
Shorthand to retrieve the set of policies of the request-local config object
- ui_get_enroll_tokentypes(client, logged_in_user)[source]¶
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
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)[source]¶
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[source]¶
The list of possible values for the remote_user policy.
- ACTIVE = 'allowed'¶
- DISABLE = 'disable'¶
- FORCE = 'force'¶
- class privacyidea.lib.policy.SCOPE[source]¶
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'¶
- REGISTER = 'register'¶
- USER = 'user'¶
- WEBUI = 'webui'¶
- class privacyidea.lib.policy.TIMEOUT_ACTION[source]¶
This is a list of actions values for idle users
- LOCKSCREEN = 'lockscreen'¶
- LOGOUT = 'logout'¶
- privacyidea.lib.policy.check_pin(g, pin, tokentype, user_obj)[source]¶
get the policies for minimum length, maximum length and PIN contents first try to get a token specific policy - otherwise fall back to default policy.
Raises an exception, if the PIN does not comply to the policies.
- Parameters
g –
pin –
tokentype –
user_obj –
- privacyidea.lib.policy.delete_policy(name)[source]¶
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)[source]¶
Enable or disable the policy with the given name.
- Parameters
name (str) – Name of the policy
enable (bool) – Set to True to enable the policy
- Returns
ID of the policy
- Return type
int
- privacyidea.lib.policy.export_policies(policies)[source]¶
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)[source]¶
This function is used in the library level to fetch policy action values from a given option dictionary.
The matched policies are not written to the audit log.
- Returns
A scalar, string or None
- privacyidea.lib.policy.get_allowed_custom_attributes(g, user_obj)[source]¶
Return the list off allowed custom user attributes that can be set and deleted. Returns a dictionary with the two keys “delete” and “set.
- Parameters
g –
user_obj – The User object to check the allowed attributes for
- Returns
dict
- privacyidea.lib.policy.get_policy_condition_comparators()[source]¶
- Returns
a dictionary mapping comparators to dictionaries with the following keys: *
"description"
, a human-readable description of the comparator
- privacyidea.lib.policy.get_policy_condition_sections()[source]¶
- Returns
a dictionary mapping condition sections to dictionaries with the following keys: *
"description"
, a human-readable description of the section
- privacyidea.lib.policy.get_static_policy_definitions(scope=None)[source]¶
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.
- Return type
dict
- privacyidea.lib.policy.import_policies(file_contents)[source]¶
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, adminuser=None, priority=None, check_all_resolvers=False, conditions=None, pinode=None, description=None, user_case_insensitive=False)[source]¶
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:
- Parameters
name – The name of the policy
scope – The scope of the policy. Something like “admin” or “authentication”
action – A scope specific action or a comma separated list of actions
realm – A realm, for which this policy is valid
resolver – A resolver, for which this policy is valid
user – A username or a list of usernames
time – N/A if type()
client – A client IP with optionally a subnet like 172.16.0.0/16
active (bool) – If the policy is active or not
adminrealm (str) – The name of the realm of administrators
adminuser (str) – A comma separated list of administrators
priority (int) – the priority of the policy (smaller values having higher priority)
check_all_resolvers (bool) – If all the resolvers of a user should be checked with this policy
user_case_insensitive (bool) – The username should be case-insensitive.
conditions – A list of 5-tuples (section, key, comparator, value, active) of policy conditions
pinode – A privacyIDEA node or a list of privacyIDEA nodes.
description (str) – A description for the policy
- Returns
The database ID of the policy
- Return type
int