mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-03 09:29:11 +00:00
7b6246ec67
The existing privilege model for API keys with privileges like `manage_api_key`, `manage_security` etc. are too permissive and we would want finer-grained control over the cluster privileges for API keys. Previously APIs created would also need these privileges to get its own information. This commit adds support for `manage_own_api_key` cluster privilege which only allows api key cluster actions on API keys owned by the currently authenticated user. Also adds support for retrieval of the API key self-information when authenticating via API key without the need for the additional API key privileges. To support this privilege, we are introducing additional authentication context along with the request context such that it can be used to authorize cluster actions based on the current user authentication. The API key get and invalidate APIs introduce an `owner` flag that can be set to true if the API key request (Get or Invalidate) is for the API keys owned by the currently authenticated user only. In that case, `realm` and `username` cannot be set as they are assumed to be the currently authenticated ones. The changes cover HLRC changes, documentation for the API changes. Closes #40031
226 lines
5.9 KiB
Plaintext
226 lines
5.9 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-invalidate-api-key]]
|
|
=== Invalidate API key API
|
|
++++
|
|
<titleabbrev>Invalidate API key</titleabbrev>
|
|
++++
|
|
|
|
Invalidates one or more API keys.
|
|
|
|
[[security-api-invalidate-api-key-request]]
|
|
==== {api-request-title}
|
|
|
|
`DELETE /_security/api_key`
|
|
|
|
[[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.
|
|
|
|
|
|
[[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.
|
|
|
|
`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 either `id` or `name` or when `owner` flag is set to `true`.
|
|
|
|
`username`::
|
|
(Optional, string) The username of a user. This parameter cannot be used with
|
|
either `id` or `name` or when `owner` flag is set to `true`.
|
|
|
|
`owner`::
|
|
(Optional, boolean) A boolean flag that can be used to query API keys owned
|
|
by the currently authenticated user. Defaults to false.
|
|
The 'realm_name' or 'username' parameters cannot be specified when this
|
|
parameter is set to 'true' as they are assumed to be the currently authenticated ones.
|
|
|
|
NOTE: At least one of "id", "name", "username" and "realm_name" must be specified
|
|
if "owner" is "false" (default).
|
|
|
|
[[security-api-invalidate-api-key-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
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.
|
|
|
|
[[security-api-invalidate-api-key-example]]
|
|
==== {api-examples-title}
|
|
|
|
If you create an API key as follows:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key
|
|
{
|
|
"name": "my-api-key"
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
A successful call returns a JSON structure that provides
|
|
API key information. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"id":"VuaCfGcBCdbkQm-e5aOx",
|
|
"name":"my-api-key",
|
|
"api_key":"ui2lp2axTNmsyakw9tvNnw"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
|
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
|
|
|
|
The following example invalidates the API key identified by specified `id`
|
|
immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"id" : "VuaCfGcBCdbkQm-e5aOx"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
|
// TEST[continued]
|
|
|
|
The following example invalidates the API key identified by specified `name`
|
|
immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"name" : "my-api-key"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The following example invalidates all API keys for the `native1` realm
|
|
immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"realm_name" : "native1"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The following example invalidates all API keys for the user `myuser` in all
|
|
realms immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"username" : "myuser"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The following example invalidates the API key identified by the specified `id` if
|
|
it is owned by the currently authenticated user immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"id" : "VuaCfGcBCdbkQm-e5aOx",
|
|
"owner" : "true"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example invalidates all API keys owned by the currently authenticated
|
|
user immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"owner" : "true"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
Finally, the following example invalidates all API keys for the user `myuser` in
|
|
the `native1` realm immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/api_key
|
|
{
|
|
"username" : "myuser",
|
|
"realm_name" : "native1"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"invalidated_api_keys": [ <1>
|
|
"api-key-id-1"
|
|
],
|
|
"previously_invalidated_api_keys": [ <2>
|
|
"api-key-id-2",
|
|
"api-key-id-3"
|
|
],
|
|
"error_count": 2, <3>
|
|
"error_details": [ <4>
|
|
{
|
|
"type": "exception",
|
|
"reason": "error occurred while invalidating api keys",
|
|
"caused_by": {
|
|
"type": "illegal_argument_exception",
|
|
"reason": "invalid api key id"
|
|
}
|
|
},
|
|
{
|
|
"type": "exception",
|
|
"reason": "error occurred while invalidating api keys",
|
|
"caused_by": {
|
|
"type": "illegal_argument_exception",
|
|
"reason": "invalid api key id"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// 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.
|
|
<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.
|