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.

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