Elasticsearch Elasticsearch Role Mapping and User Mapping

Opster Team

Last updated: Feb 14, 2023

| 4 min read

Opster Team

Last updated: Feb 14, 2023

| 4 min read

Quick links

• Overview and background
• How to implement role and user mapping
  • Role mapping API
    • Direct mapping of users to roles
    • Mapping of users to roles via attributes or groups
    • Special values
    • All, any, and except operators
    • Mapping users to roles using templating
  • Role mapping files
    • Key notes on role mapping files
• Conclusion

Overview and background

Elasticsearch uses a role-based security system. In the default native Elasticsearch security realm, roles are linked to users by the user management API. However, when using 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. To create a role, you can read 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 add 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 by 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 mapping called “my-admin-map”.
• It also creates a direct mapping from two 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 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.
• However, in order for those conditions to work, the superuser role must already exist on Elasticsearch.
• Username=“admin*” uses a wildcard, so it would apply to any user whose name starts with “admin”, e.g., “admin1” or “admin_john”. 
• Users with a value of “groups” are set to “cn=admins,dc=mysite,dc=com”.

Special values

For role-mapping rules, we can use:

• strings
• wildcard values (*)
• regular expressions (enclosed in slashes)   /.*-admin[0-9]*/  
• null (which will match a null or missing value)
• array (a list of values that will be tested in turn)

All, any, and except operators

By using the “all”, “any”, and “except” operators 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 except block will exclude any user who has a value for “metadata.terminated_date”.

The any block provides two alternative routes: 

Either username = admin1 OR super1* (note the use of a wildcard)

Or “dn”: “*,ou=admin,dc=example,dc=com”

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
}

The above example does not map the role directly but instead maps any user to whatever role is defined in that user’s field “groups”.  

That approach requires you to create a role in Elasticsearch for all possible values of “groups” that could come from the SAML system.

    ]
  }
    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
  }
}

Role mapping files

Role mapping files can only be used in the ActiveDirectory, PKI, and LDAP realms.

In general, the preferred method for role and user mapping is 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.

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 may represent users or groups.
• Any roles that are mapped via roll mapping files CANNOT be mapped 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 “my-admin-role” to any users in the group “cn=admins,dc=example,dc=com”.

It also allocates the “read-only role” to one specific user and two other groups.

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, for example, mapping users to roles by attributes or groups or by templating. Another option is to use a role mapping file. The procedures for implementing the various options are described above alongside the factors that need to be considered during implementation.