OpenSearch/docs/en/rest-api/security/role-mapping.asciidoc

130 lines
3.5 KiB
Plaintext
Raw Normal View History

[role="xpack"]
[[security-api-role-mapping]]
=== Role Mapping APIs
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.
NOTE: 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.
[[security-api-put-role-mapping]]
To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
endpoint:
[source,js]
--------------------------------------------------
POST /_xpack/security/role_mapping/administrators
{
"roles": [ "user", "admin" ],
"enabled": true, <1>
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
},
"metadata" : { <2>
"version" : 1
}
}
--------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` will be ignored when role-mapping
is performed.
<2> 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.
[source,js]
--------------------------------------------------
{
"role_mapping" : {
"created" : true <1>
}
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing mapping is updated, `created` is set to false.
[[security-api-get-role-mapping]]
To retrieve a role-mapping, issue a GET request to the
`/_xpack/security/role_mapping/<name>` endpoint:
[source,js]
--------------------------------------------------
GET /_xpack/security/role_mapping/administrators
--------------------------------------------------
// CONSOLE
// TEST[continued]
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`.
[source,js]
--------------------------------------------------
{
"administrators" : {
"enabled" : true,
"roles" : [
"user",
"admin"
],
"rules" : {
"field" : {
"username" : [
"esadmin01",
"esadmin02"
]
}
},
"metadata" : {
"version" : 1
}
}
}
--------------------------------------------------
// TESTRESPONSE
You can specify multiple mapping names as a comma-separated list.
To retrieve all mappings, omit the name entirely.
[source,js]
--------------------------------------------------
# Retrieve mappings "m1", "m2", and "administrators"
GET /_xpack/security/role_mapping/m1,m2,administrators
# Retrieve all mappings
GET /_xpack/security/role_mapping
--------------------------------------------------
// CONSOLE
// TEST[continued]
[[security-api-delete-role-mapping]]
To delete a role-mapping, submit a DELETE request to the
`/_xpack/security/role_mapping/<name>` endpoint:
[source,js]
--------------------------------------------------
DELETE /_xpack/security/role_mapping/administrators
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the mapping is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.
[source,js]
--------------------------------------------------
{
"found" : true
}
--------------------------------------------------
// TESTRESPONSE