The code of this module is tested in tests/test_api_system.py
13.1.1.10. 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
¶ This is a helper function that returns the POSSIBLE policy definitions, that can be used to define your policies.
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/
¶ 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
-
GET
/policy/export/
(export)¶ 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/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" }
-
GET
/policy/defs/
(scope)¶ This is a helper function that returns the POSSIBLE policy definitions, that can be used to define your policies.
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
-
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”
- adminrealm – Realm 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
- client (IP address with subnet) – for which requesting client this should be
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
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" }
-
GET
/policy/
(name)¶ 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" }
-
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" }