mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-25 01:19:02 +00:00
[DOCS] [Security] Documentation for Role Mapping API (elastic/x-pack-elasticsearch#1474)
Includes: - Extensive changes to "mapping roles" section - New section for role mapping API - Updates to LDAP/AD/PKI realms to refer to API based role mapping - Updates to LDAP/AD realms: `unmapped_groups_as_roles` only looks at file-based mappings - Updates to LDAP/AD realms: new setting for "metadata" Original commit: elastic/x-pack-elasticsearch@6349f665f5
This commit is contained in:
Tim Vernum
GitHub
parent
6e7102845b
commit
fe37109c3f
@ -5,6 +5,7 @@
|
||||
* <<security-api-clear-cache>>
|
||||
* <<security-api-users>>
|
||||
* <<security-api-roles>>
|
||||
* <<security-api-role-mapping>>
|
||||
* <<security-api-privileges>>
|
||||
* <<security-api-tokens>>
|
||||
|
||||
@ -13,5 +14,6 @@ include::security/change-password.asciidoc[]
|
||||
include::security/clear-cache.asciidoc[]
|
||||
include::security/users.asciidoc[]
|
||||
include::security/roles.asciidoc[]
|
||||
include::security/role-mapping.asciidoc[]
|
||||
include::security/privileges.asciidoc[]
|
||||
include::security/tokens.asciidoc[]
|
||||
|
||||
128
docs/en/rest-api/security/role-mapping.asciidoc
Normal file
128
docs/en/rest-api/security/role-mapping.asciidoc
Normal file
@ -0,0 +1,128 @@
|
||||
[[security-api-role-mapping]]
|
||||
=== Role Mapping APIs
|
||||
|
||||
The Role Mapping API enables you to add, remove, and retrieve role-mappings.
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
NOTE: The API requires that each role-mapping have a distinct name. The name is
|
||||
used solely as an identifier to facilitate interaction via the API, and does
|
||||
not affect the behaviour of the mapping in any way.
|
||||
|
||||
[[security-api-put-role-mapping]]
|
||||
To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
|
||||
endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /_xpack/security/role_mapping/administrators
|
||||
{
|
||||
"roles": [ "user", "admin" ],
|
||||
"enabled": true, <1>
|
||||
"rules": {
|
||||
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
|
||||
},
|
||||
"metadata" : { <2>
|
||||
"version" : 1
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> Mappings that have `enabled` set to `false` will be ignored when role-mapping
|
||||
is performed.
|
||||
<2> Metadata is optional
|
||||
|
||||
The `roles`, `enabled`, and `rules` fields are required at the top-level.
|
||||
Within the `metadata` object, keys beginning with `_` are reserved for system
|
||||
usage.
|
||||
|
||||
A successful call returns a JSON structure that shows whether the mapping has
|
||||
been created or updated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"role_mapping" : {
|
||||
"created" : true <1>
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
<1> When an existing mapping is updated, `created` is set to false.
|
||||
|
||||
[[security-api-get-role-mapping]]
|
||||
To retrieve a role-mapping, issue a GET request to the
|
||||
`/_xpack/security/role_mapping/<name>` endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_xpack/security/role_mapping/administrators
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
A successful call an object, where the keys are the
|
||||
names of the request mappings, and the values are
|
||||
the JSON representation of those mappings.
|
||||
If there is no mapping with the requested name, the
|
||||
response will have status code `404`.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"administrators" : {
|
||||
"enabled" : true,
|
||||
"roles" : [
|
||||
"user",
|
||||
"admin"
|
||||
],
|
||||
"rules" : {
|
||||
"field" : {
|
||||
"username" : [
|
||||
"esadmin01",
|
||||
"esadmin02"
|
||||
]
|
||||
}
|
||||
},
|
||||
"metadata" : {
|
||||
"version" : 1
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
You can specify multiple mapping names as a comma-separated list.
|
||||
To retrieve all mappings, omit the name entirely.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
# Retrieve mappings "m1", "m2", and "administrators"
|
||||
GET /_xpack/security/role_mapping/m1,m2,administrators
|
||||
|
||||
# Retrieve all mappings
|
||||
GET /_xpack/security/role_mapping
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
[[security-api-delete-role-mapping]]
|
||||
To delete a role-mapping, submit a DELETE request to the
|
||||
`/_xpack/security/role_mapping/<name>` endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_xpack/security/role_mapping/administrators
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
If the mapping is successfully deleted, the request returns `{"found": true}`.
|
||||
Otherwise, `found` is set to false.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"found" : true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
@ -219,9 +219,12 @@ operation are supported: failover and load balancing
|
||||
`base_dn` is a group object and that it is the only group considered.
|
||||
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped Active Directory
|
||||
groups should be used as role names and assigned to the user.
|
||||
A group is considered to be _unmapped_ if it is not referenced
|
||||
in any <<mapping-roles-file, role-mapping files>> (API based
|
||||
role-mappings are not considered).
|
||||
Defaults to `false`.
|
||||
| `files.role_mapping` | no | Specifies the path and file name of the
|
||||
<<ad-role-mapping, YAML role mapping configuration file>>.
|
||||
<<ldap-role-mapping, YAML role mapping configuration file>>.
|
||||
Defaults to `CONF_DIR/x-pack/role_mapping.yml`,
|
||||
where `CONF_DIR` is `ES_HOME/config` (zip/tar installations)
|
||||
or `/etc/elasticsearch` (package installations).
|
||||
@ -229,6 +232,8 @@ operation are supported: failover and load balancing
|
||||
by the Active Directory server. Referrals are URLs returned by
|
||||
the server that are to be used to continue the LDAP operation
|
||||
(such as `search`). Defaults to `true`.
|
||||
| `metadata` | no | Specifies the list of additional LDAP attributes that should
|
||||
be stored in the `metadata` of an authenticated user.
|
||||
| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the Active Directory
|
||||
server requires client authentication. `ssl.key` and `ssl.keystore.path` may not be used at the
|
||||
same time.
|
||||
@ -281,13 +286,55 @@ Active Directory server, the expectation is that their roles are managed there
|
||||
as well. In fact, Active Directory supports the notion of groups, which often
|
||||
represent user roles for different systems in the organization.
|
||||
|
||||
The `active_directory` realm enables you to map Active Directory users and groups
|
||||
to roles in the role mapping file stored on each node. You specify users and
|
||||
groups using their distinguished names (DNs). For example, the following mapping
|
||||
configuration maps the Active Directory `admins` group to both the `monitoring`
|
||||
and `user` roles, maps the `users` group to the `user` role and maps the `John Doe`
|
||||
user to the `user` role.
|
||||
The `active_directory` realm enables you to map Active Directory users to roles
|
||||
via their Active Directory groups, or other metadata. This role mapping can be
|
||||
configured via the <<security-api-role-mapping, role-mapping API>>, or by using
|
||||
a file stored on each node. When a user authenticates against an Active
|
||||
Directory realm, the privileges for that user are the union of all privileges
|
||||
defined by the roles to which the user is mapped.
|
||||
|
||||
Within a mapping definition, you specify groups using their distinguished
|
||||
names. For example, the following mapping configuration maps the Active
|
||||
Directory `admins` group to both the `monitoring` and `user` roles, maps the
|
||||
`users` group to the `user` role and maps the `John Doe` user to the `user`
|
||||
role.
|
||||
|
||||
Configured via the role-mapping API:
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/admins
|
||||
{
|
||||
"roles" : [ "monitoring" , "user" ],
|
||||
"rules" : { "field" : {
|
||||
"groups" : "cn=admins,dc=example,dc=com" <1>
|
||||
} },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> The Active Directory distinguished name (DN) of the `admins` group.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/basic_users
|
||||
{
|
||||
"roles" : [ "user" ],
|
||||
"rules" : { "any": [
|
||||
{ "field" : {
|
||||
"groups" : "cn=users,dc=example,dc=com" <1>
|
||||
} },
|
||||
{ "field" : {
|
||||
"dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" <2>
|
||||
} }
|
||||
] },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> The Active Directory distinguished name (DN) of the `users` group.
|
||||
<2> The Active Directory distinguished name (DN) of the user `John Doe`.
|
||||
|
||||
Or, alternatively, configured via the role-mapping file:
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
monitoring: <1>
|
||||
@ -307,7 +354,7 @@ For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.
|
||||
[[ad-user-metadata]]
|
||||
==== User Metadata in Active Directory Realms
|
||||
When a user is authenticated via an Active Directory realm, the following
|
||||
properties are populated in user's _metadata_. This metadata is returned in the
|
||||
properties are populated in the user's _metadata_. This metadata is returned in the
|
||||
<<security-api-authenticate,authenticate API>>, and can be used with
|
||||
<<templating-role-query, templated queries>> in roles.
|
||||
|
||||
@ -319,6 +366,8 @@ properties are populated in user's _metadata_. This metadata is returned in the
|
||||
groups were mapped to a role).
|
||||
|=======================
|
||||
|
||||
Additional metadata can be extracted from the Active Directory server by configuring
|
||||
the `metadata` setting on the Active Directory realm.
|
||||
|
||||
[[active-directory-ssl]]
|
||||
==== Setting up SSL Between Elasticsearch and Active Directory
|
||||
|
||||
@ -207,6 +207,9 @@ failover and load balancing modes of operation.
|
||||
the user DN is passed to the filter.
|
||||
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP groups
|
||||
should be used as role names and assigned to the user.
|
||||
A group is considered to be _unmapped_ if it is not referenced
|
||||
in any <<mapping-roles-file, role-mapping files>> (API based
|
||||
role-mappings are not considered).
|
||||
Defaults to `false`.
|
||||
| `timeout.tcp_connect` | no | Specifies the TCP connect timeout period for establishing an
|
||||
LDAP connection. An `s` at the end indicates seconds, or `ms`
|
||||
@ -224,6 +227,8 @@ failover and load balancing modes of operation.
|
||||
returned by the LDAP server. Referrals are URLs returned by
|
||||
the server that are to be used to continue the LDAP operation
|
||||
(e.g. search). Defaults to `true`.
|
||||
| `metadata` | no | Specifies the list of additional LDAP attributes that should
|
||||
be stored in the `metadata` of an authenticated user.
|
||||
| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the LDAP
|
||||
server requires client authentication. `ssl.key` and `ssl.keystore.path`
|
||||
may not be used at the same time.
|
||||
@ -330,15 +335,48 @@ the expectation is that their roles are managed there as well. If fact, LDAP
|
||||
supports the notion of groups, which often represent user roles for different
|
||||
systems in the organization.
|
||||
|
||||
The `ldap` realm enables you to map LDAP groups to roles in the role mapping
|
||||
file stored on each node. When a user authenticates with LDAP, the privileges
|
||||
for that user are the union of all privileges defined by the roles assigned to
|
||||
the set of groups that the user belongs to.
|
||||
The `ldap` realm enables you to map LDAP users to to roles via their LDAP
|
||||
groups, or other metadata. This role mapping can be configured via the
|
||||
<<security-api-role-mapping, role-mapping API>>, or by using a file stored
|
||||
on each node. When a user authenticates with LDAP, the privileges
|
||||
for that user are the union of all privileges defined by the roles to which
|
||||
the user is mapped.
|
||||
|
||||
You specify groups using their distinguished names. For example, the following
|
||||
mapping configuration maps the LDAP `admins` group to both the `monitoring` and
|
||||
`user` roles, and maps the `users` group to the `user` role.
|
||||
Within a mapping definition, you specify groups using their distinguished
|
||||
names. For example, the following mapping configuration maps the LDAP
|
||||
`admins` group to both the `monitoring` and `user` roles, and maps the
|
||||
`users` group to the `user` role.
|
||||
|
||||
Configured via the role-mapping API:
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/admins
|
||||
{
|
||||
"roles" : [ "monitoring" , "user" ],
|
||||
"rules" : { "field" : {
|
||||
"groups" : "cn=admins,dc=example,dc=com" <1>
|
||||
} },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> The LDAP distinguished name (DN) of the `admins` group.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/basic_users
|
||||
{
|
||||
"roles" : [ "user" ],
|
||||
"rules" : { "field" : {
|
||||
"groups" : "cn=users,dc=example,dc=com" <1>
|
||||
} },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> The LDAP distinguished name (DN) of the `users` group.
|
||||
|
||||
Or, alternatively, configured via the role-mapping file:
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
monitoring: <1>
|
||||
@ -368,6 +406,24 @@ populated in user's _metadata_. This metadata is returned in the
|
||||
groups were mapped to a role).
|
||||
|=======================
|
||||
|
||||
Additional fields can be included in the user's metadata by configuring
|
||||
the `metadata` setting on the LDAP realm. This metadata is available for use
|
||||
with the <<mapping-roles-api, role mapping API>> or in
|
||||
<<templating-role-query, templated role queries>>.
|
||||
|
||||
The example below includes the user's common name (`cn`) as an additional
|
||||
field in their metadata.
|
||||
[source,yaml]
|
||||
--------------------------------------------------
|
||||
xpack:
|
||||
security:
|
||||
authc:
|
||||
realms:
|
||||
ldap1:
|
||||
type: ldap
|
||||
metadata: cn
|
||||
--------------------------------------------------
|
||||
|
||||
[[ldap-ssl]]
|
||||
==== Setting up SSL Between Elasticsearch and LDAP
|
||||
|
||||
|
||||
@ -117,10 +117,32 @@ xpack:
|
||||
[[assigning-roles-pki]]
|
||||
==== Mapping Roles for PKI Users
|
||||
|
||||
You map roles for PKI users in the role mapping file stored on each node. You
|
||||
identify a user by the distinguished name in their certificate. For example, the
|
||||
following mapping configuration maps `John Doe` to the `user` role:
|
||||
You map roles for PKI users through the
|
||||
<<security-api-role-mapping, role-mapping API>>, or by using a file stored on
|
||||
each node. When a user authenticates against a PKI realm, the privileges for
|
||||
that user are the union of all privileges defined by the roles to which the
|
||||
user is mapped.
|
||||
|
||||
You identify a user by the distinguished name in their certificate.
|
||||
For example, the following mapping configuration maps `John Doe` to the
|
||||
`user` role:
|
||||
|
||||
Using the role-mapping API:
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/users
|
||||
{
|
||||
"roles" : [ "user" ],
|
||||
"rules" : { "field" : {
|
||||
"dn" : "cn=John Doe,ou=example,o=com" <1>
|
||||
} },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
<1> The distinguished name (DN) of a PKI user.
|
||||
|
||||
Or, alternatively, configured in a role-mapping file:
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
user: <1>
|
||||
|
||||
@ -5,7 +5,239 @@ If you authenticate users with the `native` or `file` realms, you can manage
|
||||
role assignment user the <<managing-native-users, User Management APIs>> or the
|
||||
<<managing-file-users, file-realm>> command-line tool respectively.
|
||||
|
||||
For other types of realms, you configure role mappings for users and groups in a
|
||||
For other types of realms, you must create _role-mappings_ that define which
|
||||
roles should be assigned to each user based on their username, groups, or
|
||||
other metadata.
|
||||
|
||||
{security} allows role-mappings to be defined via an
|
||||
<<mapping-roles-api, API>>, or managed through <<mapping-roles-file, files>>.
|
||||
These two sources of role-mapping are combined inside of {security}, so it is
|
||||
possible for a single user to have some roles that have been mapped through
|
||||
the API, and other roles that are mapped through files.
|
||||
|
||||
When you use role-mappings, you assign existing roles to users.
|
||||
The available roles should either be added using the
|
||||
<<roles-management-api, Role Management APIs>> or defined in the
|
||||
<<roles-management-file, roles file>>. Either role-mapping method can use
|
||||
either role management method. For example, when you use the role mapping API,
|
||||
you are able to map users to both API-managed roles and file-managed roles
|
||||
(and likewise for file-based role-mappings).
|
||||
|
||||
[[mapping-roles-api]]
|
||||
==== Using the Role Mapping API
|
||||
|
||||
You can define role-mappings through the
|
||||
<<security-api-role-mapping, role mapping API>>.
|
||||
|
||||
Each role-mapping has a distinct name which is used to interact with it via the
|
||||
API. The name does not affect the behaviour of the mapping in any way, but it
|
||||
is needed so that you can update or delete an existing mapping.
|
||||
|
||||
A mapping has _rules_ that determine which users should be matched by this
|
||||
mapping, a list of _roles_ that will be granted to the users that match.
|
||||
|
||||
The rule is a logical condition that is expressed using a JSON DSL.
|
||||
An mapping example with a simple rule is shown below:
|
||||
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"roles": [ "superuser" ],
|
||||
"enabled": true,
|
||||
"rules": {
|
||||
"any": [
|
||||
{
|
||||
"field": {
|
||||
"username": "esadmin"
|
||||
}
|
||||
},
|
||||
{
|
||||
"field": {
|
||||
"groups": "cn=admins,dc=example,dc=com"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
This mapping matches any user where either of these conditions are met:
|
||||
|
||||
- the username is `esadmin`
|
||||
- the user is in the `cn=admins,dc=example,dc=com` group
|
||||
|
||||
|
||||
The rules can be more complex and include wildcard matching:
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
The mapping above 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`
|
||||
|
||||
[float]
|
||||
===== The Role Mapping DSL
|
||||
The DSL supports the following rule types:
|
||||
|
||||
|=======================
|
||||
| Type | Value Type (child) | Description
|
||||
|
||||
| `any` | An array of rules | Evaluates to `true` if *any* of its
|
||||
children are true
|
||||
| `all` | An array of rules | Evaluates to `true` if *all* of its
|
||||
children are true
|
||||
| `field` | An object | <<mapping-roles-rule-field, See below>>
|
||||
| `except` | A single rule as an object | Only valid as a child of an `all`
|
||||
rule, the `except` is `true` if its
|
||||
child is `false` (negation).
|
||||
|=======================
|
||||
|
||||
[float]
|
||||
[[mapping-roles-rule-field]]
|
||||
===== The `field` Rule
|
||||
|
||||
The `field` rule is the primary building block for a role-mapping expression.
|
||||
It takes a single object as value, and that object must contains 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 may be one of the following types:
|
||||
[cols="2,3m,5"]
|
||||
|=======================
|
||||
| Type | Example | Description
|
||||
|
||||
| Simple String | "esadmin" | Matches exactly the provided value
|
||||
| Wildcard String | "*,dc=example,dc=com" | Matches the provided value using a wildcard
|
||||
| Regular Expression | "/.\*-admin[0-9]*/" | Matches the provided value using a
|
||||
{ref}/query-dsl-regexp-query.html#regexp-syntax[Lucene regexp]
|
||||
| Number | 7 | Matches an equivalent numerical value
|
||||
| Null | null | Matches a null, or missing value
|
||||
| Array | ["admin", "operator"] | Tests each element in the array in
|
||||
accordance with the definitions above.
|
||||
The match is successful if _any_ of elements match.
|
||||
|=======================
|
||||
|
||||
===== Available User Fields
|
||||
|
||||
The _user object_ against which the rules are evaluated has the following fields:
|
||||
[cols="1s,1,3"]
|
||||
|=======================
|
||||
| Name | Type | Description
|
||||
|
||||
| username | string | The username by which {security} knows this user.
|
||||
| dn | string | The _Distinguished Name_ of the user.
|
||||
| groups | array-of-string | The groups to which the user belongs.
|
||||
| metadata | object | Additional metadata for the user.
|
||||
| realm | object | The realm that authenticated the user.
|
||||
The only field in this object is the realm name.
|
||||
|=======================
|
||||
|
||||
Example:
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"username": "jsmith",
|
||||
"dn" : "cn=jsmith,ou=users,dc=example,dc=com",
|
||||
"groups" : [ "cn=admin,ou=groups,dc=example,dc=com", "cn=esusers,ou=groups,dc=example,dc=com" ],
|
||||
"metadata": { "cn": "John Smith" },
|
||||
"realm" : { "name": "ldap1" }
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
The `groups` field is multi-valued - a user may 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. This means that the rule:
|
||||
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{ "field" : { "groups" : "admin" } }
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
will match any user who is a member of the `admin` group, regardless of any
|
||||
other groups they may belong to.
|
||||
|
||||
===== Role Mapping Examples
|
||||
|
||||
- Match *all users*
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{ "field" : { "username" : "*" } }
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
- Match users who authenticated against a *specific realm*:
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{ "field" : { "realm.name" : "ldap1" } }
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
- Match users within a particular *LDAP sub-tree*: +
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } }
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
- Match users within a particular *LDAP sub-tree* in a *specific realm*:
|
||||
[source, js]
|
||||
------------------------------------------------------------
|
||||
{
|
||||
"all": [
|
||||
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
|
||||
{ "field" : { "realm.name" : "ldap1" } }
|
||||
]
|
||||
}
|
||||
------------------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
[[mapping-roles-file]]
|
||||
==== Using Role Mapping Files
|
||||
|
||||
To use file based role-mappings, you must configure the mappings in a
|
||||
YAML file and copy it to each node in the cluster. Tools like Puppet or Chef can
|
||||
help with this.
|
||||
|
||||
@ -26,20 +258,20 @@ are values. The mappings can have a many-to-many relationship. When you map role
|
||||
to groups, the roles of a user in that group are the combination of the roles
|
||||
assigned to that group and the roles assigned to that user.
|
||||
|
||||
[[ad-role-mapping]]
|
||||
The available roles are either added using the <<roles-management-api, Role Management APIs>>
|
||||
or defined in the <<roles-management-file, roles file>>. To specify users and
|
||||
groups in the role mappings, you use their _Distinguished Names_ (DNs). A DN is
|
||||
a string that uniquely identifies the user or group, for example
|
||||
`"cn=John Doe,cn=contractors,dc=example,dc=com"`.
|
||||
==== Realm Specific Details
|
||||
[float]
|
||||
[[ldap-role-mapping]]
|
||||
===== Active Directory and LDAP Realms
|
||||
To specify users and groups in the role mappings, you use their
|
||||
_Distinguished Names_ (DNs). A DN is a string that uniquely identifies the user
|
||||
or group, for example `"cn=John Doe,cn=contractors,dc=example,dc=com"`.
|
||||
|
||||
NOTE: {security} only supports Active Directory security groups. You cannot map
|
||||
distribution groups to roles.
|
||||
|
||||
[[ldap-role-mapping]]
|
||||
For example, the following snippet maps the `admins` group to the `monitoring`
|
||||
role and maps the `John Doe` user, the `users` group, and the `admins` group to
|
||||
the `user` role.
|
||||
For example, the following snippet uses the file-based method to map the
|
||||
`admins` group to the `monitoring` role and map the `John Doe` user, the
|
||||
`users` group, and the `admins` group to the `user` role.
|
||||
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
@ -54,9 +286,41 @@ user:
|
||||
<2> The distinguished name of an LDAP group or an Active Directory security group.
|
||||
<3> The distinguished name of an LDAP or Active Directory user.
|
||||
|
||||
We can use the role-mapping API to define equivalent mappings as follows:
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/admins
|
||||
{
|
||||
"roles" : [ "monitoring", "user" ],
|
||||
"rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/basic_users
|
||||
{
|
||||
"roles" : [ "user" ],
|
||||
"rules" : { "any" : [
|
||||
{ "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } },
|
||||
{ "field" : { "groups" : "cn=users,dc=example,dc=com" } }
|
||||
] },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
[float]
|
||||
[[pki-role-mapping]]
|
||||
PKI realms only support mapping users to roles, as there is no notion of a group
|
||||
in PKI. For example:
|
||||
===== PKI Realms
|
||||
PKI realms support mapping users to roles, but you cannot map groups as
|
||||
the PKI realm has no notion of a group.
|
||||
|
||||
This is an example using a file-based mapping:
|
||||
|
||||
[source, yaml]
|
||||
------------------------------------------------------------
|
||||
@ -65,3 +329,28 @@ monitoring:
|
||||
user:
|
||||
- "cn=John Doe,ou=example,o=com"
|
||||
------------------------------------------------------------
|
||||
|
||||
And the equivalent mappings using the API:
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/admin_user
|
||||
{
|
||||
"roles" : [ "monitoring" ],
|
||||
"rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
PUT _xpack/security/role_mapping/basic_user
|
||||
{
|
||||
"roles" : [ "user" ],
|
||||
"rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } },
|
||||
"enabled": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
@ -221,8 +221,8 @@ the filter. If not set, the user DN is passed into the filter. Defaults to Empt
|
||||
|
||||
`unmapped_groups_as_roles`::
|
||||
Takes a boolean variable. When this element is set to `true`, the names of any
|
||||
unmapped LDAP groups are used as role names and assigned to the user. Defaults
|
||||
to `false`.
|
||||
LDAP groups that are not referenced in a role-mapping _file_ are used as role
|
||||
names and assigned to the user. Defaults to `false`.
|
||||
|
||||
`files.role_mapping`::
|
||||
The <<security-files-location,location>> for the <<ldap-role-mapping,
|
||||
@ -234,6 +234,10 @@ Boolean value that specifies whether Securityshould follow referrals returned
|
||||
by the LDAP server. Referrals are URLs returned by the server that are to be
|
||||
used to continue the LDAP operation (e.g. search). Defaults to `true`.
|
||||
|
||||
`metadata`::
|
||||
A list of additional LDAP attributes that should be loaded from the
|
||||
LDAP server and stored in the authenticated user's metadata field.
|
||||
|
||||
`timeout.tcp_connect`::
|
||||
The TCP connect timeout period for establishing an LDAP connection.
|
||||
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
|
||||
@ -331,12 +335,12 @@ The domain name of Active Directory. The cluster can derive the URL and
|
||||
otherwise specified. Required.
|
||||
|
||||
`unmapped_groups_as_roles`::
|
||||
Takes a boolean variable. When this element is set to `true`, the names of
|
||||
any unmapped groups and the user's relative distinguished name are used as
|
||||
role names and assigned to the user. Defaults to `false`.
|
||||
Takes a boolean variable. When this element is set to `true`, the names of any
|
||||
LDAP groups that are not referenced in a role-mapping _file_ are used as role
|
||||
names and assigned to the user. Defaults to `false`.
|
||||
|
||||
`files.role_mapping`::
|
||||
The <<security-files-location,location>> for the <<ad-role-mapping, YAML
|
||||
The <<security-files-location,location>> for the <<ldap-role-mapping, YAML
|
||||
role mapping configuration file>>. Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`.
|
||||
|
||||
`user_search.base_dn`::
|
||||
@ -383,7 +387,11 @@ Specifies whether the group search should be `sub_tree`, `one_level` or
|
||||
`base` specifies that the `base_dn` is a group object, and that it is
|
||||
the only group considered. Defaults to `sub_tree`.
|
||||
|
||||
`timeout.tcp_connect`::
|
||||
`metadata`::
|
||||
A list of additional LDAP attributes that should be loaded from the
|
||||
LDAP server and stored in the authenticated user's metadata field.
|
||||
|
||||
`timeout.tcp_connect`::
|
||||
The TCP connect timeout period for establishing an LDAP connection.
|
||||
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
|
||||
Defaults to `5s` (5 seconds ).
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"xpack.security.delete_role_mapping": {
|
||||
"documentation": "Deletes a native role mapping (Documentation WIP)",
|
||||
"documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-delete-role-mapping",
|
||||
"methods": [ "DELETE" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role_mapping/{name}",
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"xpack.security.get_role_mapping": {
|
||||
"documentation": "Retrieves a native role mapping (Documentation WIP)",
|
||||
"documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-get-role-mapping",
|
||||
"methods": [ "GET" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role_mapping/{name}",
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"xpack.security.put_role_mapping": {
|
||||
"documentation": "Stores a native role mapping (Documentation WIP)",
|
||||
"documentation": "https://www.elastic.co/guide/en/x-pack/master/security-api-role-mapping.html#security-api-put-role-mapping",
|
||||
"methods": [ "PUT", "POST" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role_mapping/{name}",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user