Mapping users and groups to roles
editMapping users and groups to roles
editIf you authenticate users with the native
or file
realms, you can manage
role assignment by using the User Management APIs or
the 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.
X-Pack security allows role-mappings to be defined via an API, or managed through files. These two sources of role-mapping are combined inside of X-Pack 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 role management APIs or defined in the 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).
Using the role mapping API
editYou can define role-mappings through the add role mapping API.
Using role mapping files
editTo 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
Active Directory,
LDAP, and
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, X-Pack 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
editActive Directory and LDAP realms
editTo 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"
.
X-Pack 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.
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"
The name of a X-Pack security role. |
|
The distinguished name of an LDAP group or an Active Directory security group. |
|
The distinguished name of an LDAP or Active Directory user. |
You can use the role-mapping API to define equivalent mappings as follows:
PUT _xpack/security/role_mapping/admins { "roles" : [ "monitoring", "user" ], "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } }, "enabled": true }
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 }
PKI realms
editPKI 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:
monitoring: - "cn=Admin,ou=example,o=com" user: - "cn=John Doe,ou=example,o=com"
The following example creates equivalent mappings using the API:
PUT _xpack/security/role_mapping/admin_user { "roles" : [ "monitoring" ], "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } }, "enabled": true }
PUT _xpack/security/role_mapping/basic_user { "roles" : [ "user" ], "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } }, "enabled": true }