179 lines
6.8 KiB
Plaintext
179 lines
6.8 KiB
Plaintext
[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 <<managing-native-users, User Management APIs>> 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
|
|
<<mapping-roles-api, API>> or manage them through <<mapping-roles-file, files>>.
|
|
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
|
|
<<roles-management-file, 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).
|
|
|
|
NOTE: The PKI, LDAP, Kerberos and SAML realms support using
|
|
<<authorization_realms, authorization realms>> as an alternative to role mapping.
|
|
|
|
NOTE: When <<anonymous-access, anonymous access>> 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
|
|
}
|
|
--------------------------------------------------
|