Create or update role mappings API

edit

Create or update role mappings API

edit

Creates and updates role mappings.

Request

edit

POST /_security/role_mapping/<name>

PUT /_security/role_mapping/<name>

Prerequisites

edit
  • To use this API, you must have at least the manage_security cluster privilege.

Description

edit

Role mappings define which roles are assigned to each user. Each mapping has rules that identify users and a list of roles that are granted to those users.

The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The create or update role mappings API cannot update role mappings that are defined in role mapping files.

This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using Role Management APIs or roles files.

For more information, see Mapping users and groups to roles.

Path parameters

edit
name
(string) The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way.

Request body

edit

The following parameters can be specified in the body of a PUT or POST request and pertain to adding a role mapping:

enabled
(Required, boolean) Mappings that have enabled set to false are ignored when role mapping is performed.
metadata
(object) Additional metadata that helps define which roles are assigned to each user. Within the metadata object, keys beginning with _ are reserved for system usage.
roles
(list of strings) A list of role names that are granted to the users that match the role mapping rules. Exactly one of roles or role_templates must be specified.
role_templates
(list of objects) A list of mustache templates that will be evaluated to determine the roles names that should granted to the users that match the role mapping rules. The format of these objects is defined below. Exactly one of roles or role_templates must be specified.
rules
(Required, object) The rules that determine which users should be matched by the mapping. A rule is a logical condition that is expressed by using a JSON DSL. See Role mapping resources.

Role Templates

edit

The most common use for role mappings is to create a mapping from a known value on the user to a fixed role name. For example, all users in the cn=admin,dc=example,dc=com LDAP group should be given the superuser role in Elasticsearch. The roles field is used for this purpose.

For more complex needs it is possible to use Mustache templates to dynamically determine the names of the roles that should be granted to the user. The role_templates field is used for this purpose.

All of the user fields that are available in the role mapping rules are also available in the role templates. Thus it is possible to assign a user to a role that reflects their username, their groups or the name of the realm to which they authenticated.

By default a template is evaluated to produce a single string that is the name of the role which should be assigned to the user. If the format of the template is set to "json" then the template is expected to produce a JSON string, or an array of JSON strings for the role name(s).

The Examples section below demonstrates the use of templated role names.

Examples

edit

The following example assigns the "user" role to all users:

POST /_security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, 
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { 
    "version" : 1
  }
}

Mappings that have enabled set to false are ignored when role mapping is performed.

Metadata is optional.

A successful call returns a JSON structure that shows whether the mapping has been created or updated.

{
  "role_mapping" : {
    "created" : true 
  }
}

When an existing mapping is updated, created is set to false.

The following example assigns the "user" and "admin" roles to specific users:

POST /_security/role_mapping/mapping2
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}

The following example matches users who authenticated against a specific realm:

POST /_security/role_mapping/mapping3
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}

The following example matches any user where either the username is esadmin or the user is in the cn=admin,dc=example,dc=com group:

POST /_security/role_mapping/mapping4
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}

The example above is useful when the group names in your identity management system (such as Active Directory, or a SAML Identity Provider) do not have a 1-to-1 correspondence with the names of roles in Elasticsearch. The role mapping is the means by which you link a group name with a role name.

However, in rare cases the names of your groups may be an exact match for the names of your Elasticsearch roles. This can be the case when your SAML Identity Provider includes its own "group mapping" feature and can be configured to release Elasticsearch role names in the user’s SAML attributes.

In these cases it is possible to use a template that treats the group names as role names.

Note: This should only be done if you intend to define roles for all of the provided groups. Mapping a user to a large number of unnecessary or undefined roles is inefficient and can have a negative effect on system performance. If you only need to map a subset of the groups, then you should do this using explicit mappings.

POST /_security/role_mapping/mapping5
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}

The tojson mustache function is used to convert the list of group names into a valid JSON array.

Because the template produces a JSON array, the format must be set to json.

The following example matches users within a specific LDAP sub-tree:

POST /_security/role_mapping/mapping6
{
  "roles": [ "example-user" ],
  "enabled": true,
  "rules": {
    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
  }
}

The following example matches users within a particular LDAP sub-tree in a specific realm:

POST /_security/role_mapping/mapping7
{
  "roles": [ "ldap-example-user" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
      { "field" : { "realm.name" : "ldap1" } }
    ]
  }
}

The rules can be more complex and include wildcard matching. For example, the following mapping matches any user where all of these conditions are met:

  • the Distinguished Name matches the pattern *,ou=admin,dc=example,dc=com, or the username is es-admin, or the username is es-system
  • the user in in the cn=people,dc=example,dc=com group
  • the user does not have a terminated_date
POST /_security/role_mapping/mapping8
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "all": [
      {
        "any": [
          {
            "field": {
              "dn": "*,ou=admin,dc=example,dc=com"
            }
          },
          {
            "field": {
              "username": [ "es-admin", "es-system" ]
            }
          }
        ]
      },
      {
        "field": {
          "groups": "cn=people,dc=example,dc=com"
        }
      },
      {
        "except": {
          "field": {
            "metadata.terminated_date": null
          }
        }
      }
    ]
  }
}

A templated role can be used to automatically map every user to their own custom role. The role itself can be defined through the Roles API or using a custom roles provider.

In this example every user who authenticates using the "cloud-saml" realm will be automatically mapped to two roles - the "saml_user" role and a role that is their username prefixed with _user_. As an example, the user nwong would be assigned the saml_user and _user_nwong roles.

POST /_security/role_mapping/mapping9
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, 
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}

Because it is not possible to specify both roles and role_templates in the same role mapping, we can apply a "fixed name" role by using a template that has no substitutions.