The code of this module is tested in tests/test_api_system.py
16.1.1.13. Policy endpoints¶
The policy endpoints are a subset of the system endpoint.
You can read more about policies at Policies.
- GET /policy/check¶
This function checks, if the given parameters would match a defined policy or not.
- Query Parameters
user – the name of the user
realm – the realm of the user or the realm the administrator want to do administrative tasks on.
resolver – the resolver of a user
scope – the scope of the policy
action – the action that is done - if applicable
client (IP_Address) – the client, from which this request would be issued
- Return
a json result with the keys allowed and policy in the value key
- Rtype
json
- Status Codes
200 OK – Policy created or modified.
401 Unauthorized – Authentication failed
Example request:
GET /policy/check?user=admin&realm=r1&client=172.16.1.1 HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "pol_update_del": { "action": "enroll", "active": true, "client": "172.16.0.0/16", "name": "pol_update_del", "realm": "r1", "resolver": "test", "scope": "selfservice", "time": "", "user": "admin" } } }, "version": "privacyIDEA unknown" }
- GET /policy/defs/(scope)¶
- GET /policy/defs¶
This is a helper function that returns the POSSIBLE policy definitions, that can be used to define your policies.
- If the given scope is “conditions”, this returns a dictionary with the following keys:
"sections"
, containing a dictionary mapping each condition section name to a dictionary with the following keys:"description"
, a human-readable description of the section
"comparators"
, containing a dictionary mapping each comparator to a dictionary with the following keys:"description"
, a human-readable description of the comparator
if the scope is “pinodes”, it returns a list of the configured privacyIDEA nodes.
- Query Parameters
scope – if given, the function will only return policy definitions for the given scope.
- Return
The policy definitions of the allowed scope with the actions and action types. The top level key is the scope.
- Rtype
dict
- GET /policy/export/(export)¶
- GET /policy/(name)¶
- GET /policy/¶
this function is used to retrieve the policies that you defined. It can also be used to export the policy to a file.
- Query Parameters
name – will only return the policy with the given name
export – The filename needs to be specified as the third part of the URL like policy.cfg. It will then be exported to this file.
realm – will return all policies in the given realm
scope – will only return the policies within the given scope
active – Set to true or false if you only want to display active or inactive policies.
- Return
a json result with the configuration of the specified policies
- Rtype
json
- Status Codes
200 OK – Policy created or modified.
401 Unauthorized – Authentication failed
Example request:
In this example a policy “pol1” is created.
GET /policy/pol1 HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "pol_update_del": { "action": "enroll", "active": true, "client": "1.1.1.1", "name": "pol_update_del", "realm": "r1", "resolver": "test", "scope": "selfservice", "time": "", "user": "admin" } } }, "version": "privacyIDEA unknown" }
- POST /policy/disable/(name)¶
Disable a given policy by its name.
- JSON Parameters
name – The name of the policy
- Return
ID in the database
- POST /policy/enable/(name)¶
Enable a given policy by its name.
- JSON Parameters
name – Name of the policy
- Return
ID in the database
- POST /policy/import/(filename)¶
This function is used to import policies from a file.
- JSON Parameters
filename – The name of the file in the request
- Form Parameters
file – The uploaded file contents
- Return
A json response with the number of imported policies.
- Status Codes
200 OK – Policy created or modified.
401 Unauthorized – Authentication failed
Example request:
POST /policy/import/backup-policy.cfg HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": 2 }, "version": "privacyIDEA unknown" }
- POST /policy/(name)¶
Creates a new policy that defines access or behaviour of different actions in privacyIDEA
- JSON Parameters
name (basestring) – name of the policy
scope – the scope of the policy like “admin”, “system”, “authentication” or “selfservice”
priority – the priority of the policy
description – a description of the policy
adminrealm – Realm of the administrator. (only for admin scope)
adminuser – Username of the administrator. (only for admin scope)
action – which action may be executed
realm – For which realm this policy is valid
resolver – This policy is valid for this resolver
user – The policy is valid for these users. string with wild cards or list of strings
time – on which time does this policy hold
pinode – The privacyIDEA node (or list of nodes) for which this policy is valid
client (IP address with subnet) – for which requesting client this should be
active – bool, whether this policy is active or not
check_all_resolvers – bool, whether all all resolvers in which the user exists should be checked with this policy.
conditions – a (possibly empty) list of conditions of the policy. Each condition is encoded as a list with 5 elements:
[section (string), key (string), comparator (string), value (string), active (boolean)]
Hence, theconditions
parameter expects a list of lists. When privacyIDEA checks if a defined policy should take effect, all conditions of the policy must be fulfilled for the policy to match. Note that the order of conditions is not guaranteed to be preserved.
- Return
a json result with success or error
- Status Codes
200 OK – Policy created or modified.
401 Unauthorized – Authentication failed
Example request:
In this example a policy “pol1” is created.
POST /policy/pol1 HTTP/1.1 Host: example.com Accept: application/json scope=admin realm=realm1 action=enroll, disable
The policy POST request can also take the parameter of conditions. This is a list of conditions sets: [ [ “userinfo”, “memberOf”, “equals”, “groupA”, “true” ], [ … ] ] With the entries being the
section
, thekey
, thecomparator
, thevalue
andactive
. For more on conditions see Extended Policy Conditions.Example response:
HTTP/1.0 200 OK Content-Length: 354 Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "setPolicy pol1": 1 } }, "version": "privacyIDEA unknown" }
- DELETE /policy/(name)¶
This deletes the policy of the given name.
- JSON Parameters
name – the policy with the given name
- Return
a json result about the delete success. In case of success value > 0
- Status Codes
200 OK – Policy created or modified.
401 Unauthorized – Authentication failed
Example request:
In this example a policy “pol1” is created.
DELETE /policy/pol1 HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.0 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": 1 }, "version": "privacyIDEA unknown" }