[DOCS] Reformats the security APIs (#45124)
This commit is contained in:
Lisa Cawley
lcawl
parent
4b8ae97e9d
commit
00235bbecd
|
|
@ -5,23 +5,28 @@
|
|||
<titleabbrev>Authenticate</titleabbrev>
|
||||
++++
|
||||
|
||||
The Authenticate API enables you to submit a request with a basic auth header to
|
||||
Enables you to submit a request with a basic auth header to
|
||||
authenticate a user and retrieve information about the authenticated user.
|
||||
|
||||
|
||||
==== Request
|
||||
[[security-api-authenticate-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/_authenticate`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-authenticate-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
A successful call returns a JSON structure that shows user information such as their username, the roles that are
|
||||
assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user.
|
||||
|
||||
[[security-api-authenticate-response-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
If the user cannot be authenticated, this API returns a 401 status code.
|
||||
|
||||
==== Examples
|
||||
[[security-api-authenticate-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
To authenticate a user, submit a GET request to the
|
||||
`/_security/_authenticate` endpoint:
|
||||
|
|
|
|||
|
|
@ -7,14 +7,22 @@
|
|||
|
||||
Changes the passwords of users in the native realm and built-in users.
|
||||
|
||||
==== Request
|
||||
[[security-api-change-password-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/user/_password` +
|
||||
|
||||
`POST /_security/user/<username>/_password`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-change-password-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* Every user can change their own password. Users with the `manage_security`
|
||||
privilege can change passwords of other users.
|
||||
|
||||
[[security-api-change-password-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
You can use the <<security-api-put-user,create user API>> to update everything
|
||||
but a user's `username` and `password`. This API changes a user's password.
|
||||
|
|
@ -23,26 +31,23 @@ For more information about the native realm, see
|
|||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-change-password-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username`::
|
||||
(string) The user whose password you want to change. If you do not specify
|
||||
(Optional, string) The user whose password you want to change. If you do not specify
|
||||
this parameter, the password is changed for the current user.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-change-password-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`password` (required)::
|
||||
(string) The new password value.
|
||||
`password`::
|
||||
(Required, string) The new password value.
|
||||
|
||||
|
||||
==== Authorization
|
||||
|
||||
Every user can change their own password. Users with the `manage_security`
|
||||
privilege can change passwords of other users.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-change-password-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example updates the password for the `jacknich` user:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,36 +5,42 @@
|
|||
<titleabbrev>Clear cache</titleabbrev>
|
||||
++++
|
||||
|
||||
The clear cache API evicts users from the user cache. You can completely clear
|
||||
Evicts users from the user cache. You can completely clear
|
||||
the cache or evict specific users.
|
||||
|
||||
==== Request
|
||||
[[security-api-clear-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/realm/<realms>/_clear_cache` +
|
||||
|
||||
`POST /_security/realm/<realms>/_clear_cache?usernames=<usernames>`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-clear-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
User credentials are cached in memory on each node to avoid connecting to a
|
||||
remote authentication service or hitting the disk for every incoming request.
|
||||
There are realm settings that you can use to configure the user cache. For more
|
||||
information, see {xpack-ref}/controlling-user-cache.html[Controlling the User Cache].
|
||||
information, see
|
||||
{stack-ov}/controlling-user-cache.html[Controlling the user cache].
|
||||
|
||||
To evict roles from the role cache, see the
|
||||
<<security-api-clear-role-cache,Clear Roles Cache API>>.
|
||||
<<security-api-clear-role-cache,Clear roles cache API>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-clear-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`realms` (required)::
|
||||
(list) A comma-separated list of the realms to clear.
|
||||
`realms`::
|
||||
(Required, list) A comma-separated list of the realms to clear.
|
||||
|
||||
`usernames`::
|
||||
(list) A comma-separated list of the users to clear from the cache. If you
|
||||
do not specify this parameter, the API evicts all users from the user cache.
|
||||
(Optional, list) A comma-separated list of the users to clear from the cache.
|
||||
If you do not specify this parameter, the API evicts all users from the user
|
||||
cache.
|
||||
|
||||
==== Examples
|
||||
[[security-api-clear-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
For example, to evict all users cached by the `file` realm:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,30 +7,31 @@
|
|||
|
||||
Evicts roles from the native role cache.
|
||||
|
||||
==== Request
|
||||
[[security-api-clear-role-cache-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/role/<name>/_clear_cache`
|
||||
|
||||
==== Description
|
||||
[[security-api-clear-role-cache-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
[[security-api-clear-role-cache-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-clear-role-cache-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`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
|
||||
[[security-api-clear-role-cache-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The clear roles cache API evicts roles from the native role cache. For example,
|
||||
to clear the cache for `my_admin_role`:
|
||||
|
|
|
|||
|
|
@ -7,12 +7,19 @@
|
|||
|
||||
Creates an API key for access without requiring basic authentication.
|
||||
|
||||
==== Request
|
||||
[[security-api-create-api-key-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/api_key`
|
||||
`PUT /_security/api_key`
|
||||
|
||||
==== Description
|
||||
[[security-api-create-api-key-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
|
||||
[[security-api-create-api-key-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The API keys are created by the {es} API key service, which is automatically enabled
|
||||
when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
|
||||
|
|
@ -30,29 +37,31 @@ when you create the API keys.
|
|||
See <<api-key-service-settings>> for configuration settings related to API key
|
||||
service.
|
||||
|
||||
==== Request Body
|
||||
|
||||
[[security-api-create-api-key-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a POST or PUT request:
|
||||
|
||||
`name`::
|
||||
(string) Specifies the name for this API key.
|
||||
|
||||
`role_descriptors` (optional)::
|
||||
(array-of-role-descriptor) An array of role descriptors for this API key. This
|
||||
parameter is optional. When it is not specified or is an empty array, then the API key will have
|
||||
the permissions of the authenticated user. If you supply role descriptors, they must
|
||||
be a subset of the authenticated user's permissions. The structure of role descriptor is the
|
||||
same as the request for create role API. For more details, see
|
||||
`role_descriptors`::
|
||||
(Optional, array-of-role-descriptor) An array of role descriptors for this API
|
||||
key. This parameter is optional. When it is not specified or is an empty array,
|
||||
then the API key will have the permissions of the authenticated user. If you
|
||||
supply role descriptors, they must be a subset of the authenticated user's
|
||||
permissions. The structure of role descriptor is the same as the request for
|
||||
create role API. For more details, see
|
||||
<<security-api-roles,role management APIs>>.
|
||||
|
||||
`expiration`::
|
||||
(string) Optional expiration time for the API key. By default, API keys never expire.
|
||||
(Optional, string) Expiration time for the API key. By default, API keys never
|
||||
expire.
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
|
||||
==== Examples
|
||||
[[security-api-create-api-key-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example creates an API key:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,14 +7,21 @@
|
|||
|
||||
Creates and updates role mappings.
|
||||
|
||||
==== Request
|
||||
[[security-api-put-role-mapping-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/role_mapping/<name>` +
|
||||
|
||||
`PUT /_security/role_mapping/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-put-role-mapping-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-put-role-mapping-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
Role mappings define which roles are assigned to each user. Each mapping has
|
||||
_rules_ that identify users and a list of _roles_ that are
|
||||
|
|
@ -28,7 +35,8 @@ For more information, see
|
|||
{stack-ov}/mapping-roles.html[Mapping users and groups to roles].
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-put-role-mapping-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`name`::
|
||||
(string) The distinct name that identifies the role mapping. The name is
|
||||
|
|
@ -36,14 +44,15 @@ For more information, see
|
|||
not affect the behavior of the mapping in any way.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-put-role-mapping-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
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.
|
||||
`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
|
||||
|
|
@ -62,10 +71,10 @@ mapping rules.
|
|||
The format of these objects is defined below.
|
||||
_Exactly one of `roles` or `role_templates` must be specified_.
|
||||
|
||||
`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>>.
|
||||
`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>>.
|
||||
|
||||
==== Role Templates
|
||||
|
||||
|
|
@ -91,12 +100,8 @@ array of JSON strings for the role name(s).
|
|||
|
||||
The Examples section below demonstrates the use of templated role names.
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-put-role-mapping-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example assigns the "user" role to all users:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,27 +7,37 @@
|
|||
|
||||
Adds and updates roles in the native realm.
|
||||
|
||||
==== Request
|
||||
[[security-api-put-role-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/role/<name>` +
|
||||
|
||||
`PUT /_security/role/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-put-role-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
[[security-api-put-role-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
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
|
||||
[[security-api-put-role-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`name`::
|
||||
(string) The name of the role.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-put-role-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a PUT or POST request
|
||||
and pertain to adding a role:
|
||||
|
|
@ -67,14 +77,8 @@ For more information, see
|
|||
|
||||
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
|
||||
[[security-api-put-role-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example adds a role called `my_admin_role`:
|
||||
|
||||
|
|
|
|||
|
|
@ -9,14 +9,22 @@ Adds and updates users in the native realm. These users are commonly referred
|
|||
to as _native users_.
|
||||
|
||||
|
||||
==== Request
|
||||
[[security-api-put-user-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/user/<username>` +
|
||||
|
||||
`PUT /_security/user/<username>`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-put-user-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
|
||||
[[security-api-put-user-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
When updating a user, you can update everything but its `username` and `password`.
|
||||
To change a user's password, use the
|
||||
|
|
@ -25,10 +33,11 @@ To change a user's password, use the
|
|||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-put-user-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username` (required)::
|
||||
(string) An identifier for the user.
|
||||
`username`::
|
||||
(Required, string) An identifier for the user.
|
||||
+
|
||||
--
|
||||
[[username-validation]]
|
||||
|
|
@ -38,14 +47,16 @@ printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_bloc
|
|||
|
||||
--
|
||||
|
||||
==== Query Parameters
|
||||
[[security-api-put-user-query-params]]
|
||||
==== {api-query-parms-title}
|
||||
|
||||
`refresh`::
|
||||
(string) One of `true`, `false`, or `wait_for`.
|
||||
These values have the same meaning as in the <<docs-refresh, Index API>>,
|
||||
but the default value for this API (Put User) is `true`.
|
||||
|
||||
==== Request Body
|
||||
[[security-api-put-user-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a POST or PUT request:
|
||||
|
||||
|
|
@ -61,7 +72,7 @@ The following parameters can be specified in the body of a POST or PUT request:
|
|||
`metadata`::
|
||||
(object) Arbitrary metadata that you want to associate with the user.
|
||||
|
||||
`password` ::
|
||||
`password`::
|
||||
(string) The user's password. Passwords must be at least 6 characters long.
|
||||
+
|
||||
When adding a user, one of `password` or `password_hash` is required.
|
||||
|
|
@ -69,7 +80,7 @@ When updating an existing user, the password is optional, so that other
|
|||
fields on the user (such as their roles) may be updated without modifying
|
||||
the user's password.
|
||||
|
||||
`password_hash` ::
|
||||
`password_hash`::
|
||||
(string) A _hash_ of the user's password. This must be produced using the
|
||||
same hashing algorithm as has been configured for password storage. For more
|
||||
details, see the explanation of the
|
||||
|
|
@ -82,17 +93,14 @@ performance and/or confidentiality reasons.
|
|||
The `password` parameter and the `password_hash` parameter cannot be
|
||||
used in the same request.
|
||||
|
||||
`roles` (required)::
|
||||
(list) A set of roles the user has. The roles determine the user's access
|
||||
permissions. To create a user without any roles, specify an empty list: `[]`.
|
||||
`roles`::
|
||||
(Required, list) A set of roles the user has. The roles determine the user's
|
||||
access permissions. To create a user without any roles, specify an empty list:
|
||||
`[]`.
|
||||
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-put-user-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example creates a user `jacknich`:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,24 +8,13 @@
|
|||
Removes
|
||||
{stack-ov}/security-privileges.html#application-privileges[application privileges].
|
||||
|
||||
==== Request
|
||||
[[security-api-delete-privilege-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/privilege/<application>/<privilege>`
|
||||
|
||||
//==== Description
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`application` (required)::
|
||||
(string) The name of the application. Application privileges are always
|
||||
associated with exactly one application.
|
||||
|
||||
`privilege` (required)::
|
||||
(string) The name of the privilege.
|
||||
|
||||
// ==== Request Body
|
||||
|
||||
==== Authorization
|
||||
[[security-api-delete-privilege-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
To use this API, you must have either:
|
||||
|
||||
|
|
@ -33,7 +22,18 @@ To use this API, you must have either:
|
|||
- the _"Manage Application Privileges"_ global privilege for the application being referenced
|
||||
in the request
|
||||
|
||||
==== Examples
|
||||
[[security-api-delete-privilege-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`application`::
|
||||
(Required, string) The name of the application. Application privileges are
|
||||
always associated with exactly one application.
|
||||
|
||||
`privilege`::
|
||||
(Required, string) The name of the privilege.
|
||||
|
||||
[[security-api-delete-privilege-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example deletes the `read` application privilege from the
|
||||
`myapp` application:
|
||||
|
|
|
|||
|
|
@ -7,30 +7,33 @@
|
|||
|
||||
Removes role mappings.
|
||||
|
||||
==== Request
|
||||
[[security-api-delete-role-mapping-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/role_mapping/<name>`
|
||||
|
||||
==== Description
|
||||
[[security-api-delete-role-mapping-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-delete-role-mapping-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
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
|
||||
[[security-api-delete-role-mapping-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`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
|
||||
[[security-api-delete-role-mapping-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example delete a role mapping:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,32 +7,34 @@
|
|||
|
||||
Removes roles in the native realm.
|
||||
|
||||
==== Request
|
||||
[[security-api-delete-role-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/role/<name>`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-delete-role-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
|
||||
[[security-api-delete-role-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
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
|
||||
[[security-api-delete-role-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`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
|
||||
[[security-api-delete-role-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example deletes a `my_admin_role` role:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,28 +7,31 @@
|
|||
|
||||
Deletes users from the native realm.
|
||||
|
||||
==== Request
|
||||
[[security-api-delete-user-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/user/<username>`
|
||||
|
||||
==== Description
|
||||
[[security-api-delete-user-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-delete-user-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-delete-user-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username` (required)::
|
||||
(string) An identifier for the user.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
`username`::
|
||||
(Required, string) An identifier for the user.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-delete-user-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example deletes the user `jacknich`:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,12 +8,19 @@
|
|||
Disables users in the native realm.
|
||||
|
||||
|
||||
==== Request
|
||||
[[security-api-disable-user-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`PUT /_security/user/<username>/_disable`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-disable-user-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-disable-user-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
By default, when you create users, they are enabled. You can use this API to
|
||||
revoke a user's access to {es}. To re-enable a user, there is an
|
||||
|
|
@ -22,19 +29,15 @@ revoke a user's access to {es}. To re-enable a user, there is an
|
|||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-disable-user-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username` (required)::
|
||||
(string) An identifier for the user.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
`username`::
|
||||
(Required, string) An identifier for the user.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-disable-user-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example disables the user `jacknich`:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,12 +8,19 @@
|
|||
Enables users in the native realm.
|
||||
|
||||
|
||||
==== Request
|
||||
[[security-api-enable-user-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`PUT /_security/user/<username>/_enable`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-enable-user-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-enable-user-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
By default, when you create users, they are enabled. You can use this enable
|
||||
users API and the <<security-api-disable-user,disable users API>> to change that attribute.
|
||||
|
|
@ -21,19 +28,15 @@ users API and the <<security-api-disable-user,disable users API>> to change that
|
|||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-enable-user-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username` (required)::
|
||||
(string) An identifier for the user.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
`username`::
|
||||
(Required, string) An identifier for the user.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-enable-user-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example enables the user `jacknich`:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,43 +7,48 @@
|
|||
|
||||
Retrieves information for one or more API keys.
|
||||
|
||||
==== Request
|
||||
[[security-api-get-api-key-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/api_key`
|
||||
|
||||
==== Description
|
||||
[[security-api-get-api-key-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
The information for the API keys created by <<security-api-create-api-key,create API Key>> can be retrieved
|
||||
using this API.
|
||||
* To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
|
||||
==== Request Body
|
||||
[[security-api-get-api-key-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The information for the API keys created by
|
||||
<<security-api-create-api-key,create API Key>> can be retrieved using this API.
|
||||
|
||||
[[security-api-get-api-key-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the query parameters of a GET request and
|
||||
pertain to retrieving api keys:
|
||||
|
||||
`id` (optional)::
|
||||
(string) An API key id. This parameter cannot be used with any of `name`,
|
||||
`realm_name` or `username` are used.
|
||||
`id`::
|
||||
(Optional, string) An API key id. This parameter cannot be used with any of
|
||||
`name`, `realm_name` or `username` are used.
|
||||
|
||||
`name` (optional)::
|
||||
(string) An API key name. This parameter cannot be used with any of `id`,
|
||||
`realm_name` or `username` are used.
|
||||
`name`::
|
||||
(Optional, string) An API key name. This parameter cannot be used with any of
|
||||
`id`, `realm_name` or `username` are used.
|
||||
|
||||
`realm_name` (optional)::
|
||||
(string) The name of an authentication realm. This parameter cannot be used with
|
||||
`realm_name`::
|
||||
(Optional, string) The name of an authentication realm. This parameter cannot be
|
||||
used with either `id` or `name`.
|
||||
|
||||
`username`::
|
||||
(Optional, string) The username of a user. This parameter cannot be used with
|
||||
either `id` or `name`.
|
||||
|
||||
`username` (optional)::
|
||||
(string) The username of a user. This parameter cannot be used with either `id`
|
||||
or `name`.
|
||||
|
||||
NOTE: While all parameters are optional, at least one of them is required.
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-api-key-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
If you create an API key as follows:
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,8 @@
|
|||
Retrieves
|
||||
{stack-ov}/security-privileges.html#application-privileges[application privileges].
|
||||
|
||||
==== Request
|
||||
[[security-api-get-privileges-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/privilege` +
|
||||
|
||||
|
|
@ -17,27 +18,8 @@ Retrieves
|
|||
`GET /_security/privilege/<application>/<privilege>`
|
||||
|
||||
|
||||
==== Description
|
||||
|
||||
To check a user's application privileges, use the
|
||||
<<security-api-has-privileges,has privileges API>>.
|
||||
|
||||
|
||||
==== Path Parameters
|
||||
|
||||
`application`::
|
||||
(string) The name of the application. Application privileges are always
|
||||
associated with exactly one application.
|
||||
If you do not specify this parameter, the API returns information about all
|
||||
privileges for all applications.
|
||||
|
||||
`privilege`::
|
||||
(string) The name of the privilege. If you do not specify this parameter, the
|
||||
API returns information about all privileges for the requested application.
|
||||
|
||||
//==== Request Body
|
||||
|
||||
==== Authorization
|
||||
[[security-api-get-privileges-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
To use this API, you must have either:
|
||||
|
||||
|
|
@ -45,7 +27,30 @@ To use this API, you must have either:
|
|||
- the _"Manage Application Privileges"_ global privilege for the application being referenced
|
||||
in the request
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-privileges-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
To check a user's application privileges, use the
|
||||
<<security-api-has-privileges,has privileges API>>.
|
||||
|
||||
|
||||
[[security-api-get-privileges-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`application`::
|
||||
(Optional, string) The name of the application. Application privileges are
|
||||
always associated with exactly one application. If you do not specify this
|
||||
parameter, the API returns information about all privileges for all
|
||||
applications.
|
||||
|
||||
`privilege`::
|
||||
(Optional, string) The name of the privilege. If you do not specify this
|
||||
parameter, the API returns information about all privileges for the requested
|
||||
application.
|
||||
|
||||
|
||||
[[security-api-get-privileges-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example retrieves information about the `read` privilege for the
|
||||
`app01` application:
|
||||
|
|
|
|||
|
|
@ -10,37 +10,44 @@ Retrieves the list of
|
|||
{stack-ov}/security-privileges.html#privileges-list-indices[index privileges] that are
|
||||
available in this version of {es}.
|
||||
|
||||
==== Request
|
||||
[[security-api-get-builtin-privileges-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/privilege/_builtin`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-get-builtin-privileges-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
This API retrieves the set of cluster and index privilege names that are available in the
|
||||
version of {es} that is being queried.
|
||||
* To use this API, you must have - the `manage_security` cluster privilege
|
||||
(or a greater privilege such as `all`).
|
||||
|
||||
[[security-api-get-builtin-privileges-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
This API retrieves the set of cluster and index privilege names that are
|
||||
available in the version of {es} that is being queried.
|
||||
|
||||
To check whether a user has particular privileges, use the
|
||||
<<security-api-has-privileges,has privileges API>>.
|
||||
|
||||
==== Results
|
||||
|
||||
[[security-api-get-builtin-privileges-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
The response is an object with two fields:
|
||||
|
||||
`cluster`:: (array of string) The list of
|
||||
{stack-ov}/security-privileges.html#privileges-list-cluster[cluster privileges] that are
|
||||
understood by this version of {es}
|
||||
{stack-ov}/security-privileges.html#privileges-list-cluster[cluster privileges]
|
||||
that are understood by this version of {es}
|
||||
|
||||
`index`:: (array of string) The list of
|
||||
{stack-ov}/security-privileges.html#privileges-list-indices[index privileges] that are
|
||||
understood by this version of {es}
|
||||
{stack-ov}/security-privileges.html#privileges-list-indices[index privileges]
|
||||
that are understood by this version of {es}
|
||||
|
||||
==== Authorization
|
||||
|
||||
To use this API, you must have - the `manage_security` cluster privilege
|
||||
(or a greater privilege such as `all`)
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-builtin-privileges-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example retrieves the names of all builtin privileges:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,45 +7,51 @@
|
|||
|
||||
Retrieves role mappings.
|
||||
|
||||
==== Request
|
||||
[[security-api-get-role-mapping-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/role_mapping` +
|
||||
|
||||
`GET /_security/role_mapping/<name>`
|
||||
|
||||
==== Description
|
||||
[[security-api-get-role-mapping-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
[[security-api-get-role-mapping-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
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
|
||||
[[security-api-get-role-mapping-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`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
|
||||
(Optional, 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
|
||||
[[security-api-get-role-mapping-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
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>>.
|
||||
|
||||
[[security-api-get-role-mapping-response-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
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
|
||||
[[security-api-get-role-mapping-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example retrieves information about the `mapping1` role mapping:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,33 +7,46 @@
|
|||
|
||||
Retrieves roles in the native realm.
|
||||
|
||||
==== Request
|
||||
[[security-api-get-role-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/role` +
|
||||
|
||||
`GET /_security/role/<name>` +
|
||||
|
||||
==== Description
|
||||
[[security-api-get-role-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
|
||||
[[security-api-get-role-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-get-role-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`name`::
|
||||
(string) The name of the role. You can specify multiple roles as a
|
||||
(Optional, 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.
|
||||
|
||||
[[security-api-get-role-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
//==== Request Body
|
||||
A successful call returns an array of roles with the JSON representation of the
|
||||
role.
|
||||
|
||||
==== Authorization
|
||||
[[security-api-get-role-response-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster
|
||||
privilege.
|
||||
If the role is not defined in the native realm, the request returns 404.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-role-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example retrieves information about the `my_admin_role` role in
|
||||
the native realm:
|
||||
|
|
@ -45,9 +58,6 @@ GET /_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]
|
||||
--------------------------------------------------
|
||||
{
|
||||
|
|
@ -84,6 +94,3 @@ GET /_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.
|
||||
|
|
|
|||
|
|
@ -7,11 +7,14 @@
|
|||
|
||||
Creates a bearer token for access without requiring basic authentication.
|
||||
|
||||
==== Request
|
||||
[[security-api-get-token-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/oauth2/token`
|
||||
|
||||
==== Description
|
||||
|
||||
[[security-api-get-token-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The tokens are created by the {es} Token Service, which is automatically enabled
|
||||
when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
|
||||
|
|
@ -35,7 +38,8 @@ If you want to invalidate a token immediately, you can do so by using the
|
|||
<<security-api-invalidate-token,invalidate token API>>.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-get-token-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a POST request and
|
||||
pertain to creating a token:
|
||||
|
|
@ -71,7 +75,8 @@ supported grant type.
|
|||
grant type, this parameter is required. This parameter is not valid with any
|
||||
other supported grant type.
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-token-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example obtains a token using the `client_credentials` grant type,
|
||||
which simply creates a token as the authenticated user:
|
||||
|
|
|
|||
|
|
@ -8,31 +8,46 @@
|
|||
Retrieves information about users in the native realm and built-in users.
|
||||
|
||||
|
||||
==== Request
|
||||
[[security-api-get-user-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/user` +
|
||||
|
||||
`GET /_security/user/<username>`
|
||||
|
||||
==== Description
|
||||
[[security-api-get-user-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
|
||||
|
||||
[[security-api-get-user-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For more information about the native realm, see
|
||||
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||||
|
||||
==== Path Parameters
|
||||
[[security-api-get-user-path-params]]
|
||||
==== {api-path-parms-title}
|
||||
|
||||
`username`::
|
||||
(string) An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves
|
||||
information about all users.
|
||||
(Optional, string) An identifier for the user. You can specify multiple
|
||||
usernames as a comma-separated list. If you omit this parameter, the API
|
||||
retrieves information about all users.
|
||||
|
||||
//==== Request Body
|
||||
[[security-api-get-user-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
==== Authorization
|
||||
A successful call returns an array of users with the JSON representation of the
|
||||
users. Note that user passwords are not included.
|
||||
|
||||
To use this API, you must have at least the `manage_security` cluster privilege.
|
||||
[[security-api-get-user-response-codes]]
|
||||
==== {api-response-codes-title}
|
||||
|
||||
If the user is not defined in the `native` realm, the request 404s.
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-user-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
To retrieve a native user, submit a GET request to the `/_security/user/<username>`
|
||||
endpoint:
|
||||
|
|
@ -44,9 +59,6 @@ GET /_security/user/jacknich
|
|||
// CONSOLE
|
||||
// TEST[setup:jacknich_user]
|
||||
|
||||
A successful call returns an array of users with the JSON representation of the
|
||||
user. Note that user passwords are not included.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
|
|
@ -65,8 +77,6 @@ user. Note that user passwords are not included.
|
|||
// CONSOLE
|
||||
// TESTRESPONSE
|
||||
|
||||
If the user is not defined in the `native` realm, the request 404s.
|
||||
|
||||
Omit the username to retrieve all users:
|
||||
|
||||
[source,js]
|
||||
|
|
|
|||
|
|
@ -9,12 +9,22 @@
|
|||
The `has_privileges` API allows you to determine whether the logged in user has
|
||||
a specified list of privileges.
|
||||
|
||||
==== Request
|
||||
[[security-api-has-privileges-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_security/user/_has_privileges`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-has-privileges-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* All users can use this API, but only to determine their own privileges.
|
||||
To check the privileges of other users, you must use the run as feature. For
|
||||
more information, see
|
||||
{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
|
||||
|
||||
[[security-api-has-privileges-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For a list of the privileges that you can specify in this API,
|
||||
see {stack-ov}/security-privileges.html[Security privileges].
|
||||
|
|
@ -22,8 +32,8 @@ see {stack-ov}/security-privileges.html[Security privileges].
|
|||
A successful call returns a JSON structure that shows whether each specified
|
||||
privilege is assigned to the user.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-has-privileges-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`cluster`:: (list) A list of the cluster privileges that you want to check.
|
||||
|
||||
|
|
@ -47,15 +57,9 @@ actions that are granted by those privileges
|
|||
`resources`::: (list) A list of resource names against which the privileges
|
||||
should be checked
|
||||
|
||||
==== Authorization
|
||||
|
||||
All users can use this API, but only to determine their own privileges.
|
||||
To check the privileges of other users, you must use the run as feature. For
|
||||
more information, see
|
||||
{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-has-privileges-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example checks whether the current user has a specific set of
|
||||
cluster, index, and application privileges:
|
||||
|
|
|
|||
|
|
@ -7,43 +7,57 @@
|
|||
|
||||
Invalidates one or more API keys.
|
||||
|
||||
==== Request
|
||||
[[security-api-invalidate-api-key-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/api_key`
|
||||
|
||||
==== Description
|
||||
[[security-api-invalidate-api-key-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
|
||||
[[security-api-invalidate-api-key-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The API keys created by <<security-api-create-api-key,create API Key>> can be
|
||||
invalidated using this API.
|
||||
|
||||
==== Request Body
|
||||
|
||||
[[security-api-invalidate-api-key-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a DELETE request and
|
||||
pertain to invalidating api keys:
|
||||
|
||||
`id` (optional)::
|
||||
(string) An API key id. This parameter cannot be used with any of `name`,
|
||||
`realm_name` or `username` are used.
|
||||
`id`::
|
||||
(Optional, string) An API key id. This parameter cannot be used with any of
|
||||
`name`, `realm_name` or `username` are used.
|
||||
|
||||
`name` (optional)::
|
||||
(string) An API key name. This parameter cannot be used with any of `id`,
|
||||
`realm_name` or `username` are used.
|
||||
`name`::
|
||||
(Optional, string) An API key name. This parameter cannot be used with any of
|
||||
`id`, `realm_name` or `username` are used.
|
||||
|
||||
`realm_name` (optional)::
|
||||
(string) The name of an authentication realm. This parameter cannot be used with
|
||||
`realm_name`::
|
||||
(Optional, string) The name of an authentication realm. This parameter cannot be
|
||||
used with either `id` or `name`.
|
||||
|
||||
`username`::
|
||||
(Optional, string) The username of a user. This parameter cannot be used with
|
||||
either `id` or `name`.
|
||||
|
||||
`username` (optional)::
|
||||
(string) The username of a user. This parameter cannot be used with either
|
||||
`id` or `name`.
|
||||
|
||||
NOTE: While all parameters are optional, at least one of them is required.
|
||||
|
||||
==== Authorization
|
||||
[[security-api-invalidate-api-key-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
To use this API, you must have at least the `manage_api_key` cluster privilege.
|
||||
A successful call returns a JSON structure that contains the ids of the API keys
|
||||
that were invalidated, the ids of the API keys that had already been invalidated,
|
||||
and potentially a list of errors encountered while invalidating specific api
|
||||
keys.
|
||||
|
||||
==== Examples
|
||||
[[security-api-invalidate-api-key-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
If you create an API key as follows:
|
||||
|
||||
|
|
@ -71,7 +85,8 @@ API key information. For example:
|
|||
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
||||
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
|
||||
|
||||
The following example invalidates the API key identified by specified `id` immediately:
|
||||
The following example invalidates the API key identified by specified `id`
|
||||
immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -84,7 +99,8 @@ DELETE /_security/api_key
|
|||
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
||||
// TEST[continued]
|
||||
|
||||
The following example invalidates the API key identified by specified `name` immediately:
|
||||
The following example invalidates the API key identified by specified `name`
|
||||
immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -136,10 +152,6 @@ DELETE /_security/api_key
|
|||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
A successful call returns a JSON structure that contains the ids of the API keys that were invalidated, the ids
|
||||
of the API keys that had already been invalidated, and potentially a list of errors encountered while invalidating
|
||||
specific api keys.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
|
|
@ -173,8 +185,8 @@ specific api keys.
|
|||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
<1> The ids of the API keys that were invalidated as part of this request.
|
||||
<2> The ids of the API keys that were already invalidated.
|
||||
<1> The IDs of the API keys that were invalidated as part of this request.
|
||||
<2> The IDs of the API keys that were already invalidated.
|
||||
<3> The number of errors that were encountered when invalidating the API keys.
|
||||
<4> Details about these errors. This field is not present in the response when
|
||||
`error_count` is 0.
|
||||
|
|
|
|||
|
|
@ -7,11 +7,13 @@
|
|||
|
||||
Invalidates one or more access tokens or refresh tokens.
|
||||
|
||||
==== Request
|
||||
[[security-api-invalidate-token-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`DELETE /_security/oauth2/token`
|
||||
|
||||
==== Description
|
||||
[[security-api-invalidate-token-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The access tokens returned by the <<security-api-get-token,get token API>> have a
|
||||
finite period of time for which they are valid and after that time period, they
|
||||
|
|
@ -25,34 +27,43 @@ only valid for 24 hours. They can also be used exactly once.
|
|||
If you want to invalidate one or more access or refresh tokens immediately, use
|
||||
this invalidate token API.
|
||||
|
||||
|
||||
==== Request Body
|
||||
[[security-api-invalidate-token-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of a DELETE request and
|
||||
pertain to invalidating tokens:
|
||||
|
||||
`token` (optional)::
|
||||
(string) An access token. This parameter cannot be used any of `refresh_token`,
|
||||
`realm_name` or `username` are used.
|
||||
`token`::
|
||||
(Optional, string) An access token. This parameter cannot be used any of
|
||||
`refresh_token`, `realm_name` or `username` are used.
|
||||
|
||||
`refresh_token` (optional)::
|
||||
(string) A refresh token. This parameter cannot be used any of `refresh_token`,
|
||||
`realm_name` or `username` are used.
|
||||
`refresh_token`::
|
||||
(Optional, string) A refresh token. This parameter cannot be used any of
|
||||
`refresh_token`, `realm_name` or `username` are used.
|
||||
|
||||
`realm_name` (optional)::
|
||||
(string) The name of an authentication realm. This parameter cannot be used with
|
||||
either `refresh_token` or `token`.
|
||||
`realm_name`::
|
||||
(Optional, string) The name of an authentication realm. This parameter cannot be
|
||||
used with either `refresh_token` or `token`.
|
||||
|
||||
`username` (optional)::
|
||||
(string) The username of a user. This parameter cannot be used with either
|
||||
`refresh_token` or `token`
|
||||
`username`::
|
||||
(Optional, string) The username of a user. This parameter cannot be used with
|
||||
either `refresh_token` or `token`
|
||||
|
||||
NOTE: While all parameters are optional, at least one of them is required. More
|
||||
specifically, either one of `token` or `refresh_token` parameters is required.
|
||||
If none of these two are specified, then `realm_name` and/or `username` need to
|
||||
be specified.
|
||||
|
||||
==== Examples
|
||||
|
||||
[[security-api-invalidate-token-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
A successful call returns a JSON structure that contains the number of tokens
|
||||
that were invalidated, the number of tokens that had already been invalidated,
|
||||
and potentially a list of errors encountered while invalidating specific tokens.
|
||||
|
||||
[[security-api-invalidate-token-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
For example, if you create a token using the `client_credentials` grant type as
|
||||
follows:
|
||||
|
|
@ -178,10 +189,6 @@ DELETE /_security/oauth2/token
|
|||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
A successful call returns a JSON structure that contains the number of tokens
|
||||
that were invalidated, the number of tokens that had already been invalidated,
|
||||
and potentially a list of errors encountered while invalidating specific tokens.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
|
|
|
|||
|
|
@ -1,45 +1,61 @@
|
|||
[role="xpack"]
|
||||
[[security-api-oidc-authenticate]]
|
||||
=== OpenID Connect authenticate API
|
||||
|
||||
=== OpenID Connect Authenticate API
|
||||
Submits the response to an oAuth 2.0 authentication request for consumption from
|
||||
{es}. Upon successful validation, {es} will respond with an {es} internal Access
|
||||
Token and Refresh Token that can be subsequently used for authentication.
|
||||
|
||||
Submits the response to an oAuth 2.0 authentication request for consumption from {es}. Upon successful validation, {es}
|
||||
will respond with an {es} internal Access Token and Refresh Token that can be subsequently used for authentication. This
|
||||
API endpoint basically exchanges successful OpenID Connect Authentication responses for {es} access and refresh tokens
|
||||
to be used for authentication.
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
|
||||
are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
|
||||
custom web applications or other clients. See also
|
||||
<<security-api-oidc-prepare-authentication,OpenID Connect Prepare Authentication API>> and
|
||||
<<security-api-oidc-logout,OpenID Connect Logout API>>
|
||||
|
||||
==== Request
|
||||
[[security-api-oidc-authenticate-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/oidc/authenticate`
|
||||
|
||||
==== Request Body
|
||||
//[[security-api-oidc-authenticate-prereqs]]
|
||||
//==== {api-prereq-title}
|
||||
|
||||
[[security-api-oidc-authenticate-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
This API endpoint basically exchanges successful OpenID Connect Authentication
|
||||
responses for {es} access and refresh tokens to be used for authentication.
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the
|
||||
OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
|
||||
OpenID Connect based authentication, but can also be used by other, custom web
|
||||
applications or other clients. See also
|
||||
<<security-api-oidc-prepare-authentication,OpenID Connect prepare authentication API>>
|
||||
and <<security-api-oidc-logout,OpenID Connect logout API>>
|
||||
|
||||
[[security-api-oidc-authenticate-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`redirect_uri`::
|
||||
The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request, after a
|
||||
successful authentication. This URL is expected to be provided as-is (URL encoded), taken from the body of the response
|
||||
or as the value of a `Location` header in the response from the OpenID Connect Provider.
|
||||
The URL to which the OpenID Connect Provider redirected the User Agent in
|
||||
response to an authentication request, after a successful authentication. This
|
||||
URL is expected to be provided as-is (URL encoded), taken from the body of the
|
||||
response or as the value of a `Location` header in the response from the OpenID
|
||||
Connect Provider.
|
||||
|
||||
`state`::
|
||||
String value used to maintain state between the authentication request and the response. This value needs to be the same
|
||||
as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
|
||||
String value used to maintain state between the authentication request and the
|
||||
response. This value needs to be the same as the one that was provided to the
|
||||
call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
|
||||
and included in the response to that call.
|
||||
|
||||
`nonce`::
|
||||
String value used to associate a Client session with an ID Token, and to mitigate replay attacks. This value needs to be
|
||||
the same as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
|
||||
and included in the response to that call.
|
||||
String value used to associate a Client session with an ID Token and to mitigate
|
||||
replay attacks. This value needs to be the same as the one that was provided to
|
||||
the call to `/_security/oidc/prepare` earlier, or the one that was generated by
|
||||
{es} and included in the response to that call.
|
||||
|
||||
==== Examples
|
||||
[[security-api-oidc-authenticate-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example request exchanges the response that was returned from the OpenID Connect Provider after a successful
|
||||
authentication, for an {es} access token and refresh token to be used in subsequent requests. This example is from an
|
||||
authentication that uses the authorization code grant flow.
|
||||
The following example request exchanges the response that was returned from the
|
||||
OpenID Connect Provider after a successful authentication, for an {es} access
|
||||
token and refresh token to be used in subsequent requests. This example is from
|
||||
an authentication that uses the authorization code grant flow.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -53,8 +69,9 @@ POST /_security/oidc/authenticate
|
|||
// CONSOLE
|
||||
// TEST[catch:unauthorized]
|
||||
|
||||
The following example output contains the access token that was generated in response, the amount of time (in
|
||||
seconds) that the token expires in, the type, and the refresh token:
|
||||
The following example output contains the access token that was generated in
|
||||
response, the amount of time (in seconds) that the token expires in, the type,
|
||||
and the refresh token:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -1,32 +1,42 @@
|
|||
[role="xpack"]
|
||||
[[security-api-oidc-logout]]
|
||||
=== OpenID Connect logout API
|
||||
|
||||
=== OpenID Connect Logout API
|
||||
Submits a request to invalidate a refresh token and an access token that was
|
||||
generated as a response to a call to `/_security/oidc/authenticate`.
|
||||
|
||||
Submits a request to invalidate a refresh token and an access token that was generated as a response to a call to
|
||||
`/_security/oidc/authenticate`. If the OpenID Connect authentication realm in {es} is accordingly configured, the
|
||||
response to this call will contain a URI pointing to the End Session Endpoint of the OpenID Connect Provider in
|
||||
order to perform Single Logout
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
|
||||
are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
|
||||
custom web applications or other clients. See also <<security-api-oidc-authenticate,OpenID Connect Authenticate API>>
|
||||
and <<security-api-oidc-prepare-authentication,OpenID Connect Prepare Authentication API>>
|
||||
|
||||
==== Request
|
||||
[[security-api-oidc-logout-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/oidc/logout`
|
||||
|
||||
==== Request Body
|
||||
[[security-api-oidc-logout-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
If the OpenID Connect authentication realm in {es} is accordingly configured,
|
||||
the response to this call will contain a URI pointing to the End Session
|
||||
Endpoint of the OpenID Connect Provider in order to perform Single Logout.
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the
|
||||
OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
|
||||
OpenID Connect based authentication, but can also be used by other, custom web
|
||||
applications or other clients. See also
|
||||
<<security-api-oidc-authenticate,OpenID Connect authenticate API>>
|
||||
and
|
||||
<<security-api-oidc-prepare-authentication,OpenID Connect prepare authentication API>>.
|
||||
|
||||
[[security-api-oidc-logout-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
`access_token`::
|
||||
The value of the access token to be invalidated as part of the logout.
|
||||
|
||||
`refresh_token`::
|
||||
The value of the refresh token to be invalidated as part of the logout. (Optional)
|
||||
(Optional) The value of the refresh token to be invalidated as part of the logout.
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-oidc-logout-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example performs logout
|
||||
|
||||
|
|
@ -41,8 +51,9 @@ POST /_security/oidc/logout
|
|||
// CONSOLE
|
||||
// TEST[catch:unauthorized]
|
||||
|
||||
The following example output of the response contains the URI pointing to the End Session Endpoint of the
|
||||
OpenID Connect Provider with all the parameters of the Logout Request, as HTTP GET parameters
|
||||
The following example output of the response contains the URI pointing to the
|
||||
End Session Endpoint of the OpenID Connect Provider with all the parameters of
|
||||
the Logout Request, as HTTP GET parameters:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -1,53 +1,69 @@
|
|||
[role="xpack"]
|
||||
[[security-api-oidc-prepare-authentication]]
|
||||
|
||||
=== OpenID Connect Prepare Authentication API
|
||||
|
||||
Creates an oAuth 2.0 authentication request as a URL string based on the configuration of the respective
|
||||
OpenID Connect authentication realm in {es}. The response of this API is a URL pointing to the Authorization Endpoint
|
||||
of the configured OpenID Connect Provider and can be used to redirect the browser of the user in order to continue
|
||||
the authentication process.
|
||||
Creates an oAuth 2.0 authentication request as a URL string based on the
|
||||
configuration of the respective OpenID Connect authentication realm in {es}.
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
|
||||
are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
|
||||
custom web applications or other clients. See also <<security-api-oidc-authenticate,OpenID Connect Authenticate API>>
|
||||
and <<security-api-oidc-logout,OpenID Connect Logout API>>
|
||||
|
||||
==== Request
|
||||
[[security-api-oidc-prepare-authentication-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/oidc/prepare`
|
||||
|
||||
//[[security-api-oidc-prepare-authentication-prereqs]]
|
||||
//==== {api-prereq-title}
|
||||
|
||||
==== Request Body
|
||||
[[security-api-oidc-prepare-authentication-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The response of this API is a URL pointing to the Authorization Endpoint of the
|
||||
configured OpenID Connect Provider and can be used to redirect the browser of
|
||||
the user in order to continue the authentication process.
|
||||
|
||||
{es} exposes all the necessary OpenID Connect related functionality via the
|
||||
OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
|
||||
OpenID Connect based authentication, but can also be used by other, custom web
|
||||
applications or other clients. See also
|
||||
<<security-api-oidc-authenticate,OpenID Connect authenticate API>>
|
||||
and <<security-api-oidc-logout,OpenID Connect logout API>>.
|
||||
|
||||
[[security-api-oidc-prepare-authentication-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The following parameters can be specified in the body of the request:
|
||||
|
||||
`realm`::
|
||||
The name of the OpenID Connect realm in {es} the configuration of which should be used in order to
|
||||
generate the authentication request. Cannot be specified when `iss` is specified.
|
||||
The name of the OpenID Connect realm in {es} the configuration of which should
|
||||
be used in order to generate the authentication request. Cannot be specified
|
||||
when `iss` is specified.
|
||||
|
||||
`state`::
|
||||
String value used to maintain state between the authentication request and the response, typically used
|
||||
as a Cross-Site Request Forgery mitigation. If the caller of the API doesn't provide a value, {es} will
|
||||
generate one with sufficient entropy itself and return it in the response.
|
||||
String value used to maintain state between the authentication request and the
|
||||
response, typically used as a Cross-Site Request Forgery mitigation. If the
|
||||
caller of the API doesn't provide a value, {es} will generate one with
|
||||
sufficient entropy itself and return it in the response.
|
||||
|
||||
`nonce`::
|
||||
String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
|
||||
If the caller of the API doesn't provide a value, {es} will generate one with sufficient entropy itself
|
||||
and return it in the response.
|
||||
String value used to associate a Client session with an ID Token and to mitigate
|
||||
replay attacks. If the caller of the API doesn't provide a value, {es} will
|
||||
generate one with sufficient entropy itself and return it in the response.
|
||||
|
||||
`issuer`::
|
||||
In the case of a 3rd Party initiated Single Sign On, this is the Issuer Identifier for the OP that the RP is
|
||||
to send the Authentication Request to. Cannot be specified when `realm` is specified.
|
||||
In the case of a 3rd Party initiated Single Sign On, this is the Issuer
|
||||
Identifier for the OP that the RP is to send the Authentication Request to.
|
||||
Cannot be specified when `realm` is specified.
|
||||
|
||||
`login_hint`::
|
||||
In the case of a 3rd Party initiated Single Sign On, a string value to be included in the authentication
|
||||
request, as the `login_hint` parameter. This parameter is not valid when `realm` is specified
|
||||
In the case of a 3rd Party initiated Single Sign On, a string value to be
|
||||
included in the authentication request, as the `login_hint` parameter. This
|
||||
parameter is not valid when `realm` is specified
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-oidc-prepare-authentication-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example generates an authentication request for the OpenID Connect Realm `oidc1`
|
||||
The following example generates an authentication request for the OpenID Connect
|
||||
Realm `oidc1`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -57,8 +73,9 @@ POST /_security/oidc/prepare
|
|||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the
|
||||
OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
|
||||
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
|
||||
the Authentication Request, as HTTP GET parameters:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -71,8 +88,9 @@ OpenID Connect Provider with all the parameters of the Authentication Request, a
|
|||
// TESTRESPONSE[s/4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I/\$\{body.state\}/]
|
||||
// TESTRESPONSE[s/WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM/\$\{body.nonce\}/]
|
||||
|
||||
The following example generates an authentication request for the OpenID Connect Realm `oidc1`, where the
|
||||
values for the state and the nonce have been generated by the client
|
||||
The following example generates an authentication request for the OpenID Connect
|
||||
Realm `oidc1`, where the values for the state and the nonce have been generated
|
||||
by the client:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -85,8 +103,8 @@ POST /_security/oidc/prepare
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the
|
||||
OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
|
||||
the Authentication Request, as HTTP GET parameters:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -98,8 +116,9 @@ OpenID Connect Provider with all the parameters of the Authentication Request, a
|
|||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
The following example generates an authentication request for a 3rd party initiated single sign on, specifying the
|
||||
issuer that should be used for matching the appropriate OpenID Connect Authentication realm
|
||||
The following example generates an authentication request for a 3rd party
|
||||
initiated single sign on, specifying the issuer that should be used for matching
|
||||
the appropriate OpenID Connect Authentication realm:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -111,8 +130,8 @@ POST /_security/oidc/prepare
|
|||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the
|
||||
OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
|
||||
The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
|
||||
the Authentication Request, as HTTP GET parameters:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -8,14 +8,25 @@
|
|||
Adds or updates
|
||||
{stack-ov}/security-privileges.html#application-privileges[application privileges].
|
||||
|
||||
==== Request
|
||||
[[security-api-put-privileges-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`POST /_security/privilege` +
|
||||
|
||||
`PUT /_security/privilege`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-put-privileges-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
To use this API, you must have either:
|
||||
|
||||
- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
|
||||
- the _"Manage Application Privileges"_ global privilege for the application
|
||||
being referenced in the request
|
||||
|
||||
[[security-api-put-privileges-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
This API creates or updates privileges. To remove privileges, use the
|
||||
<<security-api-delete-privilege,delete application privilege API>>.
|
||||
|
|
@ -26,7 +37,8 @@ For more information, see
|
|||
To check a user's application privileges, use the
|
||||
<<security-api-has-privileges,has privileges API>>.
|
||||
|
||||
==== Request Body
|
||||
[[security-api-put-privileges-request-body]]
|
||||
==== {api-request-body-title}
|
||||
|
||||
The body is a JSON object where the names of the fields are the application
|
||||
names and the value of each field is an object. The fields in this inner
|
||||
|
|
@ -43,7 +55,7 @@ that begin with `_` are reserved for system usage.
|
|||
[[security-api-app-privileges-validation]]
|
||||
==== Validation
|
||||
|
||||
Application Names::
|
||||
Application names::
|
||||
Application names are formed from a _prefix_, with an optional _suffix_ that
|
||||
conform to the following rules:
|
||||
* The prefix must begin with a lowercase ASCII letter
|
||||
|
|
@ -54,23 +66,22 @@ Application Names::
|
|||
`\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`
|
||||
* No part of the name can contain whitespace.
|
||||
|
||||
Privilege Names::
|
||||
Privilege names::
|
||||
Privilege names must begin with a lowercase ASCII letter and must contain
|
||||
only ASCII letters and digits along with the characters `_`, `-` and `.`
|
||||
|
||||
Action Names::
|
||||
Action names::
|
||||
Action names can contain any number of printable ASCII characters and must
|
||||
contain at least one of the following characters: `/` `*`, `:`
|
||||
|
||||
==== Authorization
|
||||
[[security-api-put-privileges-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
To use this API, you must have either:
|
||||
A successful call returns a JSON structure that shows whether the privilege has
|
||||
been created or updated.
|
||||
|
||||
- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
|
||||
- the _"Manage Application Privileges"_ global privilege for the application being referenced
|
||||
in the request
|
||||
|
||||
==== Examples
|
||||
[[security-api-put-privileges-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
To add a single privilege, submit a PUT or POST request to the
|
||||
`/_security/privilege/<application>/<privilege>` endpoint. For example:
|
||||
|
|
@ -102,9 +113,6 @@ PUT /_security/privilege
|
|||
wildcard and returns `true`.
|
||||
<3> The metadata object is optional.
|
||||
|
||||
A successful call returns a JSON structure that shows whether the privilege has
|
||||
been created or updated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
|
|
|
|||
|
|
@ -8,12 +8,21 @@
|
|||
The `certificates` API enables you to retrieve information about the X.509
|
||||
certificates that are used to encrypt communications in your {es} cluster.
|
||||
|
||||
==== Request
|
||||
[[security-api-ssl-request]]
|
||||
==== {api-request-title}
|
||||
|
||||
`GET /_ssl/certificates`
|
||||
|
||||
|
||||
==== Description
|
||||
[[security-api-ssl-prereqs]]
|
||||
==== {api-prereq-title}
|
||||
|
||||
* If the {security-features} are enabled, you must have `monitor` cluster
|
||||
privileges to use this API. For more information, see
|
||||
{stack-ov}/security-privileges.html[Security privileges].
|
||||
|
||||
[[security-api-ssl-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
For more information about how certificates are configured in conjunction with
|
||||
Transport Layer Security (TLS), see
|
||||
|
|
@ -45,8 +54,8 @@ If {es} is configured to use a keystore or truststore, the API output
|
|||
includes all certificates in that store, even though some of the certificates
|
||||
might not be in active use within the cluster.
|
||||
|
||||
|
||||
==== Results
|
||||
[[security-api-ssl-response-body]]
|
||||
==== {api-response-body-title}
|
||||
|
||||
The response is an array of objects, with each object representing a
|
||||
single certificate. The fields in each object are:
|
||||
|
|
@ -64,14 +73,9 @@ certificate, this field has a value of `true`.
|
|||
`expiry`:: (string) The ISO formatted date of the certificate's expiry
|
||||
(not-after) date.
|
||||
|
||||
==== Authorization
|
||||
|
||||
If the {security-features} are enabled, you must have `monitor` cluster
|
||||
privileges to use this API. For more information, see
|
||||
{stack-ov}/security-privileges.html[Security Privileges].
|
||||
|
||||
|
||||
==== Examples
|
||||
[[security-api-ssl-example]]
|
||||
==== {api-examples-title}
|
||||
|
||||
The following example provides information about the certificates on a single
|
||||
node of {es}:
|
||||
|
|
|
|||
Loading…
Reference in New Issue