405 lines
12 KiB
Plaintext
405 lines
12 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-role-mapping]]
|
|
=== Role Mapping APIs
|
|
|
|
The Role Mapping API enables you to add, remove, and retrieve role mappings.
|
|
|
|
==== Request
|
|
|
|
`GET /_xpack/security/role_mapping` +
|
|
|
|
`GET /_xpack/security/role_mapping/<name>` +
|
|
|
|
`DELETE /_xpack/security/role_mapping/<name>` +
|
|
|
|
`POST /_xpack/security/role_mapping/<name>` +
|
|
|
|
`PUT /_xpack/security/role_mapping/<name>`
|
|
|
|
==== Description
|
|
|
|
Role mappings have _rules_ that identify users and a list of _roles_ that are
|
|
granted to those users.
|
|
|
|
NOTE: This API does not create roles. Rather, it maps users to existing roles.
|
|
Roles can be created by using <<security-api-roles, Role Management APIs>> or
|
|
{xpack-ref}/defining-roles.html#roles-management-file[roles files].
|
|
|
|
The role mapping rule is a logical condition that is expressed using a JSON DSL.
|
|
The DSL supports the following rule types:
|
|
|
|
|=======================
|
|
| Type | Value Type (child) | Description
|
|
|
|
| `any` | An array of rules | If *any* of its children are true, it
|
|
evaluates to `true`.
|
|
| `all` | An array of rules | If *all* of its children are true, it
|
|
evaluates to `true`.
|
|
| `field` | An object | See <<mapping-roles-rule-field>>
|
|
| `except` | A single rule as an object | Only valid as a child of an `all`
|
|
rule. If its child is `false`, the
|
|
`except` is `true`.
|
|
|=======================
|
|
|
|
[float]
|
|
[[mapping-roles-rule-field]]
|
|
===== The Field Rule
|
|
|
|
The `field` rule is the primary building block for a role-mapping expression.
|
|
It takes a single object as its value and that object must contain a single
|
|
member with key _F_ and value _V_. The field rule looks up the value of _F_
|
|
within the user object and then tests whether the user value _matches_ the
|
|
provided value _V_.
|
|
|
|
The value specified in the field rule can be one of the following types:
|
|
[cols="2,5,3m"]
|
|
|=======================
|
|
| Type | Description | Example
|
|
|
|
| Simple String | Exactly matches the provided value. | "esadmin"
|
|
| Wildcard String | Matches the provided value using a wildcard. | "*,dc=example,dc=com"
|
|
| Regular Expression | Matches the provided value using a
|
|
{ref}/query-dsl-regexp-query.html#regexp-syntax[Lucene regexp]. | "/.\*-admin[0-9]*/"
|
|
| Number | Matches an equivalent numerical value. | 7
|
|
| Null | Matches a null or missing value. | null
|
|
| Array | Tests each element in the array in
|
|
accordance with the above definitions.
|
|
If _any_ of elements match, the match is successful. | ["admin", "operator"]
|
|
|=======================
|
|
|
|
===== User Fields
|
|
|
|
The _user object_ against which rules are evaluated has the following fields:
|
|
[cols="1s,,,m"]
|
|
|=======================
|
|
| Name | Type | Description | Example
|
|
|
|
| username | string | The username by which {security} knows this user. | `"username": "jsmith"`
|
|
| dn | string | The _Distinguished Name_ of the user. | `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`
|
|
| groups | array-of-string | The groups to which the user belongs. | `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com",
|
|
"cn=esusers,ou=groups,dc=example,dc=com ]`
|
|
| metadata | object | Additional metadata for the user. | `"metadata": { "cn": "John Smith" }`
|
|
| realm | object | The realm that authenticated the user. The only field in this object is the realm name. | `"realm": { "name": "ldap1" }`
|
|
|=======================
|
|
|
|
The `groups` field is multi-valued; a user can belong to many groups. When a
|
|
`field` rule is applied against a multi-valued field, it is considered to match
|
|
if _at least one_ of the member values matches. For example, the following rule
|
|
matches any user who is a member of the `admin` group, regardless of any
|
|
other groups they belong to:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
{ "field" : { "groups" : "admin" } }
|
|
------------------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
For additional realm-specific details, see
|
|
{xpack-ref}/mapping-roles.html#ldap-role-mapping[Mapping Users and Groups to Roles].
|
|
|
|
|
|
==== Path Parameters
|
|
|
|
`name`::
|
|
(string) The distinct name that identifies the role mapping. The name is
|
|
used solely as an identifier to facilitate interaction via the API; it does
|
|
not affect the behavior of the mapping in any way. If you do not specify this
|
|
parameter for the Get Role Mappings API, it returns information about all
|
|
role mappings.
|
|
|
|
|
|
==== Request Body
|
|
|
|
The following parameters can be specified in the body of a PUT or POST request
|
|
and pertain to adding a role mapping:
|
|
|
|
`enabled` (required)::
|
|
(boolean) Mappings that have `enabled` set to `false` are ignored when role
|
|
mapping is performed.
|
|
|
|
`metadata`::
|
|
(object) Additional metadata that helps define which roles are assigned to each
|
|
user. Within the `metadata` object, keys beginning with `_` are reserved for
|
|
system usage.
|
|
|
|
`roles` (required)::
|
|
(list) A list of roles that are granted to the users that match the role-mapping
|
|
rules.
|
|
|
|
`rules` (required)::
|
|
(object) The rules that determine which users should be matched by the mapping.
|
|
A rule is a logical condition that is expressed by using a JSON DSL.
|
|
|
|
|
|
==== Authorization
|
|
|
|
To use this API, you must have at least the `manage_security` cluster privilege.
|
|
|
|
|
|
==== Examples
|
|
|
|
[[security-api-put-role-mapping]]
|
|
To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>` endpoint. The following example assigns
|
|
the "user" role to all users:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping1
|
|
{
|
|
"roles": [ "user"],
|
|
"enabled": true, <1>
|
|
"rules": {
|
|
"field" : { "username" : "*" }
|
|
},
|
|
"metadata" : { <2>
|
|
"version" : 1
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
|
|
is performed.
|
|
<2> Metadata is optional.
|
|
|
|
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.
|
|
|
|
The following example assigns the "user" and "admin" roles to specific users:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping2
|
|
{
|
|
"roles": [ "user", "admin" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example matches any user where either the username is `esadmin`
|
|
or the user is in the `cn=admin,dc=example,dc=com` group:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping3
|
|
{
|
|
"roles": [ "superuser" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"any": [
|
|
{
|
|
"field": {
|
|
"username": "esadmin"
|
|
}
|
|
},
|
|
{
|
|
"field": {
|
|
"groups": "cn=admins,dc=example,dc=com"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example matches users who authenticated against a specific realm:
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping4
|
|
{
|
|
"roles": [ "ldap-user" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"field" : { "realm.name" : "ldap1" }
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example matches users within a specific LDAP sub-tree:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping5
|
|
{
|
|
"roles": [ "example-user" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example matches users within a particular LDAP sub-tree in a
|
|
specific realm:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping6
|
|
{
|
|
"roles": [ "ldap-example-user" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"all": [
|
|
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
|
|
{ "field" : { "realm.name" : "ldap1" } }
|
|
]
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The rules can be more complex and include wildcard matching. For example, the
|
|
following mapping matches any user where *all* of these conditions are met:
|
|
|
|
- the _Distinguished Name_ matches the pattern `*,ou=admin,dc=example,dc=com`,
|
|
or the username is `es-admin`, or the username is `es-system`
|
|
- the user in in the `cn=people,dc=example,dc=com` group
|
|
- the user does not have a `terminated_date`
|
|
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_xpack/security/role_mapping/mapping7
|
|
{
|
|
"roles": [ "superuser" ],
|
|
"enabled": true,
|
|
"rules": {
|
|
"all": [
|
|
{
|
|
"any": [
|
|
{
|
|
"field": {
|
|
"dn": "*,ou=admin,dc=example,dc=com"
|
|
}
|
|
},
|
|
{
|
|
"field": {
|
|
"username": [ "es-admin", "es-system" ]
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"field": {
|
|
"groups": "cn=people,dc=example,dc=com"
|
|
}
|
|
},
|
|
{
|
|
"except": {
|
|
"field": {
|
|
"metadata.terminated_date": null
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[[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/mapping7
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
A successful call retrieves 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]
|
|
--------------------------------------------------
|
|
{
|
|
"mapping7": {
|
|
"enabled": true,
|
|
"roles": [
|
|
"superuser"
|
|
],
|
|
"rules": {
|
|
"all": [
|
|
{
|
|
"any": [
|
|
{
|
|
"field": {
|
|
"dn": "*,ou=admin,dc=example,dc=com"
|
|
}
|
|
},
|
|
{
|
|
"field": {
|
|
"username": [
|
|
"es-admin",
|
|
"es-system"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"field": {
|
|
"groups": "cn=people,dc=example,dc=com"
|
|
}
|
|
},
|
|
{
|
|
"except": {
|
|
"field": {
|
|
"metadata.terminated_date": null
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"metadata": {}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|
|
|
|
You can specify multiple mapping names as a comma-separated list.
|
|
To retrieve all mappings, omit the name entirely.
|
|
|
|
[[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/mapping1
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:role_mapping]
|
|
|
|
If the mapping is successfully deleted, the request returns `{"found": true}`.
|
|
Otherwise, `found` is set to false.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"found" : true
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE
|