REST API

The Info API returns basic information about the Shield installation.

To get Shield info, submit a GET request to the _shield endpoint:

GET _shield

A successful call returns a JSON structure that contains information such as the plugin version and status:

{
  "status": "enabled",
  "name": "Golden Archer",
  "cluster_name": "elasticsearch",
  "version": {
    "number": "2.2.0",
    "build_hash": "1f974b97ad2a18ed1999edb78575ad73e564ce57",
    "build_timestamp": "2016-01-06T22:39:20Z",
    "build_snapshot": false
  },
  "tagline": "You Know, for Security"
}

The Authenticate API enables you to submit a request with a basic auth header to authenticate a user and retrieve information about the authenticated user. Returns a 401 status code if the user cannot be authenticated.

To authenticate a user, submit a GET request to the _shield/authenticate endpoint:

GET _shield/authenticate

A successful call returns a JSON structure that shows what roles are assigned to the user.

{
  "username": "rdeniro",
  "roles": [
    "admin",
    "kibana4"
  ]
}

The Clear Cache API evicts users from the user cache. You can completely clear the cache or evict specific users.

For example, to evict all users cached by the default file realm:

POST _shield/realm/default_file/_clear_cache

To evict selected users, specify the usernames parameter:

POST _shield/realm/default_file/_clear_cache?usernames=rdeniro,alpacino

To clear the caches for multiple realms, specify the realms as a comma-delimited list:

POST _shield/realm/default_file,ldap1/_clear_cache

For more information, see Controlling the User Cache.

The Users API enables you to create, read, update, and delete users from the native realm. These users are commonly referred to as native users. To use this API, you must have at least the manage_security cluster privilege.

To add a user, submit a PUT or POST request to the /_shield/user/<username> endpoint. A username must be at least 1 character and no longer than 30 characters. The first character must be a letter (a-z or A-Z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9), or any of the following symbols @, -, . or $

POST /_shield/user/ironman
{
  "password" : "j@rV1s",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Tony Stark",
  "email" : "tony@starkcorp.co",
  "metadata" : {
    "intelligence" : 7
  }
}

A successful call returns a JSON structure that shows whether the user has been created or updated.

{
  "user": {
    "created" : true 
  }
}

Once you add a user through the Users API, requests from that user can be authenticated.

curl -u eustace:secret-password http://localhost:9200/_cluster/health

To retrieve a native user, submit a GET request to the /_shield/user/<username> endpoint:

GET /_shield/user/ironman

A successful call returns an array of users with the JSON representation of the user. Note that user passwords are not included.

{
  "found" : true, 
  "users" : [
    {
      "username" : "ironman",
      "roles" : [ "admin", "other_role1" ],
      "full_name" : "Tony Stark",
      "email" : "tony@starkcorp.co",
        "metadata" : {
          "intelligence" : 7
        }
      }
    }
  ]
}

You can specify multiple usernames as a comma-separated list:

GET /_shield/user/ironman,hulk

or omit the username all together to retrieve all users:

GET /_shield/user

To delete a user, submit a DELETE request to the /_shield/user/<username> endpoint:

DELETE /_shield/user/ironman

If the user is successfully deleted, the request returns {"found": true}. Otherwise, found is set to false.

{
  "found" : true
}

The Roles API enables you to add, remove, and retrieve roles in the native Shield realm. To use this API, you must have at least the manage_security cluster privilege.

To add a role, submit a PUT or POST request to the /_shield/role/<rolename> endpoint:

POST /_shield/role/my_admin_role
{
  "cluster": ["all"],
  "indices": [
    {
      "names": [ "index1", "index2" ],
      "privileges": ["all"],
      "fields": [ "title", "body" ], // optional
      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
    }
  ],
  "run_as": [ "other_user" ] // optional
}

When specifying indices privileges, the names and privileges fields are required. Specifying the fields and query fields to configure field and document level security is optional.

A successful call returns a JSON structure that shows whether the role has been created or updated.

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

To retrieve a role from the native Shield realm, issue a GET request to the /_shield/role/<rolename> endpoint:

GET /_shield/role/my_admin_role

A successful call returns an array of roles with the JSON representation of the role.

{
  "found" : true, 
  "roles" : [ {
    "name" : "my_admin_role",
    "cluster" : [ "all" ],
    "indices" : [ {
      "names" : [ "index1", "index2" ],
      "privileges" : [ "all" ],
      "fields" : [ "title", "body" ],
      "query" : "{\"match\": {\"title\": \"foo\"}}"
    } ],
    "run_as" : [ "other_user" ]
  } ]
}

You can specify multiple roles as a comma-separated list. To retrieve all roles, omit the role name.

// Retrieve roles "r1", "r2", and "other_role"
GET /_shield/role/r1,r2,other_role

// Retrieve all roles
GET /_shield/role

To delete a role, submit a DELETE request to the /_shield/role/<rolename> endpoint:

DELETE /_shield/role/my_admin_role

If the role is successfully deleted, the request returns {"found": true}. Otherwise, found is set to false.

{
  "found" : true
}