14.1.1.8. Realm endpoints¶
The realm endpoints are used to define realms. A realm groups together many users. Administrators can manage the tokens of the users in such a realm. Policies and tokens can be assigned to realms.
A realm consists of several resolvers. Thus you can create a realm and gather users from LDAP and flat file source into one realm or you can pick resolvers that collect users from different points from your vast LDAP directory and group these users into a realm.
You will only be able to see and use user object, that are contained in a realm.
The code of this module is tested in tests/test_api_system.py
- POST /realm/(realm)¶
This call creates a new realm or reconfigures a realm. The realm contains a list of resolvers.
In the result it returns a list of added resolvers and a list of resolvers, that could not be added.
- Parameters:
realm – The unique name of the realm
resolvers (string or list) – A comma separated list of unique resolver names or a list object
priority – Additional parameters priority.<resolvername> define the priority of the resolvers within this realm.
- Return:
a json result with a list of Realms
Example request:
To create a new realm “newrealm”, that consists of the resolvers “reso1_with_realm” and “reso2_with_realm” call:
POST /realm/newrealm HTTP/1.1 Host: example.com Accept: application/json Content-Length: 26 Content-Type: application/x-www-form-urlencoded resolvers=reso1_with_realm, reso2_with_realm priority.reso1_with_realm=1 priority.reso2_with_realm=2
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "added": ["reso1_with_realm", "reso2_with_realm"], "failed": [] } } "version": "eduMFA unknown" }
- GET /realm/¶
This call returns the list of all defined realms. It takes no arguments.
- Return:
a json result with a list of realms
Example request:
GET / HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "realm1_with_resolver": { "default": true, "resolver": [ { "name": "reso1_with_realm", "type": "passwdresolver" } ] } } }, "version": "eduMFA unknown" }
- GET /realm/superuser¶
This call returns the list of all superuser realms as they are defined in edumfa.cfg. See The Config File for more information about this.
- Return:
a json result with a list of realms
Example request:
GET /superuser HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": ["superuser", "realm2"] } }, "version": "eduMFA unknown" }
- DELETE /realm/(realm)¶
This call deletes the given realm.
- Parameters:
realm – The name of the realm to delete
- Return:
a json result with value=1 if deleting the realm was successful
Example request:
DELETE /realm/realm_to_delete HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": 1 }, "version": "eduMFA unknown" }