[role="xpack"]
[[security-api-put-role-mapping]]
=== Create or update role mappings API
++++
<titleabbrev>Create or update role mappings</titleabbrev>
++++

Creates and updates role mappings.

[[security-api-put-role-mapping-request]]
==== {api-request-title}

`POST /_security/role_mapping/<name>` +

`PUT /_security/role_mapping/<name>`


[[security-api-put-role-mapping-prereqs]]
==== {api-prereq-title}

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

[[security-api-put-role-mapping-desc]]
==== {api-description-title}

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 {ref}/mapping-roles.html#mapping-roles-file[role mapping files].
The create or update role mappings API cannot update role mappings that are defined
in role mapping files.

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
<<roles-management-file,roles files>>.

For more information, see <<mapping-roles>>.


[[security-api-put-role-mapping-path-params]]
==== {api-path-parms-title}

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


[[security-api-put-role-mapping-request-body]]
==== {api-request-body-title}

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`::
(list of strings) A list of role names that are granted to the users that match
the role mapping rules.
_Exactly one of `roles` or `role_templates` must be specified_.

`role_templates`::
(list of objects) A list of mustache templates that will be evaluated to
determine the roles names that should granted to the users that match the role
mapping rules.
The format of these objects is defined below.
_Exactly one of `roles` or `role_templates` must be specified_.

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

==== Role Templates

The most common use for role mappings is to create a mapping from a known value
on the user to a fixed role name.
For example, all users in the `cn=admin,dc=example,dc=com` LDAP group should be
given the `superuser` role in {es}.
The `roles` field is used for this purpose.

For more complex needs it is possible to use Mustache templates to dynamically
determine the names of the roles that should be granted to the user.
The `role_templates` field is used for this purpose.

All of the <<role-mapping-resources,user fields>> that are available in the
role mapping `rules` are also available in the role templates. Thus it is possible
to assign a user to a role that reflects their `username`, their `groups` or the
name of the `realm` to which they authenticated.

By default a template is evaluated to produce a single string that is the name
of the role which should be assigned to the user. If the `format` of the template
is set to `"json"` then the template is expected to produce a JSON string, or an
array of JSON strings for the role name(s).

The Examples section below demonstrates the use of templated role names.

[[security-api-put-role-mapping-example]]
==== {api-examples-title}

The following example assigns the "user" role to all users:

[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping1
{
  "roles": [ "user"],
  "enabled": true, <1>
  "rules": {
    "field" : { "username" : "*" }
  },
  "metadata" : { <2>
    "version" : 1
  }
}
------------------------------------------------------------
<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,console-result]
--------------------------------------------------
{
  "role_mapping" : {
    "created" : true <1>
  }
}
--------------------------------------------------

<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,console]
--------------------------------------------------
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:
[source,console]
------------------------------------------------------------
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:

[source,console]
------------------------------------------------------------
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 {es}. The role mapping is the
means by which you link a _group name_ with a _role name_.

However, in rare cases the names of your groups may be an exact match for the
names of your {es} roles. This can be the case when your SAML Identity Provider
includes its own "group mapping" feature and can be configured to release {es}
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.

[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping5
{
  "role_templates": [
    {
      "template": { "source": "{{#tojson}}groups{{/tojson}}" }, <1>
      "format" : "json" <2>
    }
  ],
  "rules": {
    "field" : { "realm.name" : "saml1" }
  },
  "enabled": true
}
------------------------------------------------------------
<1> The `tojson` mustache function is used to convert the list of
    group names into a valid JSON array.
<2> Because the template produces a JSON array, the format must be
    set to `json`.

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

[source,console]
------------------------------------------------------------
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:

[source,console]
------------------------------------------------------------
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:

- 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,console]
------------------------------------------------------------
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
<<security-api-put-role, Roles API>> or using a
<<implementing-custom-roles-provider,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.

[source,console]
------------------------------------------------------------
POST /_security/role_mapping/mapping9
{
  "rules": { "field": { "realm.name": "cloud-saml" } },
  "role_templates": [
    { "template": { "source" : "saml_user" } }, <1>
    { "template": { "source" : "_user_{{username}}" } }
  ],
  "enabled": true
}
------------------------------------------------------------
<1> Because it is not possible to specify both `roles` and `role_templates` in
    the same role mapping, we can apply a "fixed name" role by using a template
    that has no substitutions.