[DOCS] Splits the roles API documentation into multiple pages (#32794)
This commit is contained in:
Lisa Cawley
GitHub
parent
e3aa68b0a9
commit
c5de9ec79d
|
|
@ -722,3 +722,17 @@ setups['sensor_prefab_data'] = '''
|
|||
{"node.terms.value":"c","temperature.sum.value":202.0,"temperature.max.value":202.0,"timestamp.date_histogram.time_zone":"UTC","temperature.min.value":202.0,"timestamp.date_histogram._count":1,"timestamp.date_histogram.interval":"1h","_rollup.computed":["temperature.sum","temperature.min","voltage.avg","temperature.max","node.terms","timestamp.date_histogram"],"voltage.avg.value":4.0,"node.terms._count":1,"_rollup.version":1,"timestamp.date_histogram.timestamp":1516294800000,"voltage.avg._count":1.0,"_rollup.id":"sensor"}
|
||||
|
||||
'''
|
||||
setups['admin_role'] = '''
|
||||
- do:
|
||||
xpack.security.put_role:
|
||||
name: "my_admin_role"
|
||||
body: >
|
||||
{
|
||||
"cluster": ["all"],
|
||||
"indices": [
|
||||
{"names": ["index1", "index2" ], "privileges": ["all"], "field_security" : {"grant" : [ "title", "body" ]}}
|
||||
],
|
||||
"run_as": [ "other_user" ],
|
||||
"metadata" : {"version": 1}
|
||||
}
|
||||
'''
|
||||
|
|
|
|||
|
|
@ -2,20 +2,26 @@
|
|||
[[security-api]]
|
||||
== Security APIs
|
||||
|
||||
You can use the following APIs to perform {security} activities.
|
||||
|
||||
* <<security-api-authenticate>>
|
||||
* <<security-api-clear-cache>>
|
||||
* <<security-api-privileges>>
|
||||
* <<security-api-roles>>
|
||||
* <<security-api-role-mapping>>
|
||||
* <<security-api-ssl>>
|
||||
* <<security-api-tokens>>
|
||||
* <<security-api-users>>
|
||||
|
||||
include::security/roles.asciidoc[]
|
||||
|
||||
include::security/authenticate.asciidoc[]
|
||||
include::security/change-password.asciidoc[]
|
||||
include::security/clear-cache.asciidoc[]
|
||||
include::security/clear-roles-cache.asciidoc[]
|
||||
include::security/create-roles.asciidoc[]
|
||||
include::security/delete-roles.asciidoc[]
|
||||
include::security/get-roles.asciidoc[]
|
||||
include::security/privileges.asciidoc[]
|
||||
include::security/roles.asciidoc[]
|
||||
include::security/role-mapping.asciidoc[]
|
||||
include::security/ssl.asciidoc[]
|
||||
include::security/tokens.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,39 @@
|
|||
[role="xpack"]
|
||||
[[security-api-clear-role-cache]]
|
||||
=== Clear roles cache API
|
||||
|
||||
Evicts roles from the native role cache.
|
||||
|
||||
==== Request
|
||||
|
||||
`POST /_xpack/security/role/<name>/_clear_cache`
|
||||
|
||||
==== Description
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`name`::
|
||||
(string) The name of the role.
|
||||
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
The clear roles cache API evicts roles from the native role cache. For example,
|
||||
to clear the cache for `my_admin_role`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /_xpack/security/role/my_admin_role/_clear_cache
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
[role="xpack"]
|
||||
[[security-api-put-role]]
|
||||
=== Create roles API
|
||||
|
||||
Adds roles in the native realm.
|
||||
|
||||
==== Request
|
||||
|
||||
`POST /_xpack/security/role/<name>` +
|
||||
|
||||
`PUT /_xpack/security/role/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
|
||||
The role API is generally the preferred way to manage roles, rather than using
|
||||
file-based role management. For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`name`::
|
||||
(string) The name of the role.
|
||||
|
||||
|
||||
==== Request Body
|
||||
|
||||
The following parameters can be specified in the body of a PUT or POST request
|
||||
and pertain to adding a role:
|
||||
|
||||
`cluster`:: (list) A list of cluster privileges. These privileges define the
|
||||
cluster level actions that users with this role are able to execute.
|
||||
|
||||
`indices`:: (list) A list of indices permissions entries.
|
||||
`field_security`::: (list) The document fields that the owners of the role have
|
||||
read access to. For more information, see
|
||||
{stack-ov}/field-and-document-access-control.html[Setting up field and document level security].
|
||||
`names` (required)::: (list) A list of indices (or index name patterns) to which the
|
||||
permissions in this entry apply.
|
||||
`privileges`(required)::: (list) The index level privileges that the owners of the role
|
||||
have on the specified indices.
|
||||
`query`::: A search query that defines the documents the owners of the role have
|
||||
read access to. A document within the specified indices must match this query in
|
||||
order for it to be accessible by the owners of the role.
|
||||
|
||||
`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
|
||||
that begin with `_` are reserved for system usage.
|
||||
|
||||
`run_as`:: (list) A list of users that the owners of this role can impersonate.
|
||||
For more information, see
|
||||
{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
|
||||
|
||||
For more information, see {stack-ov}/defining-roles.html[Defining roles].
|
||||
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
The following example adds a role called `my_admin_role`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /_xpack/security/role/my_admin_role
|
||||
{
|
||||
"cluster": ["all"],
|
||||
"indices": [
|
||||
{
|
||||
"names": [ "index1", "index2" ],
|
||||
"privileges": ["all"],
|
||||
"field_security" : { // optional
|
||||
"grant" : [ "title", "body" ]
|
||||
},
|
||||
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
|
||||
}
|
||||
],
|
||||
"run_as": [ "other_user" ], // optional
|
||||
"metadata" : { // optional
|
||||
"version" : 1
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
A successful call returns a JSON structure that shows whether the role has been
|
||||
created or updated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"role": {
|
||||
"created": true <1>
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
<1> When an existing role is updated, `created` is set to false.
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
[role="xpack"]
|
||||
[[security-api-delete-role]]
|
||||
=== Delete roles API
|
||||
|
||||
Removes roles in the native realm.
|
||||
|
||||
==== Request
|
||||
|
||||
`DELETE /_xpack/security/role/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
|
||||
The Roles API is generally the preferred way to manage roles, rather than using
|
||||
file-based role management. For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`name`::
|
||||
(string) The name of the role.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
The following example deletes a `my_admin_role` role:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_xpack/security/role/my_admin_role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:admin_role]
|
||||
|
||||
If the role is successfully deleted, the request returns `{"found": true}`.
|
||||
Otherwise, `found` is set to false.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"found" : true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
[role="xpack"]
|
||||
[[security-api-get-role]]
|
||||
=== Get roles API
|
||||
|
||||
Retrieves roles in the native realm.
|
||||
|
||||
==== Request
|
||||
|
||||
`GET /_xpack/security/role` +
|
||||
|
||||
`GET /_xpack/security/role/<name>` +
|
||||
|
||||
==== Description
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`name`::
|
||||
(string) The name of the role. You can specify multiple roles as a
|
||||
comma-separated list. If you do not specify this parameter, the API
|
||||
returns information about all roles.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
The following example retrieves information about the `my_admin_role` role in
|
||||
the native realm:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_xpack/security/role/my_admin_role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[setup:admin_role]
|
||||
|
||||
A successful call returns an array of roles with the JSON representation of the
|
||||
role. If the role is not defined in the native realm, the request returns 404.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"my_admin_role": {
|
||||
"cluster" : [ "all" ],
|
||||
"indices" : [
|
||||
{
|
||||
"names" : [ "index1", "index2" ],
|
||||
"privileges" : [ "all" ],
|
||||
"field_security" : {
|
||||
"grant" : [ "title", "body" ]}
|
||||
}
|
||||
],
|
||||
"applications" : [ ],
|
||||
"run_as" : [ "other_user" ],
|
||||
"metadata" : {
|
||||
"version" : 1
|
||||
},
|
||||
"transient_metadata": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
To retrieve all roles, omit the role name:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_xpack/security/role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
NOTE: If single role is requested, that role is returned as the response. When
|
||||
requesting multiple roles, an object is returned holding the found roles, each
|
||||
keyed by the relevant role name.
|
||||
|
|
@ -1,205 +1,9 @@
|
|||
[role="xpack"]
|
||||
[float]
|
||||
[[security-api-roles]]
|
||||
=== Role Management APIs
|
||||
=== Roles
|
||||
|
||||
The Roles API enables you to add, remove, and retrieve roles in the `native`
|
||||
realm.
|
||||
You can use the following APIs to add, remove, and retrieve roles in the native realm:
|
||||
|
||||
==== Request
|
||||
|
||||
`GET /_xpack/security/role` +
|
||||
|
||||
`GET /_xpack/security/role/<name>` +
|
||||
|
||||
`DELETE /_xpack/security/role/<name>` +
|
||||
|
||||
`POST /_xpack/security/role/<name>/_clear_cache` +
|
||||
|
||||
`POST /_xpack/security/role/<name>` +
|
||||
|
||||
`PUT /_xpack/security/role/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
|
||||
The Roles API is generally the preferred way to manage roles, rather than using
|
||||
file-based role management. For more information, see
|
||||
{xpack-ref}/authorization.html[Configuring Role-based Access Control].
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`name`::
|
||||
(string) The name of the role. If you do not specify this parameter, the
|
||||
Get Roles API returns information about all roles.
|
||||
|
||||
|
||||
==== Request Body
|
||||
|
||||
The following parameters can be specified in the body of a PUT or POST request
|
||||
and pertain to adding a role:
|
||||
|
||||
`cluster`:: (list) A list of cluster privileges. These privileges define the
|
||||
cluster level actions that users with this role are able to execute.
|
||||
|
||||
`indices`:: (list) A list of indices permissions entries.
|
||||
`field_security`::: (list) The document fields that the owners of the role have
|
||||
read access to. For more information, see
|
||||
{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
|
||||
`names` (required)::: (list) A list of indices (or index name patterns) to which the
|
||||
permissions in this entry apply.
|
||||
`privileges`(required)::: (list) The index level privileges that the owners of the role
|
||||
have on the specified indices.
|
||||
`query`::: A search query that defines the documents the owners of the role have
|
||||
read access to. A document within the specified indices must match this query in
|
||||
order for it to be accessible by the owners of the role.
|
||||
|
||||
`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
|
||||
that begin with `_` are reserved for system usage.
|
||||
|
||||
`run_as`:: (list) A list of users that the owners of this role can impersonate.
|
||||
For more information, see
|
||||
{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
|
||||
|
||||
For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
|
||||
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
|
||||
[[security-api-put-role]]
|
||||
To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
|
||||
endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /_xpack/security/role/my_admin_role
|
||||
{
|
||||
"cluster": ["all"],
|
||||
"indices": [
|
||||
{
|
||||
"names": [ "index1", "index2" ],
|
||||
"privileges": ["all"],
|
||||
"field_security" : { // optional
|
||||
"grant" : [ "title", "body" ]
|
||||
},
|
||||
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
|
||||
}
|
||||
],
|
||||
"run_as": [ "other_user" ], // optional
|
||||
"metadata" : { // optional
|
||||
"version" : 1
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
A successful call returns a JSON structure that shows whether the role has been
|
||||
created or updated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"role": {
|
||||
"created": true <1>
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
<1> When an existing role is updated, `created` is set to false.
|
||||
|
||||
[[security-api-get-role]]
|
||||
To retrieve a role from the `native` Security realm, issue a GET request to the
|
||||
`/_xpack/security/role/<rolename>` endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_xpack/security/role/my_admin_role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
A successful call returns an array of roles with the JSON representation of the
|
||||
role. If the role is not defined in the `native` realm, the request 404s.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"my_admin_role": {
|
||||
"cluster" : [ "all" ],
|
||||
"indices" : [ {
|
||||
"names" : [ "index1", "index2" ],
|
||||
"privileges" : [ "all" ],
|
||||
"field_security" : {
|
||||
"grant" : [ "title", "body" ]
|
||||
},
|
||||
"query" : "{\"match\": {\"title\": \"foo\"}}"
|
||||
} ],
|
||||
"applications" : [ ],
|
||||
"run_as" : [ "other_user" ],
|
||||
"metadata" : {
|
||||
"version" : 1
|
||||
},
|
||||
"transient_metadata": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
You can specify multiple roles as a comma-separated list. To retrieve all roles,
|
||||
omit the role name.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
# Retrieve roles "r1", "r2", and "my_admin_role"
|
||||
GET /_xpack/security/role/r1,r2,my_admin_role
|
||||
|
||||
# Retrieve all roles
|
||||
GET /_xpack/security/role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
NOTE: If single role is requested, that role is returned as the response. When
|
||||
requesting multiple roles, an object is returned holding the found roles, each
|
||||
keyed by the relevant role name.
|
||||
|
||||
[[security-api-delete-role]]
|
||||
To delete a role, submit a DELETE request to the `/_xpack/security/role/<rolename>`
|
||||
endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_xpack/security/role/my_admin_role
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
If the role is successfully deleted, the request returns `{"found": true}`.
|
||||
Otherwise, `found` is set to false.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"found" : true
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
[[security-api-clear-role-cache]]
|
||||
The Clear Roles Cache API evicts roles from the native role cache. To clear the
|
||||
cache for a role, submit a POST request `/_xpack/security/role/<rolename>/_clear_cache`
|
||||
endpoint:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /_xpack/security/role/my_admin_role/_clear_cache
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
|
||||
* <<security-api-clear-role-cache,Clear roles cache>>
|
||||
* <<security-api-get-role,Get roles>>
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.clear_cached_roles": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-clear-role-cache",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html",
|
||||
"methods": [ "POST" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role/{name}/_clear_cache",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.delete_role": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-delete-role",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role.html",
|
||||
"methods": [ "DELETE" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role/{name}",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.get_role": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-get-role",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role.html",
|
||||
"methods": [ "GET" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role/{name}",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.put_role": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-put-role",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html",
|
||||
"methods": [ "PUT", "POST" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/role/{name}",
|
||||
|
|
|
|||
Loading…
Reference in New Issue