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

15.1.1.12. 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

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

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)

  • 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, 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

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, the key, the comparator, the value and active. 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

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