Create or update role mappings Added in 5.5.0

POST /_security/role_mapping/{name}
Api key auth Basic auth Bearer auth

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.

NOTE: This API does not create roles. Rather, it maps users to existing roles. Roles can be created by using the create or update roles API or roles files.

Role templates

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.

NOTE: To use role templates successfully, the relevant scripting feature must be enabled. Otherwise, all attempts to create a role mapping with role templates fail.

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 names.

External documentation

Path parameters

  • name string Required

    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.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

  • enabled boolean

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

  • metadata object
    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • roles array[string]

    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 array[object]

    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. Exactly one of roles or role_templates must be specified.

    Hide role_templates attributes Show role_templates attributes object
  • rules object
    Hide rules attributes Show rules attributes object
  • run_as array[string]

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
POST /_security/role_mapping/{name} 
curl \
 --request POST 'http://api.example.com/_security/role_mapping/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"roles\": [ \"user\"],\n  \"enabled\": true, \n  \"rules\": {\n    \"field\" : { \"username\" : \"*\" }\n  },\n  \"metadata\" : { \n    \"version\" : 1\n  }\n}"'
Request examples
Run `POST /_security/role_mapping/mapping1` to assign the `user` role to all users. 
{
  "roles": [ "user"],
  "enabled": true, 
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { 
    "version" : 1
  }
}
Run `POST /_security/role_mapping/mapping2` to assign the "user" and "admin" roles to specific users. 
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
    "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}
Run `POST /_security/role_mapping/mapping3` to match users who authenticated against a specific realm. 
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}
Run `POST /_security/role_mapping/mapping4` to match any user where either the username is `esadmin` or the user is in the `cn=admin,dc=example,dc=com group`. This example is useful when the group names in your identity management system (such as Active Directory, or a SAML Identity Provider) do not have a one-to-one 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. 
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}
Run `POST /_security/role_mapping/mapping5` to use an array syntax for the groups field when there are multiple groups. This pattern matches any of the groups (rather than all of the groups). 
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}
Run `POST /_security/role_mapping/mapping6` for rare cases when 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, you should do it by using explicit mappings. 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`. 
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, 
      "format" : "json" 
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}
Run `POST /_security/role_mapping/mapping7` to match users within a particular LDAP sub-tree in a specific realm. 
{
  "roles": [ "ldap-example-user" ],
  "enabled": true,
  "rules": {
    "all": [
      { "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
      { "field" : { "realm.name" : "ldap1" } }
    ]
  }
}
Run `POST /_security/role_mapping/mapping8` to assign rules that are complex and include wildcard matching. For example, this 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 is in the `cn=people,dc=example,dc=com` group; the user does not have a `terminated_date`. 
{
  "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
          }
        }
      }
    ]
  }
}
Run `POST /_security/role_mapping/mapping9` to use templated roles to automatically map every user to their own custom role. 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_`. For example, the user `nwong` would be assigned the `saml_user` and `_user_nwong` roles. 
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, 
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}
Response examples (200)
A successful response from `POST /_security/role_mapping/mapping1`. 
{
  "role_mapping" : {
    "created" : true 
  }
}