honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Role Mapping API improvements (elastic/x-pack-elasticsearch#3951) 

Original commit: elastic/x-pack-elasticsearch@d300c96c7a
This commit is contained in:
Lisa Cawley 2018-02-16 09:29:19 -08:00 committed by GitHub
parent 50be43bcd3
commit 3890875a88
3 changed files with 295 additions and 265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/build.gradle
View File

@ -379,3 +379,14 @@ setups['calendar_outages_addevent'] = setups['calendar_outages_addjob'] + '''
{ "description": "event 3", "start_time": "1514160000000", "end_time": "1514246400000"}
]}
'''
setups['role_mapping'] = '''
- do:
xpack.security.put_role_mapping:
name: "mapping1"
body: >
{
"enabled": true,
"roles": [ "user" ],
"rules": { "field": { "username": "*" } }
}
'''

319
docs/en/rest-api/security/role-mapping.asciidoc
View File

@ -18,19 +18,94 @@ The Role Mapping API enables you to add, remove, and retrieve role mappings.
==== Description
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 behavior of the mapping in any way.
Role mappings have _rules_ that identify users and a list of _roles_ that are
granted to those users.
NOTE: This API does not create roles. Rather, it maps users to existing roles.
Roles can be created by using <<security-api-roles, Role Management APIs>> or
{xpack-ref}/defining-roles.html#roles-management-file[roles files].
The role mapping rule is a logical condition that is expressed using a JSON DSL.
The DSL supports the following rule types:
|=======================
| Type | Value Type (child) | Description
| `any` | An array of rules | If *any* of its children are true, it
evaluates to `true`.
| `all` | An array of rules | If *all* of its children are true, it
evaluates to `true`.
| `field` | An object | See <<mapping-roles-rule-field>>
| `except` | 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]]
===== The Field Rule
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"]
|=======================
===== User Fields
The _user object_ against which rules are evaluated has the following fields:
[cols="1s,,,m"]
|=======================
| Name | Type | Description | Example
| username | string | The username by which {security} knows this user. | `"username": "jsmith"`
| dn | string | The _Distinguished Name_ of the user. | `"dn": "cn=jsmith,ou=users,dc=example,dc=com",`
| groups | array-of-string | The groups to which the user belongs. | `"groups" : [ "cn=admin,ou=groups,dc=example,dc=com",
"cn=esusers,ou=groups,dc=example,dc=com ]`
| metadata | object | Additional metadata for the user. | `"metadata": { "cn": "John Smith" }`
| realm | object | The realm that authenticated the user. The only field in this object is the realm name. | `"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
{xpack-ref}/mapping-roles.html#ldap-role-mapping[Mapping Users and Groups to Roles].
For more information, see
{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
==== Path Parameters
`name`::
(string) The distinct name that identifies the role mapping. If you do not
specify this parameter, the Get Role Mappings API returns information about all
role mappings.
(string) The distinct name that identifies the role mapping. The name is
used solely as an identifier to facilitate interaction via the API; it does
not affect the behavior of the mapping in any way. If you do not specify this
parameter for the Get Role Mappings API, it returns information about all
role mappings.
==== Request Body
@ -64,27 +139,27 @@ To use this API, you must have at least the `manage_security` cluster privilege.
==== Examples
[[security-api-put-role-mapping]]
To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
endpoint:
To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>` endpoint. The following example assigns
the "user" role to all users:
[source,js]
--------------------------------------------------
POST /_xpack/security/role_mapping/administrators
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping1
{
"roles": [ "user", "admin" ],
"roles": [ "user"],
"enabled": true, <1>
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
"field" : { "username" : "*" }
},
"metadata" : { <2>
"version" : 1
}
}
--------------------------------------------------
------------------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` will be ignored when role mapping
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
is performed.
<2> Metadata is optional
<2> Metadata is optional.
A successful call returns a JSON structure that shows whether the mapping has
been created or updated.
@ -100,13 +175,152 @@ been created or updated.
// TESTRESPONSE
<1> When an existing mapping is updated, `created` is set to false.
The following example assigns the "user" and "admin" roles to specific users:
[source,js]
--------------------------------------------------
POST /_xpack/security/role_mapping/mapping2
{
"roles": [ "user", "admin" ],
"enabled": true,
"rules": {
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
}
}
--------------------------------------------------
// CONSOLE
The following example matches any user where either the username is `esadmin`
or the user is in the `cn=admin,dc=example,dc=com` group:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping3
{
"roles": [ "superuser" ],
"enabled": true,
"rules": {
"any": [
{
"field": {
"username": "esadmin"
}
},
{
"field": {
"groups": "cn=admins,dc=example,dc=com"
}
}
]
}
}
------------------------------------------------------------
// CONSOLE
The following example matches users who authenticated against a specific realm:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping4
{
"roles": [ "ldap-user" ],
"enabled": true,
"rules": {
"field" : { "realm.name" : "ldap1" }
}
}
------------------------------------------------------------
// CONSOLE
The following example matches users within a specific LDAP sub-tree:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping5
{
"roles": [ "example-user" ],
"enabled": true,
"rules": {
"field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
}
}
------------------------------------------------------------
// CONSOLE
The following example matches users within a particular LDAP sub-tree in a
specific realm:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping6
{
"roles": [ "ldap-example-user" ],
"enabled": true,
"rules": {
"all": [
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
{ "field" : { "realm.name" : "ldap1" } }
]
}
}
------------------------------------------------------------
// CONSOLE
The rules can be more complex and include wildcard matching. For example, the
following mapping 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`
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping7
{
"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
}
}
}
]
}
}
------------------------------------------------------------
// CONSOLE
[[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
GET /_xpack/security/role_mapping/mapping7
--------------------------------------------------
// CONSOLE
// TEST[continued]
@ -120,23 +334,45 @@ response will have status code `404`.
[source,js]
--------------------------------------------------
{
"administrators" : {
"enabled" : true,
"roles" : [
"user",
"admin"
"mapping7": {
"enabled": true,
"roles": [
"superuser"
],
"rules" : {
"field" : {
"username" : [
"esadmin01",
"esadmin02"
]
}
"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
}
}
}
]
},
"metadata" : {
"version" : 1
}
"metadata": {}
}
}
--------------------------------------------------
@ -145,27 +381,16 @@ response will have status code `404`.
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
DELETE /_xpack/security/role_mapping/mapping1
--------------------------------------------------
// CONSOLE
// TEST[continued]
// TEST[setup:role_mapping]
If the mapping is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.

