Roles and Tenants API

Used to receive, create, update and delete roles and their respective permissions.

Endpoint

/_searchguard/api/roles/{rolename}

Where rolename is the name of the role.

GET

Get a single role

GET /_searchguard/api/roles/{rolename}

Retrieve a role and its permissions, specified by rolename, in JSON format.

GET /_searchguard/api/roles/sg_human_resources_trainee

{  
  "sg_human_resources_trainee" : {
    "reserved" : false,
    "hidden" : false,
    "static" : false,
    "cluster_permissions" : [
      "SGS_CLUSTER_COMPOSITE_OPS_RO"
    ],
    "index_permissions" : [
      {
        "index_patterns" : [
          "humanresources"
        ],
        "dls" : "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
        "fls" : [
          "Designation",
          "FirstName",
          "LastName",
          "Salary"
        ],
        "masked_fields" : [ ],
        "allowed_actions" : [
          "SGS_READ"
        ]
      }
    ],
    "tenant_permissions" : [
      {
        "tenant_patterns" : [
          "human_resources"
        ],
        "allowed_actions" : [
          "SGS_KIBANA_ALL_WRITE"
        ]
      }
    ]    
  }
}

Get all roles

GET /_searchguard/api/roles/{rolename}

Returns all roles in JSON format.

DELETE

DELETE /_searchguard/api/roles/{rolename}

Deletes the role specified by rolename. If successful, the call returns with status code 200 and a JSON success message.

DELETE /_searchguard/api/roles/sg_human_resources_trainee

{
  "status":"OK",
  "message":"role sg_human_resources_trainee deleted."
}

PUT

PUT /_searchguard/api/roles/{rolename}

Replaces or creates the role specified by rolename.

The JSON format resembles the format used in sg_roles.yml:

{  
  "cluster_permissions" : [ "...", "..."],
  "index_permissions" : [
    {
      "index_patterns" : [ "...", "..." ],
      "dls" : "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
      "fls" : [ "...", "..." ],
      "masked_fields" : ["...", "..." ],
      "allowed_actions" : [ "...", "..." ]
    }
  ],
  "tenant_permissions" : [
    {
      "tenant_patterns" : [ "...", "..." ],
      "allowed_actions" : [ "...", "..." ]
    }
  ]    
}

Example:

PUT /_searchguard/api/roles/sg_human_resources_trainee

{  
  "cluster_permissions" : [
    "SGS_CLUSTER_COMPOSITE_OPS_RO"
  ],
  "index_permissions" : [
    {
      "index_patterns" : [
        "humanresources"
      ],
      "dls" : "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
      "fls" : [
        "Designation",
        "FirstName",
        "LastName",
        "Salary"
      ],
      "masked_fields" : [ ],
      "allowed_actions" : [
        "SGS_READ"
      ]
    }
  ],
  "tenant_permissions" : [
    {
      "tenant_patterns" : [
        "human_resources"
      ],
      "allowed_actions" : [
        "SGS_KIBANA_ALL_WRITE"
      ]
    }
  ]    
}

If you’re using DLS in the role definition, make sure to escape the quotes correctly!

If the call is succesful, a JSON structure is returned, indicating whether the role was created or updated.

{
  "status":"OK",
  "message":"role sg_human_resources_trainee created."
}

PATCH

The PATCH endpoint can be used to change individual attributes of a role, or to create, change and delete roles in a bulk call. The PATCH endpoint expects a payload in JSON Patch format. Search Guard supports the complete JSON patch specification.

JSON patch specification: http://jsonpatch.com/

Patch a single role

PATCH /_searchguard/api/roles/{rolename}

Adds, deletes or changes one or more attributes of a role specified by rolename.

PATCH /_searchguard/api/roles/starfleet
[ 
  { 
    "op": "replace", "path": "/index_permissions[0]/fls", "value": ["field1"] 
  }, 
  { 
    "op": "remove", "path": "/index_permissions[0]/dls" 
  }   
]

Bulk add, delete and change users

PATCH /_searchguard/api/roles
[ 
  { 
    "op": "add", "path": "/klingons",  "value": { "index_permissions": [...] } 
  },
  { 
    "op": "add", "path": "/romulans",  "value": { "index_permissions": [...] }
  }
]

Example: Modify an existing object or array

PATCH /_searchguard/api/roles
[
  {
    "op": "add", "path": "/index_permissions/0", "value": "testrole2" 
  },
  {
    "op": "add", "path": "/index_permissions/-", "value": "testrole3"
  },
]

The operation inserts the value into an array. The value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.

PATCH /_searchguard/api/internalusers/spock
[
  {
    "op": "remove", "path": "/index_permissions/0"
  }
]

The operation removes the element 0 of the array (or just removes the "0" key if index_permissions is an object)

For more examples, please refer to JSON patch format documentation.

---

---

Not what you were looking for? Try the search.