[[mapping-roles]]
=== Mapping Users and Groups to Roles

If you authenticate users with the `native` or `file` realms, you can manage
role assignment by using the <<managing-native-users, User Management APIs>> or
the {ref}/users-command.html[users] command-line tool respectively.

For other types of realms, you must create _role-mappings_ that define which
roles should be assigned to each user based on their username, groups, or
other metadata.

{security} allows role-mappings to be defined via an
<<mapping-roles-api, API>>, or managed through <<mapping-roles-file, files>>.
These two sources of role-mapping are combined inside of {security}, so it is
possible for a single user to have some roles that have been mapped through
the API, and other roles that are mapped through files.

When you use role-mappings, you assign existing roles to users.
The available roles should either be added using the
{ref}/security-api-roles.html[Role Management APIs] or defined in the
<<roles-management-file, roles file>>. Either role-mapping method can use
either role management method. For example, when you use the role mapping API,
you are able to map users to both API-managed roles and file-managed roles
(and likewise for file-based role-mappings).

[[mapping-roles-api]]
==== Using the Role Mapping API

You can define role-mappings through the
{ref}/security-api-role-mapping.html[role mapping API].

[[mapping-roles-file]]
==== Using Role Mapping Files

To use file based role-mappings, you must configure the mappings in a YAML file
and copy it to each node in the cluster. Tools like Puppet or Chef can help with
this.

By default, role mappings are stored in `ES_PATH_CONF/x-pack/role_mapping.yml`,
where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or
`/etc/elasticsearch` (package installations). To specify a different location,
you configure the `files.role_mapping` realm settings in `elasticsearch.yml`.
This setting enables you to use a different set of mappings for each realm type:

|=====
| `xpack.security.authc.ldap.files.role_mapping` | | | The location of the role mappings for LDAP realms.
| `xpack.security.authc.active_directory.files.role_mapping` | | | The location of the role mappings for Active Directory realms.
| `xpack.security.authc.pki.files.role_mapping` | | | The location of the role mappings for PKI realms.
|=====

Within the role mapping file, the security roles are keys and groups and users
are values. The mappings can have a many-to-many relationship. When you map roles
to groups, the roles of a user in that group are the combination of the roles
assigned to that group and the roles assigned to that user.

By default, {security} checks role mapping files for changes every 5 seconds.
You can change this default behavior by changing the
`resource.reload.interval.high` setting in the `elasticsearch.yml` file. Since
this is a common setting in Elasticsearch, changing its value might effect other
schedules in the system.

==== Realm Specific Details
[float]
[[ldap-role-mapping]]
===== Active Directory and LDAP Realms

To specify users and groups in the role mappings, you use their
_Distinguished Names_ (DNs). A DN is a string that uniquely identifies the user
or group, for example `"cn=John Doe,cn=contractors,dc=example,dc=com"`.

NOTE: {security} only supports Active Directory security groups. You cannot map
      distribution groups to roles.

For example, the following snippet uses the file-based method to map the
`admins` group to the `monitoring` role and map the `John Doe` user, the
`users` group, and the `admins` group to the `user` role.

[source, yaml]
------------------------------------------------------------
monitoring: <1>
  - "cn=admins,dc=example,dc=com" <2>
user:
  - "cn=John Doe,cn=contractors,dc=example,dc=com" <3>
  - "cn=users,dc=example,dc=com"
  - "cn=admins,dc=example,dc=com"
------------------------------------------------------------
<1> The name of a {security} role.
<2> The distinguished name of an LDAP group or an Active Directory security group.
<3> The distinguished name of an LDAP or Active Directory user.

You can use the role-mapping API to define equivalent mappings as follows:
[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/admins
{
  "roles" : [ "monitoring", "user" ],
  "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } },
  "enabled": true
}
--------------------------------------------------
// CONSOLE

[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "any" : [
      { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } },
      { "field" : { "groups" : "cn=users,dc=example,dc=com" } }
  ] },
  "enabled": true
}
--------------------------------------------------
// CONSOLE

[float]
[[pki-role-mapping]]
===== PKI Realms

PKI realms support mapping users to roles, but you cannot map groups as
the PKI realm has no notion of a group.

This is an example using a file-based mapping:

[source, yaml]
------------------------------------------------------------
monitoring:
  - "cn=Admin,ou=example,o=com"
user:
  - "cn=John Doe,ou=example,o=com"
------------------------------------------------------------

The following example creates equivalent mappings using the API:

[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/admin_user
{
  "roles" : [ "monitoring" ],
  "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } },
  "enabled": true
}
--------------------------------------------------
// CONSOLE

[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/basic_user
{
  "roles" : [ "user" ],
  "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } },
  "enabled": true
}
--------------------------------------------------
// CONSOLE