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

If you authenticate users with an `esusers` realm, you can assign roles when you 
<<esusers-add,add a user>> and use the <<esusers-roles,`roles`>> command to add or remove roles. 

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/shield/users/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 `role_mapping` settings in `elasticsearch.yml`. 
The `role_mapping` settings enable you to use a different set of mappings for each realm type: 

 `shield.authc.ldap.files.role_mapping` :: The location of the role mappings for LDAP realms.
 `shield.authc.active_directory.files.role_mapping` :: The location of the role mappings for Active Directory realms.
 `shield.authc.pki.files.role_mapping` :: The location of the role mappings for PKI realms.

IMPORTANT: For Shield to read the mapping file, it must be stored in the Elasticsearch `CONF_DIR`. 

Within the role mapping file, Shield 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 defined in the <<defining-roles, 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: Shield 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   
`John Doe`, 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 Shield role defined in the <<defining-roles, roles file>>.
<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. added[1.1.0]

[[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"
------------------------------------------------------------