POST /_security/role_mapping/<name>

PUT /_security/role_mapping/<name>

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.

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

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

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
  }
}

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

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

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.

If there are multiple groups, you can use array syntax for the groups field. This matches any of the groups (rather than all of the groups):

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

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 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:

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
}