Role Mapping APIs

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>

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

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

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:

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

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

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

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

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

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
}