Quick links
Overview and background
Elasticsearch uses a role-based security model. In the default native Elasticsearch security realm, roles are linked to users by the user management API. However, when using single sign-on (SSO) methods, we need an alternative way of determining which Elasticsearch role should be used for an incoming user request.
That’s where role mapping and user mapping come in. The terms refer to the process that links users and roles from an external security system (e.g., a single sign-on system) to Elasticsearch users and roles.
Note: if you are using the default native Elasticsearch realm, this article is not for you. But if you are not, read on to discover how role and user mapping can be implemented in Elasticsearch.
How to implement role and user mapping
In order for a role to be mapped, it must already exist in the Elasticsearch cluster. The process for creating a role is described here.
How users are linked to roles depends upon the type of authorization realm that you are using in Elasticsearch as shown in the following table:
Role mapping API and role mapping files are described in more detail below.
Role mapping API
The create role mapping API allows you to define role mappings. To use the role mapping API, you must have at least the “manage_security” cluster privilege. If you have that, you can create or update role mappings using the following requests:
Direct mapping of users to roles
POST /_security/role_mapping/my-admin-map
{
"roles": [ "read_all", "admin" ],
"enabled": true,
"rules": {
"field" : { "username" : [ "admin01", "admin02" ] }
}
}The above call creates a direct role mapping called “my-admin-map”, which assigns users with the usernames “admin01” and “admin02” to two different roles called “read_all” and “admin”. Note that the usernames will have been created in the external realm, but the roles “read_all” and “admin” have to have been created in Elasticsearch.
Mapping of users to roles via attributes or groups
We can use a list of rules on attributes or other fields from the external system to map a given role. For example:
POST /_security/role_mapping/my-admin-map2
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"any": [
{
"field": {
"username": "admin*"
}
},
{
"field": {
"groups": "cn=admins,dc=mysite,dc=com"
}
}
]
}
}The above command sets two alternative conditions that govern the allocation of the superuser role, which must already exist in Elasticsearch. The role is assigned to any external user who satisfies either of the two following conditions: either the user has a `username` that starts with the prefix `admin` (e.g., `admin01`, `admin_john`, etc.) or is part of the group `cn=admins,dc=mysite,dc=com`.
Special values
For role mapping field rules, we can use any of the following:
- a simple string
- a wildcard string (*)
- a regular expression (delimited by slashes) /.*-admin[0-9]*/
- any number
- null (which will match a null or missing value)
- an array (a list of values that will be tested in turn, and any can match)
All, any, and except operators
By using the “all”, “any”, and “except” rule types, you can construct more complex conditions:
POST /_security/role_mapping/my-admin-map-3
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"all": [
{
"any": [
{
"field": {
"dn": "*,ou=admin,dc=example,dc=com"
}
},
{
"field": {
"username": [ "admin1", "super*" ]
}
}
]
},
{
"except": {
"field": {
"metadata.terminated_date": null
}
}
}
]
}
}Note that the above rule consists of an “all” block that nests an “any” block along with an “except” block. The `superuser` role will be assigned to users who satisfy all conditions in the “all” block.
The “any” block provides two sub-rules:
- Either username = admin1 OR super* (note the use of a wildcard)
- Or the distinguished name (i.e., `dn`) = is “*,ou=admin,dc=example,dc=com”
The “except” block will only consider users who have a null value for “metadata.terminated_date”, i.e., users who are still active.
Although it is possible to create complex structures using the API, it is recommended to design an architecture that keeps security role mapping as simple as possible.
Mapping users to roles using templating
POST /_security/role_mapping/my-admin-map3
{
"role_templates": [
{
"template": { "source": "{{#tojson}}groups{{/tojson}}" },
"format" : "json"
}
],
"rules": {
"field" : { "realm.name" : "saml" }
},
"enabled": true
}Sometimes, it may happen that the group names of your external users map exactly to your role names in Elasticsearch. When that’s the case, you can simply use the group names as role names by leveraging role templates written in the Mustache templating language.
In the example above, all external users in the `saml` realm will be mapped to the roles whose names are the same as their group names.
There are many other ways to map external users to role names using the create role mapping API. Check out the official documentation to discover all the options for mapping your external users to your Elasticsearch roles.
Role mapping files
Role mapping files can only be used in the ActiveDirectory, PKI, and LDAP realms.
In general, the preferred method for mapping users to roles is by leveraging the role mapping API explained above. However, in certain cases, it may be useful to use a role mapping file. For example, if an administrator uses an external SSO but you want that user to have access even when the cluster is RED to enable them to perform administrative actions. File-based role mapping is also useful when you only want specific administrator users who can access the physical nodes to be able to perform modifications on role mappings.
Role mapping files must be put onto every node in the Elasticsearch cluster. Modifications in those files will be detected by default every five seconds (no restart required).
Key notes on role mapping files
- The file must be located at ES_PATH_CONF/role_mapping.yml (in most distributions that is /etc/elasticsearch/role_mapping.yml).
- The file consists of keys and values where each key is an Elasticsearch role and each value is a user or a group that has that role. Note that the values are defined as distinguished names (DNs), which can represent users or groups.
- Any roles that are mapped via role mapping files CANNOT be changed or updated using the role mapping API.
my-admin-role: - "cn=admins,dc=example,dc=com" read-only-role: - "cn=John Smith,cn=external,dc=example,dc=com" - "cn=users,dc=example,dc=com" - "cn=admins,dc=example,dc=com"
The above file allocates the “my-admin-role” and “read-only-role” to any administrator users in the group “cn=admins,dc=example,dc=com”.
It also allocates the “read-only-role” to one specific external user (i.e., John Smith) and another group (i.e., “cn=users,dc=example,dc=com”) representing all users of the example.com organization.
Conclusion
Role and user mapping is the process that links users from an external system to roles in Elasticsearch. Although it can be done automatically by the user management API, when you are not using the default native Elasticsearch security realm, you will have to define the rules for mapping yourself.
That can be achieved by mapping users to roles by attributes or groups or by templating. Another option is to use a role mapping file. We have explained the procedures for implementing the various options alongside the factors that need to be considered during implementation.
