The code of this module is tested in tests/test_api_system.py

16.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:

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

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:

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”
  • 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
  • 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, the conditions 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:

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"
 }
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:

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