[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
                       {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"]
|=======================

[float]
===== User fields

The _user object_ against which rules are evaluated has the following fields:

`username`::
(string) The username by which {security} knows this user. For example, `"username": "jsmith"`.
`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:

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

For additional realm-specific details, see
{stack-ov}/mapping-roles.html#ldap-role-mapping[Mapping Users and Groups to Roles].