2018-08-20 17:30:42 -04:00
[role="xpack"]
[[role-mapping-resources]]
=== Role mapping resources
A role mapping resource has the following properties:
`enabled`::
(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) A list of roles that are granted to the users that match the role mapping
rules.
`rules`::
(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. The DSL supports the following rule types:
`any`:::
(array of rules) If *any* of its children are true, it evaluates to `true`.
`all`:::
(array of rules) If *all* of its children are true, it evaluates to `true`.
`field`:::
(object) See <<mapping-roles-rule-field>>.
`except`::
(object) 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]]
==== Field rules
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
2019-07-24 08:37:37 -04:00
{ref}/regexp-syntax.html[Lucene regexp]. | "/.\*-admin[0-9]*/"
2018-08-20 17:30:42 -04:00
| 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"]
|=======================
[float]
===== User fields
The _user object_ against which rules are evaluated has the following fields:
`username`::
2018-12-19 17:53:37 -05:00
(string) The username by which the {es} {security-features} knows this user. For
example, `"username": "jsmith"`.
2018-08-20 17:30:42 -04:00
`dn`::
(string) The _Distinguished Name_ of the user. For example, `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`.
`groups`::
(array of strings) The groups to which the user belongs. For example, `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com","cn=esusers,ou=groups,dc=example,dc=com ]`.
`metadata`::
(object) Additional metadata for the user. For example, `"metadata": { "cn": "John Smith" }`.
`realm`::
(object) The realm that authenticated the user. The only field in this object is the realm name. For example, `"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:
2019-09-13 11:23:53 -04:00
[source,js]
2018-08-20 17:30:42 -04:00
------------------------------------------------------------
{ "field" : { "groups" : "admin" } }
------------------------------------------------------------
// NOTCONSOLE
For additional realm-specific details, see
{stack-ov}/mapping-roles.html#ldap-role-mapping[Mapping Users and Groups to Roles].
