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

If you authenticate users with the `native` or `file` realms, you can manage
role assignment user the <<managing-native-users, User Management APIs>> or the
<<managing-file-users, file-realm>> command-line tool respectively.

For other types of realms, you configure role mappings for users and groups 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 `CONF_DIR/x-pack/role_mapping.yml`, where
`CONF_DIR` 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 enable
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.

[[ad-role-mapping]]
The available roles are either added using the <<roles-management-api, Role Management APIs>>
or defined in the <<roles-management-file, roles file>>. 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.

[[ldap-role-mapping]]
For example, the following snippet maps the `admins` group to the `monitoring`
role and maps 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.

[[pki-role-mapping]]
PKI realms only support mapping users to roles, as there is no notion of a group
in PKI. For example:

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