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

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 superuser realms

Request Headers

  • PI-Authorization – The authorization token

Example request:

GET /realm/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

Request Headers

  • PI-Authorization – The authorization token

Example request:

GET /realm/ 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",
            "node": "",
            "priority": null,
            "type": "passwdresolver"
          }
        ]
      }
    }
  },
  "version": "privacyIDEA unknown"
}

Changed in version 3.10: The response contains the node and priority of the resolver

POST /realm/(string: realm)/node/(string: nodeid)

This call creates or reconfigures a realm with node specific settings.

The realm contains a list of resolvers and corresponding priorities per node. If the node UUID can not be found in the database, the realm will be configured without a specific node. In the result it returns a list of added resolvers and a list of resolvers, that could not be added.

Parameters

  • realm (string) – The unique name of the realm

  • nodeid (string) – The UUID of the node

Request JSON Object

  • resolver – A JSON object with a list consisting of objects with the resolver name and priority

Request Headers

  • PI-Authorization – The authorization token

Status Codes

  • 200 OK – no error

  • 400 Bad Request –

    • The given node UUID does not exist

    • Could not verify data in request

Example request:

Create a new realm newrealm, that consists of the resolvers resolver1 and resolver2 on the node with UUID 8e4272a9-9037-40df-8aa3-976e4a04b5a9:

POST /realm/newrealm/node/8e4272a9-9037-40df-8aa3-976e4a04b5a9 HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
  "resolver": [
    {
      "name": "resolver1",
      "priority": 1
    },
    {
      "name": "resolver2",
      "priority": 2
    }
  ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
             "status": true,
             "value": {
                 "added": ["resolver1", "resolver2"],
                 "failed": []
             }
   }
   "version": "privacyIDEA unknown"
}

New in version 3.10: Node specific realm configuration

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

Request JSON Object

  • resolvers (string/list) – A comma separated list of unique resolver names or a list object

  • priority (integer) – Additional priority parameters priority.<resolvername> to define the priority of the resolvers within this realm

Response JSON Object

  • status (bool) – Status of the request

  • value – object with a list of added and failed resolvers

Request Headers

  • PI-Authorization – The authorization token

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-Type: application/json

"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

Response JSON Object

  • status (bool) – Status of the request

  • value (integer) – The id of the deleted realm

Request Headers

  • PI-Authorization – The authorization token

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