IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Clear Cache API Clear roles cache API »

› › ›

Create or update role mappings API

edit

Create or update role mappings API

edit

Adds and updates role mappings.

Request

edit

POST /_xpack/security/role_mapping/<name>

PUT /_xpack/security/role_mapping/<name>

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.

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 (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. See Role mapping resources.

Authorization

edit

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

Examples

edit

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

« Clear Cache API Clear roles cache API »