[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/` + `DELETE /_xpack/security/role_mapping/` + `POST /_xpack/security/role_mapping/` + `PUT /_xpack/security/role_mapping/` ==== 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 <> 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 <> | `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/` 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/` 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/` 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