honeymoose/OpenSearch
1
0
Fork 0
mirror of https://github.com/honeymoose/OpenSearch.git synced 2025-02-22 21:05:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOC] Splits role mapping APIs into separate pages (#32797)

Browse Source
This commit is contained in:
Lisa Cawley 2018-08-20 14:30:42 -07:00 committed by GitHub
parent 3fbaae10af
commit 2feda8aae0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 487 additions and 418 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/reference/redirects.asciidoc
View File

@ -531,3 +531,11 @@ native realm:
* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
* <<security-api-change-password,Change passwords>>
* <<security-api-get-user,Get users>>
[role="exclude",id="security-api-role-mapping"]
=== Role mapping APIs
You can use the following APIs to add, remove, and retrieve role mappings:
* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>

7
x-pack/docs/en/rest-api/defs.asciidoc
View File

@ -2,8 +2,8 @@
[[ml-api-definitions]]
== Definitions
These resource definitions are used in {ml} APIs and in {kib} advanced
job configuration options.
These resource definitions are used in {ml} and {security} APIs and in {kib}
advanced {ml} job configuration options.
* <<ml-calendar-resource,Calendars>>
* <<ml-datafeed-resource,{dfeeds-cap}>>
@ -13,6 +13,7 @@ job configuration options.
* <<ml-jobstats,Job statistics>>
* <<ml-snapshot-resource,Model snapshots>>
* <<ml-results-resource,Results>>
* <<role-mapping-resources,Role mappings>>
* <<ml-event-resource,Scheduled Events>>
[role="xpack"]
@ -26,6 +27,8 @@ include::ml/jobresource.asciidoc[]
[role="xpack"]
include::ml/jobcounts.asciidoc[]
[role="xpack"]
include::security/role-mapping-resources.asciidoc[]
[role="xpack"]
include::ml/snapshotresource.asciidoc[]
[role="xpack"]
include::ml/resultsresource.asciidoc[]

14
x-pack/docs/en/rest-api/security.asciidoc
View File

@ -7,7 +7,6 @@ You can use the following APIs to perform {security} activities.
* <<security-api-authenticate>>
* <<security-api-clear-cache>>
* <<security-api-privileges>>
* <<security-api-role-mapping>>
* <<security-api-ssl>>
[float]
@ -20,6 +19,15 @@ You can use the following APIs to add, remove, and retrieve roles in the native
* <<security-api-clear-role-cache,Clear roles cache>>
* <<security-api-get-role,Get roles>>
[float]
[[security-role-mapping-apis]]
=== Role mappings
You can use the following APIs to add, remove, and retrieve role mappings:
* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
* <<security-api-get-role-mapping,Get role mappings>>
[float]
[[security-token-apis]]
=== Tokens
@ -44,17 +52,19 @@ native realm:
include::security/authenticate.asciidoc[]
include::security/change-password.asciidoc[]
include::security/clear-cache.asciidoc[]
include::security/create-role-mappings.asciidoc[]
include::security/clear-roles-cache.asciidoc[]
include::security/create-roles.asciidoc[]
include::security/create-users.asciidoc[]
include::security/delete-role-mappings.asciidoc[]
include::security/delete-roles.asciidoc[]
include::security/delete-tokens.asciidoc[]
include::security/delete-users.asciidoc[]
include::security/disable-users.asciidoc[]
include::security/enable-users.asciidoc[]
include::security/get-role-mappings.asciidoc[]
include::security/get-roles.asciidoc[]
include::security/get-tokens.asciidoc[]
include::security/get-users.asciidoc[]
include::security/privileges.asciidoc[]
include::security/role-mapping.asciidoc[]
include::security/ssl.asciidoc[]

239
x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc Normal file
View File

