WARNING: Version 6.1 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.
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>
Role mappings have rules that identify users and a list of roles that are granted to those users.
This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using Role Management APIs or 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 |
---|---|---|
|
An array of rules |
If any of its children are true, it
evaluates to |
|
An array of rules |
If all of its children are true, it
evaluates to |
|
An object |
See The Field Rule |
|
A single rule as an object |
Only valid as a child of an |
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:
Type | Description | Example |
---|---|---|
Simple String |
Exactly matches the provided value. |
|
Wildcard String |
Matches the provided value using a wildcard. |
|
Regular Expression |
Matches the provided value using a Lucene regexp. |
|
Number |
Matches an equivalent numerical value. |
|
Null |
Matches a null or missing value. |
|
Array |
Tests each element in the array in accordance with the above definitions. If any of elements match, the match is successful. |
|
The user object against which rules are evaluated has the following fields:
Name | Type | Description | Example |
---|---|---|---|
username |
string |
The username by which X-Pack security knows this user. |
|
dn |
string |
The Distinguished Name of the user. |
|
groups |
array-of-string |
The groups to which the user belongs. |
|
metadata |
object |
Additional metadata for the user. |
|
realm |
object |
The realm that authenticated the user. The only field in this object is the realm name. |
|
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:
{ "field" : { "groups" : "admin" } }
For additional realm-specific details, see Mapping Users and Groups to Roles.
-
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.
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 tofalse
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.
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:
POST /_xpack/security/role_mapping/mapping1 { "roles": [ "user"], "enabled": true, "rules": { "field" : { "username" : "*" } }, "metadata" : { "version" : 1 } }
Mappings that have |
|
Metadata is optional. |
A successful call returns a JSON structure that shows whether the mapping has been created or updated.
The following example assigns the "user" and "admin" roles to specific users:
POST /_xpack/security/role_mapping/mapping2 { "roles": [ "user", "admin" ], "enabled": true, "rules": { "field" : { "username" : [ "esadmin01", "esadmin02" ] } } }
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:
POST /_xpack/security/role_mapping/mapping3 { "roles": [ "superuser" ], "enabled": true, "rules": { "any": [ { "field": { "username": "esadmin" } }, { "field": { "groups": "cn=admins,dc=example,dc=com" } } ] } }
The following example matches users who authenticated against a specific realm:
POST /_xpack/security/role_mapping/mapping4 { "roles": [ "ldap-user" ], "enabled": true, "rules": { "field" : { "realm.name" : "ldap1" } } }
The following example matches users within a specific LDAP sub-tree:
POST /_xpack/security/role_mapping/mapping5 { "roles": [ "example-user" ], "enabled": true, "rules": { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } } }
The following example matches users within a particular LDAP sub-tree in a specific realm:
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" } } ] } }
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 ises-admin
, or the username ises-system
-
the user in in the
cn=people,dc=example,dc=com
group -
the user does not have a
terminated_date
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 } } } ] } }
To retrieve a role mapping, issue a GET request to the
/_xpack/security/role_mapping/<name>
endpoint:
GET /_xpack/security/role_mapping/mapping7
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
.
{ "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": {} } }
You can specify multiple mapping names as a comma-separated list. To retrieve all mappings, omit the name entirely.
To delete a role mapping, submit a DELETE request to the
/_xpack/security/role_mapping/<name>
endpoint:
DELETE /_xpack/security/role_mapping/mapping1
If the mapping is successfully deleted, the request returns {"found": true}
.
Otherwise, found
is set to false.
{ "found" : true }