WARNING: Version 5.6 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
The Role Mapping API enables you to add, remove, and retrieve role-mappings.
To use this API, you must have at least the manage_security cluster privilege.
The API requires that each role-mapping have a distinct name. The name is used solely as an identifier to facilitate interaction via the API, and does not affect the behavior of the mapping in any way.
To add a role-mapping, submit a PUT or POST request to the /_xpack/security/role_mapping/<name>
endpoint:
POST /_xpack/security/role_mapping/administrators
{
"roles": [ "user", "admin" ],
"enabled": true,
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
},
"metadata" : {
"version" : 1
}
}
|
Mappings that have |
|
|
Metadata is optional |
The roles, enabled, and rules fields are required at the top-level.
Within the metadata object, keys beginning with _ are reserved for system
usage.
A successful call returns a JSON structure that shows whether the mapping has been created or updated.
To retrieve a role-mapping, issue a GET request to the
/_xpack/security/role_mapping/<name> endpoint:
GET /_xpack/security/role_mapping/administrators
A successful call an object, where the keys are the
names of the request mappings, and the values are
the JSON representation of those mappings.
If there is no mapping with the requested name, the
response will have status code 404.
{
"administrators" : {
"enabled" : true,
"roles" : [
"user",
"admin"
],
"rules" : {
"field" : {
"username" : [
"esadmin01",
"esadmin02"
]
}
},
"metadata" : {
"version" : 1
}
}
}
You can specify multiple mapping names as a comma-separated list. To retrieve all mappings, omit the name entirely.
# Retrieve mappings "m1", "m2", and "administrators" GET /_xpack/security/role_mapping/m1,m2,administrators # Retrieve all mappings GET /_xpack/security/role_mapping
To delete a role-mapping, submit a DELETE request to the
/_xpack/security/role_mapping/<name> endpoint:
DELETE /_xpack/security/role_mapping/administrators
If the mapping is successfully deleted, the request returns {"found": true}.
Otherwise, found is set to false.
{
"found" : true
}