230
docs/en/security/authorization/mapping-roles.asciidoc
View File

@ -17,7 +17,7 @@ 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
{ref}/security-api-roles.html[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
@ -29,217 +29,12 @@ you are able to map users to both API-managed roles and file-managed roles
You can define role-mappings through the
{ref}/security-api-role-mapping.html[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.
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.
By default, role mappings are stored in `ES_PATH_CONF/x-pack/role_mapping.yml`,
where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or
@ -260,14 +55,15 @@ assigned to that group and the roles assigned to that user.
By default, {security} checks role mapping files for changes every 5 seconds.
You can change this default behavior by changing the
`resource.reload.interval.high` setting in the `elasticsearch.yml` file
(as this is a common setting in Elasticsearch, changing its value may effect
other schedules in the system).
`resource.reload.interval.high` setting in the `elasticsearch.yml` file. Since
this is a common setting in Elasticsearch, changing its value might effect other
schedules in the system.
==== 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"`.
@ -292,7 +88,7 @@ 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:
You can use the role-mapping API to define equivalent mappings as follows:
[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/admins
@ -303,7 +99,6 @@ PUT _xpack/security/role_mapping/admins
}
--------------------------------------------------
// CONSOLE
// TEST
[source,js]
--------------------------------------------------
@ -318,11 +113,11 @@ PUT _xpack/security/role_mapping/basic_users
}
--------------------------------------------------
// CONSOLE
// TEST
[float]
[[pki-role-mapping]]
===== PKI Realms
PKI realms support mapping users to roles, but you cannot map groups as
the PKI realm has no notion of a group.
@ -336,7 +131,8 @@ user:
- "cn=John Doe,ou=example,o=com"
------------------------------------------------------------
And the equivalent mappings using the API:
The following example creates equivalent mappings using the API:
[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/admin_user
@ -347,7 +143,6 @@ PUT _xpack/security/role_mapping/admin_user
}
--------------------------------------------------
// CONSOLE
// TEST
[source,js]
--------------------------------------------------
@ -359,4 +154,3 @@ PUT _xpack/security/role_mapping/basic_user
}
--------------------------------------------------
// CONSOLE
// TEST