-
Notifications
You must be signed in to change notification settings - Fork 24.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[7.10][DOCS] Add grant API key API and grant_api_key privilege (#63853)
- Loading branch information
Showing
4 changed files
with
177 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
135 changes: 135 additions & 0 deletions
135
x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,135 @@ | ||
[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. | ||
|
||
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 when you configure TLS on the HTTP interface. See <<tls-http>>. | ||
Alternatively, you can explicitly enable the | ||
`xpack.security.authc.api_key.enabled` setting. When you are running in | ||
production mode, a bootstrap check prevents you from enabling the API key | ||
service unless you also enable TLS on the HTTP interface. | ||
|
||
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, 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, | ||
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 role descriptor is the same as the request for create | ||
role API. For more details, see <<security-api-put-role>>. | ||
|
||
`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 <<tls-http>>. | ||
|
||
`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. | ||
|
||
[[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"], | ||
"index": [ | ||
{ | ||
"names": ["index-a*"], | ||
"privileges": ["read"] | ||
} | ||
] | ||
}, | ||
"role-b": { | ||
"cluster": ["all"], | ||
"index": [ | ||
{ | ||
"names": ["index-b*"], | ||
"privileges": ["all"] | ||
} | ||
] | ||
} | ||
} | ||
} | ||
} | ||
------------------------------------------------------------ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
34 changes: 34 additions & 0 deletions
34
x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
{ | ||
"security.grant_api_key":{ | ||
"documentation":{ | ||
"url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html", | ||
"description":"Creates an API key on behalf of another user." | ||
}, | ||
"stability":"stable", | ||
"url":{ | ||
"paths":[ | ||
{ | ||
"path":"/_security/api_key/grant", | ||
"methods":[ | ||
"POST" | ||
] | ||
} | ||
] | ||
}, | ||
"params":{ | ||
"refresh":{ | ||
"type":"enum", | ||
"options":[ | ||
"true", | ||
"false", | ||
"wait_for" | ||
], | ||
"description":"If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes." | ||
} | ||
}, | ||
"body":{ | ||
"description":"The api key request to create an API key", | ||
"required":true | ||
} | ||
} | ||
} |