[role="xpack"] [[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 <> 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. You can define role-mappings via an <> or manage them through <>. These two sources of role-mapping are combined inside of the {es} {security-features}, 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.html#security-role-apis[role management APIs] or defined in the <>. 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). NOTE: The PKI, LDAP, Kerberos and SAML realms support using <> as an alternative to role mapping. NOTE: When <> is enabled, the roles of the anonymous user are assigned to all the other users as well. NOTE: Users with no roles assigned will be unauthorized for any action. [[mapping-roles-api]] ==== Using the role mapping API You can define role-mappings through the {ref}/security-api-put-role-mapping.html[add 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/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` setting in the {ref}/security-settings.html#ref-ad-settings[Active Directory], {ref}/security-settings.html#ref-ldap-settings[LDAP], and {ref}/security-settings.html#ref-pki-settings[PKI] realm settings in `elasticsearch.yml`. 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, {es} 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. While the _role mapping APIs_ is the preferred way to manage role mappings, using the `role_mappings.yml` file becomes useful in a couple of use cases: . If you want to define fixed role mappings that no one (besides an administrator with physical access to the {es} nodes) would be able to change. . If cluster administration depends on users from external realms and these users need to have their roles mapped to them even when the cluster is RED. For instance an administrator that authenticates via LDAP or PKI and gets assigned an administrator role so that they can perform corrective actions. Please note however, that the role_mappings.yml file is provided as a minimal administrative function and is not intended to cover and be used to define roles for all use cases. IMPORTANT: You cannot view, edit, or remove any roles that are defined in the role mapping files by using the the role mapping APIs. ==== 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: The {es} {security-features} support only 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 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,console] -------------------------------------------------- PUT /_security/role_mapping/admins { "roles" : [ "monitoring", "user" ], "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } }, "enabled": true } -------------------------------------------------- [source,console] -------------------------------------------------- PUT /_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 } -------------------------------------------------- [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,console] -------------------------------------------------- PUT /_security/role_mapping/admin_user { "roles" : [ "monitoring" ], "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } }, "enabled": true } -------------------------------------------------- [source,console] -------------------------------------------------- PUT /_security/role_mapping/basic_user { "roles" : [ "user" ], "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } }, "enabled": true } --------------------------------------------------