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


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

[discrete]
===== User fields

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

`username`::
(string) The username by which the {es} {security-features} 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. This can include a variety of key-value pairs. When referencing metadata fields in role mapping rules, use the dot notation to specify the key within the metadata object. If the key contains special characters such as parentheses, dots, or spaces, you must escape these characters using backslashes (`\`). 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
<<ldap-role-mapping>>.