@ -0,0 +1,239 @@
[role="xpack"]
[[security-api-put-role-mapping]]
=== Add role mappings API
Adds and updates role mappings.
==== Request
`POST /_xpack/security/role_mapping/<name>` +
`PUT /_xpack/security/role_mapping/<name>`
==== Description
Role mappings define which roles are assigned to each user. Each mapping has
_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
{stack-ov}/defining-roles.html#roles-management-file[roles files].
For more information, see
{stack-ov}/mapping-roles.html[Mapping users and groups to roles].
==== Path Parameters
`name`::
(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.
==== Request Body
The following parameters can be specified in the body of a PUT or POST request
and pertain to adding a role mapping:
`enabled` (required)::
(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` (required)::
(list) A list of roles that are granted to the users that match the role mapping
rules.
`rules` (required)::
(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. See
<<role-mapping-resources>>.
==== Authorization
To use this API, you must have at least the `manage_security` cluster privilege.
==== Examples
The following example assigns the "user" role to all users:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping1
{
"roles": [ "user"],
"enabled": true, <1>
"rules": {
"field" : { "username" : "*" }
},
"metadata" : { <2>
"version" : 1
}
}
------------------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
is performed.
<2> Metadata is optional.
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.
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

50
x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc Normal file
View File

@ -0,0 +1,50 @@
[role="xpack"]
[[security-api-delete-role-mapping]]
=== Delete role mappings API
Removes role mappings.
==== Request
`DELETE /_xpack/security/role_mapping/<name>`
==== Description
Role mappings define which roles are assigned to each user. For more information,
see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
==== Path Parameters
`name`::
(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.
//==== Request Body
==== Authorization
To use this API, you must have at least the `manage_security` cluster privilege.
==== Examples
The following example delete a role mapping:
[source,js]
--------------------------------------------------
DELETE /_xpack/security/role_mapping/mapping1
--------------------------------------------------
// CONSOLE
// TEST[setup:role_mapping]
If the mapping is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.
[source,js]
--------------------------------------------------
{
"found" : true
}
--------------------------------------------------
// TESTRESPONSE

74
x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc Normal file
View File

@ -0,0 +1,74 @@
[role="xpack"]
[[security-api-get-role-mapping]]
=== Get role mappings API
Retrieves role mappings.
==== Request
`GET /_xpack/security/role_mapping` +
`GET /_xpack/security/role_mapping/<name>`
==== Description
Role mappings define which roles are assigned to each user. For more information,
see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
==== Path Parameters
`name`::
(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. You can specify multiple
mapping names as a comma-separated list. If you do not specify this
parameter, the API returns information about all role mappings.
//==== Request Body
==== Results
A successful call retrieves an object, where the keys are the
names of the request mappings, and the values are the JSON representation of
those mappings. For more information, see
<<role-mapping-resources>>.
If there is no mapping with the requested name, the
response will have status code `404`.
==== Authorization
To use this API, you must have at least the `manage_security` cluster privilege.
==== Examples
The following example retrieves information about the `mapping1` role mapping:
[source,js]
--------------------------------------------------
GET /_xpack/security/role_mapping/mapping1
--------------------------------------------------
// CONSOLE
// TEST[setup:role_mapping]
[source,js]
--------------------------------------------------
{
"mapping1": {
"enabled": true,
"roles": [
"user"
],
"rules": {
"field": {
"username": "*"
}
},
"metadata": {}
}
}
--------------------------------------------------
// TESTRESPONSE

89
x-pack/docs/en/rest-api/security/role-mapping-resources.asciidoc Normal file
View File

@ -0,0 +1,89 @@
[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].

404
x-pack/docs/en/rest-api/security/role-mapping.asciidoc
View File

@ -1,404 +0,0 @@
[role="xpack"]
[[security-api-role-mapping]]
=== Role Mapping APIs
The Role Mapping API enables you to add, remove, and retrieve role mappings.
==== Request
`GET /_xpack/security/role_mapping` +
`GET /_xpack/security/role_mapping/<name>` +
`DELETE /_xpack/security/role_mapping/<name>` +
`POST /_xpack/security/role_mapping/<name>` +
`PUT /_xpack/security/role_mapping/<name>`
==== Description
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-role-apis,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].
==== Path Parameters
`name`::
(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
The following parameters can be specified in the body of a PUT or POST request
and pertain to adding a role mapping:
`enabled` (required)::
(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` (required)::
(list) A list of roles that are granted to the users that match the role-mapping
rules.
`rules` (required)::
(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.
==== Authorization
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. The following example assigns
the "user" role to all users:
[source, js]
------------------------------------------------------------
POST /_xpack/security/role_mapping/mapping1
{
"roles": [ "user"],
"enabled": true, <1>
"rules": {
"field" : { "username" : "*" }
},
"metadata" : { <2>
"version" : 1
}
}
------------------------------------------------------------
// CONSOLE
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
is performed.
<2> Metadata is optional.
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.
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/mapping7
--------------------------------------------------
// CONSOLE
// TEST[continued]
A successful call retrieves 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]
--------------------------------------------------
{
"mapping7": {
"enabled": true,
"roles": [
"superuser"
],
"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": {}
}
}
--------------------------------------------------
// TESTRESPONSE
You can specify multiple mapping names as a comma-separated list.
To retrieve all mappings, omit the name entirely.
[[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/mapping1
--------------------------------------------------
// CONSOLE
// TEST[setup:role_mapping]
If the mapping is successfully deleted, the request returns `{"found": true}`.
Otherwise, `found` is set to false.
[source,js]
--------------------------------------------------
{
"found" : true
}
--------------------------------------------------
// TESTRESPONSE

2
x-pack/docs/en/security/authentication/configuring-active-directory-realm.asciidoc
View File

@ -173,7 +173,7 @@ represent user roles for different systems in the organization.
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
configured via the <<security-role-mapping-apis,role-mapping APIs>> 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.

2
x-pack/docs/en/security/authentication/configuring-ldap-realm.asciidoc
View File

@ -133,7 +133,7 @@ supports both failover and load balancing modes of operation. See
--
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
{ref}/security-api-role-mapping.html[role-mapping API] or by using a file stored
{ref}/security-api-put-role-mapping.html[add 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.

2
x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc
View File

@ -126,7 +126,7 @@ The `certificate_authorities` option can be used as an alternative to the
+
--
You map roles for PKI users through the
<<security-api-role-mapping,role-mapping API>> or by using a file stored on
<<security-role-mapping-apis,role mapping APIs>> 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.

6
x-pack/docs/en/security/authentication/saml-guide.asciidoc
View File

@ -592,9 +592,9 @@ When a user authenticates using SAML, they are identified to the Elastic Stack,
but this does not automatically grant them access to perform any actions or
access any data.
Your SAML users cannot do anything until they are mapped to X-Pack Security
Your SAML users cannot do anything until they are mapped to {security}
roles. This mapping is performed through the
{ref}/security-api-role-mapping.html[role-mapping API]
{ref}/security-api-put-role-mapping.html[add role mapping API].
This is an example of a simple role mapping that grants the `kibana_user` role
to any user who authenticates against the `saml1` realm:
@ -626,7 +626,7 @@ mapping are derived from the SAML attributes as follows:
- `metadata`: See <<saml-user-metadata>>
For more information, see <<mapping-roles>> and
{ref}/security-api-role-mapping.html[Role Mapping APIs].
{ref}/security-api.html#security-role-mapping-apis[role mapping APIs].
If your IdP has the ability to provide groups or roles to Service Providers,
then you should map this SAML attribute to the `attributes.groups` setting in

2
x-pack/docs/en/security/authorization/mapping-roles.asciidoc
View File

@ -28,7 +28,7 @@ you are able to map users to both API-managed roles and file-managed roles
==== Using the role mapping API
You can define role-mappings through the
{ref}/security-api-role-mapping.html[role mapping API].
{ref}/security-api-put-role-mapping.html[add role mapping API].
[[mapping-roles-file]]
==== Using role mapping files

2
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_role_mapping.json
View File

@ -1,6 +1,6 @@
{
"xpack.security.delete_role_mapping": {
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-delete-role-mapping",
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role-mapping.html",
"methods": [ "DELETE" ],
"url": {
"path": "/_xpack/security/role_mapping/{name}",

2
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_role_mapping.json
View File

@ -1,6 +1,6 @@
{
"xpack.security.get_role_mapping": {
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-get-role-mapping",
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role-mapping.html",
"methods": [ "GET" ],
"url": {
"path": "/_xpack/security/role_mapping/{name}",

2
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_role_mapping.json
View File

@ -1,6 +1,6 @@
{
"xpack.security.put_role_mapping": {
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-role-mapping.html#security-api-put-role-mapping",
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role-mapping.html",
"methods": [ "PUT", "POST" ],
"url": {
"path": "/_xpack/security/role_mapping/{name}",