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

GET /realm/superuser

This call returns the list of all superuser realms as they are defined in pi.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": "privacyIDEA 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": "privacyIDEA unknown"
}
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": "privacyIDEA 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": "privacyIDEA unknown"
 }