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

14.1.1.12. Policy endpoints

The policy endpoints are a subset of the system endpoint.

You can read more about policies at Policies.

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/disable/(name)

Disable a given policy by its name.

JSON Parameters:

  • name – The name of the policy

Return:

ID in the database

POST /policy/(name)

Creates a new policy that defines access or behaviour of different actions in eduMFA

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

  • eduMFAnode – The eduMFA 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 eduMFA 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": "eduMFA unknown"
 }
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": "eduMFA 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": "eduMFA 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:

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": "eduMFA unknown"
 }
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": "eduMFA 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 “edumfanodes”, it returns a list of the configured eduMFA 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