REST API

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

Authenticate API

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

Clear Cache API

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.

Users API

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.

Note

As of 2.3.0, this API and the native realm are the preferred way to manage users. These operations were previously performed through the esusers command line tool. The file realm (formerly called esusers) is still supported and now functions as a fallback/recovery realm. For example, if all users lock themselves out of the system (no one remembers their username and password), you can define an admin user in the file realm and use those credentials to restore access.

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

Table 27. User Fields

Name

Required

Description

password

yes

The user’s password. Passwords must be at least 6 characters long.

roles

yes

A set of roles the user has. The roles determine the user’s access privileges

full_name

no

The full name of the user

email

no

The email of the user

metadata

no

Arbitrary metadata that you want to associate with the user.


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

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

When an existing user is updated, created is set to false.

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

If the user is not defined in the native realm, found is set to false.

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
}

Roles API

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.

Note

The Roles API is now the preferred way to manage roles. These operations were previously performed through the esusers command line tool and managed in files on each node.

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

When an existing role is updated, created is set to false.

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

If the role is not defined in the native realm, found is set to false.

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
}