343 lines
11 KiB
Plaintext
343 lines
11 KiB
Plaintext
[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.
|
|
|