mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 09:54:06 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
177 lines
5.5 KiB
Text
177 lines
5.5 KiB
Text
[role="xpack"]
|
|
[[security-api-grant-api-key]]
|
|
=== Grant API key API
|
|
++++
|
|
<titleabbrev>Grant API keys</titleabbrev>
|
|
++++
|
|
|
|
Creates an API key on behalf of another user.
|
|
|
|
[[security-api-grant-api-key-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/api_key/grant`
|
|
|
|
[[security-api-grant-api-key-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have the `grant_api_key` cluster privilege.
|
|
|
|
[[security-api-grant-api-key-desc]]
|
|
==== {api-description-title}
|
|
|
|
This API is similar to <<security-api-create-api-key>>, however it creates the
|
|
API key for a user that is different than the user that runs the API.
|
|
|
|
The caller must have authentication credentials (either an access token,
|
|
or a username and password) for the user on whose behalf the API key will be
|
|
created. It is not possible to use this API to create an API key without that
|
|
user's credentials.
|
|
|
|
The user, for whom the authentication credentials is provided,
|
|
can optionally <<run-as-privilege,"run as">> (impersonate) another user.
|
|
In this case, the API key will be created on behalf of the impersonated user.
|
|
|
|
This API is intended be used by applications that need to create and manage
|
|
API keys for end users, but cannot guarantee that those users have permission
|
|
to create API keys on their own behalf (see <<security-api-create-api-key-prereqs>>).
|
|
The API keys are created by the {es} API key service, which is automatically
|
|
enabled.
|
|
|
|
A successful grant API key API call returns a JSON structure that contains the
|
|
API key, its unique id, and its name. If applicable, it also returns expiration
|
|
information for the API key in milliseconds.
|
|
|
|
NOTE: By default, API keys never expire. You can specify expiration information
|
|
when you create the API keys.
|
|
|
|
See <<api-key-service-settings>> for configuration settings related to API key
|
|
service.
|
|
|
|
[[security-api-grant-api-key-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
The following parameters can be specified in the body of a POST request:
|
|
|
|
`access_token`::
|
|
(Required*, string)
|
|
The user's access token. If you specify the `access_token` grant type, this
|
|
parameter is required. It is not valid with other grant types.
|
|
|
|
`api_key`::
|
|
(Required, object)
|
|
Defines the API key.
|
|
|
|
`expiration`:::
|
|
(Optional, string) Expiration time for the API key. By default, API keys never
|
|
expire.
|
|
|
|
`name`:::
|
|
(Required, string) Specifies the name for this API key.
|
|
|
|
`role_descriptors`:::
|
|
(Optional, object) The role descriptors for this API
|
|
key. This parameter is optional. When it is not specified or is an empty array,
|
|
the API key has a point in time snapshot of permissions of the specified user or
|
|
access token. If you supply role descriptors, the resultant permissions are an
|
|
intersection of API keys permissions and the permissions of the user or access
|
|
token. The structure of a role descriptor is the same as the request for <<api-key-role-descriptors, create API keys API>>.
|
|
|
|
`metadata`:::
|
|
(Optional, object) Arbitrary metadata that you want to associate with the API key.
|
|
It supports nested data structure.
|
|
Within the `metadata` object, keys beginning with `_` are reserved for
|
|
system usage.
|
|
|
|
`grant_type`::
|
|
(Required, string)
|
|
The type of grant. Supported grant types are: `access_token`,`password`.
|
|
|
|
`access_token`:::
|
|
(Required*, string)
|
|
In this type of grant, you must supply an access token that was created by the
|
|
{es} token service. For more information, see
|
|
<<security-api-get-token>> and <<encrypt-http-communication>>.
|
|
|
|
`password`:::
|
|
In this type of grant, you must supply the user ID and password for which you
|
|
want to create the API key.
|
|
|
|
`password`::
|
|
(Optional*, string)
|
|
The user's password. If you specify the `password` grant type, this parameter is
|
|
required. It is not valid with other grant types.
|
|
|
|
`username`::
|
|
(Optional*, string)
|
|
The user name that identifies the user. If you specify the `password` grant type,
|
|
this parameter is required. It is not valid with other grant types.
|
|
|
|
`run_as`::
|
|
(Optional, string)
|
|
The name of the user to be <<run-as-privilege,impersonated>>.
|
|
|
|
[[security-api-grant-api-key-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key/grant
|
|
{
|
|
"grant_type": "password",
|
|
"username" : "test_admin",
|
|
"password" : "x-pack-test-password",
|
|
"api_key" : {
|
|
"name": "my-api-key",
|
|
"expiration": "1d",
|
|
"role_descriptors": {
|
|
"role-a": {
|
|
"cluster": ["all"],
|
|
"indices": [
|
|
{
|
|
"names": ["index-a*"],
|
|
"privileges": ["read"]
|
|
}
|
|
]
|
|
},
|
|
"role-b": {
|
|
"cluster": ["all"],
|
|
"indices": [
|
|
{
|
|
"names": ["index-b*"],
|
|
"privileges": ["all"]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"metadata": {
|
|
"application": "my-application",
|
|
"environment": {
|
|
"level": 1,
|
|
"trusted": true,
|
|
"tags": ["dev", "staging"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
|
|
The user (`test_admin`) whose credentials are provided can "run as" another user (`test_user`).
|
|
The API key will be granted to the impersonated user (`test_user`).
|
|
|
|
[source,console]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key/grant
|
|
{
|
|
"grant_type": "password",
|
|
"username" : "test_admin", <1>
|
|
"password" : "x-pack-test-password", <2>
|
|
"run_as": "test_user", <3>
|
|
"api_key" : {
|
|
"name": "another-api-key"
|
|
}
|
|
}
|
|
------------------------------------------------------------
|
|
<1> The user for which the credential is provided and performs "run as".
|
|
<2> Credential for the above user
|
|
<3> The impersonated user for whom the API key will be created for.
|