Mapping Users and Groups to Roles

If you authenticate users with the native or file realms, you can manage role assignment user the User Management APIs or the 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:

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.

The available roles are either added using the Role Management APIs or defined in the 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".

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.

monitoring: 
  - "cn=admins,dc=example,dc=com" 
user:
  - "cn=John Doe,cn=contractors,dc=example,dc=com" 
  - "cn=users,dc=example,dc=com"
  - "cn=admins,dc=example,dc=com"

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

monitoring:
  - "cn=Admin,ou=example,o=com"
user:
  - "cn=John Doe,ou=example,o=com"