Version: 6.x-23
Enterprise

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_role_starfleet
{
  "sg_role_starfleet" : {
    "indices" : {
      "pub*" : {
        "*" : [ "READ" ]
        "_dls_": "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"  }}}}",
        "_fls_": [
          "Designation",
          "FirstName",
          "LastName",
          "Salary"
        ]
      }
    }
  }
}

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_role_starfleet
{
  "status":"OK",
  "message":"role sg_role_starfleet deleted."
}

PUT

PUT /_searchguard/api/roles/{rolename}

Replaces or creates the role specified by rolename .

PUT /_searchguard/api/rolesmapping/sg_role_starfleet
{
  "cluster" : [ "*" ],
  "indices" : {
    "pub*" : {
      "*" : [ "READ" ],
      _dls_: "{ \"bool\": { \"must_not\": { \"match\": { \"Designation\": \"CEO\"}}}}"
      _fls_: ["field1", "field2"]
    },
    "tenants": {
      tenant1: RW,
      tenant2: RO
    }    
  }  
}

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

{
  "cluster" : [ "<cluster permission>", "<cluster permission>", ... ],
  "indices" : {
    "<indexname>" : {
      "<typename>" : [ "<index/type permission>", "<index/type permission>", ... ],
      "_dls_": "<DLS query>"
      "_fls_": ["field", "field"]
    },
    "<indexname>" : {
      "<typename>" : [ "<index/type permission>", "<index/type permission>", ... ],
    },
    "tenants": {
      <tenantname> : <RW | RO>,
      <tenantname> : <RW | RO>,
      ...
    }    
  }
}

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_role_starfleet created."
}

PATCH

The PATCH endpoint can be used to change individual attributes of a rolw, 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/

The PATCH endpoint is only available for Elasticsearch 6.4.0 and above.

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": "/indices/public/_fls_", "value": ["field1"] 
  }, 
  { 
    "op": "remove", "path": "/indices/public/_dls_" 
  }   
]

Bulk add, delete and change users

PATCH /_searchguard/api/roles
[ 
  { 
    "op": "add", "path": "/klingons",  "value": { "indices" : { "klingonindex" : { "*" : [ "READ" ] }  } } 
  },
  { 
    "op": "add", "path": "/romulans",  "value": { "indices" : { "romulansindex" : { "*" : [ "READ" ] }  } } 
  }
]

Not what you were looking for? Try the search.