91 lines
3.8 KiB
Plaintext
91 lines
3.8 KiB
Plaintext
[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 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. 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].
|