OpenSearch/docs/en/rest-api/security/role-mapping.asciidoc

[role="xpack"]
[[security-api-role-mapping]]
=== 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.

NOTE: This API does not create roles. Rather, it maps users to existing roles.
Roles can be created by using <<security-api-roles, Role Management APIs>> or
{xpack-ref}/defining-roles.html#roles-management-file[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 <<mapping-roles-rule-field>>
| `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`.
|=======================

[float]
[[mapping-roles-rule-field]]
===== 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:
[cols="2,5,3m"]
|=======================
| 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
                       {ref}/query-dsl-regexp-query.html#regexp-syntax[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:
[cols="1s,,,m"]
|=======================
| Name        | Type            | Description | Example

| username    | string          | The username by which {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:

[source, js]
------------------------------------------------------------
{ "field" : { "groups" : "admin" } }
------------------------------------------------------------
// NOTCONSOLE

For additional realm-specific details, see
{xpack-ref}/mapping-roles.html#ldap-role-mapping[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

[[security-api-put-role-mapping]]
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:

[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, <1>
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { <2>
    "version" : 1
  }
}
------------------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
    is performed.
<2> Metadata is optional.

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

[source,js]
--------------------------------------------------
{
  "role_mapping" : {
    "created" : true <1>
  }
}
--------------------------------------------------
// TESTRESPONSE
<1> When an existing mapping is updated, `created` is set to false.

The following example assigns the "user" and "admin" roles to specific users:

[source,js]
--------------------------------------------------
POST /_xpack/security/role_mapping/mapping2
{
  "roles": [ "user", "admin" ],
  "enabled": true,
  "rules": {
     "field" : { "username" : [ "esadmin01", "esadmin02" ] }
  }
}
--------------------------------------------------
// CONSOLE

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:

[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping3
{
  "roles": [ "superuser" ],
  "enabled": true,
  "rules": {
    "any": [
      {
        "field": {
          "username": "esadmin"
        }
      },
      {
        "field": {
          "groups": "cn=admins,dc=example,dc=com"
        }
      }
    ]
  }
}
------------------------------------------------------------
// CONSOLE

The following example matches users who authenticated against a specific realm:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping4
{
  "roles": [ "ldap-user" ],
  "enabled": true,
  "rules": {
    "field" : { "realm.name" : "ldap1" }
  }
}
------------------------------------------------------------
// CONSOLE

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

[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping5
{
  "roles": [ "example-user" ],
  "enabled": true,
  "rules": {
    "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
  }
}
------------------------------------------------------------
// CONSOLE

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

[source, js]
------------------------------------------------------------
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" } }
    ]
  }
}
------------------------------------------------------------
// CONSOLE

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`


[source, js]
------------------------------------------------------------
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
          }
        }
      }
    ]
  }
}
------------------------------------------------------------
// CONSOLE

[[security-api-get-role-mapping]]
To retrieve a role mapping, issue a GET request to the
`/_xpack/security/role_mapping/<name>` endpoint:

[source,js]
--------------------------------------------------
GET /_xpack/security/role_mapping/mapping7
--------------------------------------------------
// CONSOLE
// TEST[continued]

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

[source,js]
--------------------------------------------------
{
  "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": {}
  }
}
--------------------------------------------------
// TESTRESPONSE

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

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

[source,js]
--------------------------------------------------
DELETE /_xpack/security/role_mapping/mapping1
--------------------------------------------------
// CONSOLE
// TEST[setup:role_mapping]

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

[source,js]
--------------------------------------------------
{
  "found" : true
}
--------------------------------------------------
// TESTRESPONSE