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
202 lines
5.9 KiB
Plaintext
202 lines
5.9 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-get-api-key]]
|
|
=== Get API key information API
|
|
++++
|
|
<titleabbrev>Get API key information</titleabbrev>
|
|
++++
|
|
|
|
Retrieves information for one or more API keys.
|
|
|
|
[[security-api-get-api-key-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_security/api_key`
|
|
|
|
[[security-api-get-api-key-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have at least the `manage_api_key` cluster privilege.
|
|
|
|
[[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.
|
|
|
|
`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-get-api-key-example]]
|
|
==== {api-examples-title}
|
|
|
|
If you create an API key as follows:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key
|
|
{
|
|
"name": "my-api-key",
|
|
"role_descriptors": {}
|
|
}
|
|
------------------------------------------------------------
|
|
// 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/]
|
|
|
|
You can use the following example to retrieve the API key by ID:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
|
// TEST[continued]
|
|
|
|
You can use the following example to retrieve the API key by name:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?name=my-api-key
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
The following example retrieves all API keys for the `native1` realm:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?realm_name=native1
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
The following example retrieves all API keys for the user `myuser` in all realms:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?username=myuser
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
The following example retrieves all API keys owned by the currently authenticated user:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?owner=true
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
Following creates an API key
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key
|
|
{
|
|
"name": "my-api-key-1"
|
|
}
|
|
------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example retrieves the API key identified by the specified `id` if
|
|
it is owned by the currently authenticated user:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
|
// TEST[continued]
|
|
|
|
Finally, the following example retrieves all API keys for the user `myuser` in
|
|
the `native1` realm immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_security/api_key?username=myuser&realm_name=native1
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"api_keys": [ <1>
|
|
{
|
|
"id": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", <2>
|
|
"name": "hadoop_myuser_key", <3>
|
|
"creation": 1548550550158, <4>
|
|
"expiration": 1548551550158, <5>
|
|
"invalidated": false, <6>
|
|
"username": "myuser", <7>
|
|
"realm": "native1" <8>
|
|
},
|
|
{
|
|
"id": "api-key-id-2",
|
|
"name": "api-key-name-2",
|
|
"creation": 1548550550158,
|
|
"invalidated": false,
|
|
"username": "user-y",
|
|
"realm": "realm-2"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
<1> The list of API keys that were retrieved for this request.
|
|
<2> Id for the API key
|
|
<3> Name of the API key
|
|
<4> Creation time for the API key in milliseconds
|
|
<5> Optional expiration time for the API key in milliseconds
|
|
<6> Invalidation status for the API key. If the key has been invalidated, it has
|
|
a value of `true`. Otherwise, it is `false`.
|
|
<7> Principal for which this API key was created
|
|
<8> Realm name of the principal for which this API key was created
|