REST API
editREST API
editInfo API
editThe 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
editThe 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
editThe 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
editThe 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.
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 28. User Fields
Name |
Required |
Description |
|
yes |
The user’s password. Passwords must be at least 6 characters long. |
|
yes |
A set of roles the user has. The roles determine the user’s access privileges |
|
no |
The full name of the user |
|
no |
The email of the user |
|
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.
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 }
Roles API
editThe 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.
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.
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 }