Role Mapping APIs

The Role Mapping API enables you to add, remove, and retrieve role mappings.

Request

GET /_xpack/security/role_mapping

GET /_xpack/security/role_mapping/<name>

DELETE /_xpack/security/role_mapping/<name>

POST /_xpack/security/role_mapping/<name>

PUT /_xpack/security/role_mapping/<name>

Description

Role mappings have rules that identify users and a list of roles that are granted to those users.

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.

The role mapping rule is a logical condition that is expressed using a JSON DSL. The DSL supports the following rule types:

Type Value Type (child) Description

any

An array of rules

If any of its children are true, it evaluates to true.

all

An array of rules

If all of its children are true, it evaluates to true.

field

An object

See The Field Rule

except

A single rule as an object

Only valid as a child of an all rule. If its child is false, the except is true.

The Field Rule

The field rule is the primary building block for a role-mapping expression. It takes a single object as its value and that object must contain a single member with key F and value V. The field rule looks up the value of F within the user object and then tests whether the user value matches the provided value V.

The value specified in the field rule can be one of the following types:

Type Description Example

Simple String

Exactly matches the provided value.

"esadmin"

Wildcard String

Matches the provided value using a wildcard.

"*,dc=example,dc=com"

Regular Expression

Matches the provided value using a Lucene regexp.

"/.*-admin[0-9]*/"

Number

Matches an equivalent numerical value.

7

Null

Matches a null or missing value.

null

Array

Tests each element in the array in accordance with the above definitions. If any of elements match, the match is successful.

["admin", "operator"]

User Fields

The user object against which rules are evaluated has the following fields:

Name Type Description Example

username

string

The username by which X-Pack security knows this user.

"username": "jsmith"

dn

string

The Distinguished Name of the user.

"dn": "cn=jsmith,ou=users,dc=example,dc=com",

groups

array-of-string

The groups to which the user belongs.

"groups" : [ "cn=admin,ou=groups,dc=example,dc=com", "cn=esusers,ou=groups,dc=example,dc=com ]

metadata

object

Additional metadata for the user.

"metadata": { "cn": "John Smith" }

realm

object

The realm that authenticated the user. The only field in this object is the realm name.

"realm": { "name": "ldap1" }

The groups field is multi-valued; a user can belong to many groups. When a field rule is applied against a multi-valued field, it is considered to match if at least one of the member values matches. For example, the following rule matches any user who is a member of the admin group, regardless of any other groups they belong to:

{ "field" : { "groups" : "admin" } }

For additional realm-specific details, see Mapping Users and Groups to Roles.

Path Parameters

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. If you do not specify this parameter for the Get Role Mappings API, it returns information about all role mappings.

Request Body

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 (required)
(list) A list of roles that are granted to the users that match the role-mapping rules.
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.

Authorization

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

Examples

To add a role mapping, submit a PUT or POST request to the /_xpack/security/role_mapping/<name> endpoint. The following example assigns the "user" role to all users:

POST /_xpack/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 /_xpack/security/role_mapping/mapping2
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}

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 /_xpack/security/role_mapping/mapping3
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}

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

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

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

POST /_xpack/security/role_mapping/mapping5
{
  "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 /_xpack/security/role_mapping/mapping6
{
  "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 /_xpack/security/role_mapping/mapping7
{
  "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
          }
        }
      }
    ]
  }
}

To retrieve a role mapping, issue a GET request to the /_xpack/security/role_mapping/<name> endpoint:

GET /_xpack/security/role_mapping/mapping7

A successful call retrieves an object, where the keys are the names of the request mappings, and the values are the JSON representation of those mappings. If there is no mapping with the requested name, the response will have status code 404.

{
  "mapping7": {
    "enabled": true,
    "roles": [
      "superuser"
    ],
    "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
            }
          }
        }
      ]
    },
    "metadata": {}
  }
}

You can specify multiple mapping names as a comma-separated list. To retrieve all mappings, omit the name entirely.

To delete a role mapping, submit a DELETE request to the /_xpack/security/role_mapping/<name> endpoint:

DELETE /_xpack/security/role_mapping/mapping1

If the mapping is successfully deleted, the request returns {"found": true}. Otherwise, found is set to false.

{
  "found" : true
}