This provides a set of APIs to create, update, remove, and retrieve roles from the native realm.

The list of available APIs under this section, as well as information on what they do, is as follows:

GET /_xpack/security/role                               -- To retrieve the list of all roles 
GET /_xpack/security/role/<rolename>                        -- To retrieve details of a specific role
POST /_xpack/security/role/<rolename>/_clear_cache          -- To evict/clear roles from the native role cache
POST /_xpack/security/role/<rolename>                       -- To create a role
PUT /_xpack/security/role/<rolename>                        -- To update an existing role

The rolename in the path parameter specifies the role against which the operation is carried out. The body of the request accepts parameters such as cluster, which accepts a list of cluster privileges; indices, which accepts a list of objects that specify the indices privileges and run_as, which contains a list of users that the owners of this role can impersonate.

indices contains an object with parameters such as names, which accepts a list of index names; field_security, which accepts a list of fields to provide read access; privileges, which accepts a list of index privileges; and the query parameter, which accepts the query to filter the documents.

Let's take a look at a few examples of managing different roles using APIs:

• Example 1: Create a new role with field-level security imposed on the employee index:

curl -u elastic:elastic -X POST http://localhost:9200/_xpack/security/role/employee_read_new -H 'content-type: application/json' -d '{
 
  "indices": [
    {
      "names": [ "employee" ],
      "privileges": [ "read" ],
      "field_security" : {
        "grant" : [ "*" ],
        "except": [ "address*","salary" ]
      }
     
    }
  ]
}'

Response:
role":{"created":true}}

• Example 2: Get the details of a specific role:

curl -u elastic:elastic -XGET http://localhost:9200/_xpack/security/role/employee_read_new?pretty
Response:
{
  "employee_read" : {
    "cluster" : [ ],
    "indices" : [
      {
        "names" : [
          "employee"
        ],
        "privileges" : [
          "read"
        ],
        "field_security" : {
          "grant" : [
            "*"
          ],
          "except" : [
            "address*",
            "salary"
          ]
        }
      }
    ],
    "run_as" : [ ],
    "metadata" : { },
    "transient_metadata" : {
      "enabled" : true
    }
  }
}

• Example 3: Delete a role:

curl -u elastic:elastic -XDELETE http://localhost:9200/_xpack/security/role/employee_read

Response:
{"found":true}