Skip to content

Commit 100be22

Browse files
lcawllcawl
authored
[DOCS] Add grant API key API and grant_api_key privilege (#63449) (#63854)
1 parent b63aadd commit 100be22

File tree

4 files changed

+177
-3
lines changed

4 files changed

+177
-3
lines changed

‎x-pack/docs/en/rest-api/security.asciidoc

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,10 @@ without requiring basic authentication:
6161
You can use the following APIs to create, retrieve and invalidate API keys for access
6262
without requiring basic authentication:
6363

64-
* <<security-api-create-api-key,Create API Key>>
65-
* <<security-api-get-api-key,Get API Key>>
66-
* <<security-api-invalidate-api-key,Invalidate API Key>>
64+
* <<security-api-create-api-key,Create API key>>
65+
* <<security-api-get-api-key,Get API key>>
66+
* <<security-api-invalidate-api-key,Invalidate API key>>
67+
* <<security-api-grant-api-key,Grant API key>>
6768

6869
[discrete]
6970
[[security-user-apis]]
@@ -127,6 +128,7 @@ include::security/get-role-mappings.asciidoc[]
127128
include::security/get-roles.asciidoc[]
128129
include::security/get-tokens.asciidoc[]
129130
include::security/get-users.asciidoc[]
131+
include::security/grant-api-keys.asciidoc[]
130132
include::security/has-privileges.asciidoc[]
131133
include::security/invalidate-api-keys.asciidoc[]
132134
include::security/invalidate-tokens.asciidoc[]

‎x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
[role="xpack"]
2+
[[security-api-grant-api-key]]
3+
=== Grant API key API
4+
++++
5+
<titleabbrev>Grant API keys</titleabbrev>
6+
++++
7+
8+
Creates an API key on behalf of another user.
9+
10+
[[security-api-grant-api-key-request]]
11+
==== {api-request-title}
12+
13+
`POST /_security/api_key/grant`
14+
15+
[[security-api-grant-api-key-prereqs]]
16+
==== {api-prereq-title}
17+
18+
* To use this API, you must have the `grant_api_key` cluster privilege.
19+
20+
[[security-api-grant-api-key-desc]]
21+
==== {api-description-title}
22+
23+
This API is similar to <<security-api-create-api-key>>, however it creates the
24+
API key for a user that is different than the user that runs the API.
25+
26+
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.
27+
28+
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>>).
29+
The API keys are created by the {es} API key service, which is automatically
30+
enabled when you configure TLS on the HTTP interface. See <<tls-http>>.
31+
Alternatively, you can explicitly enable the
32+
`xpack.security.authc.api_key.enabled` setting. When you are running in
33+
production mode, a bootstrap check prevents you from enabling the API key
34+
service unless you also enable TLS on the HTTP interface.
35+
36+
A successful grant API key API call returns a JSON structure that contains the
37+
API key, its unique id, and its name. If applicable, it also returns expiration
38+
information for the API key in milliseconds.
39+
40+
NOTE: By default, API keys never expire. You can specify expiration information
41+
when you create the API keys.
42+
43+
See <<api-key-service-settings>> for configuration settings related to API key
44+
service.
45+
46+
[[security-api-grant-api-key-request-body]]
47+
==== {api-request-body-title}
48+
49+
The following parameters can be specified in the body of a POST request:
50+
51+
`access_token`::
52+
(Required*, string)
53+
The user's access token. If you specify the `access_token` grant type, this
54+
parameter is required. It is not valid with other grant types.
55+
56+
`api_key`::
57+
(Required, object)
58+
Defines the API key.
59+
60+
`expiration`:::
61+
(Optional, string) Expiration time for the API key. By default, API keys never
62+
expire.
63+
64+
`name`:::
65+
(Required, string) Specifies the name for this API key.
66+
67+
`role_descriptors`:::
68+
(Optional, array-of-role-descriptor) An array of role descriptors for this API
69+
key. This parameter is optional. When it is not specified or is an empty array,
70+
the API key has a point in time snapshot of permissions of the specified user or
71+
access token. If you supply role descriptors, the resultant permissions are an
72+
intersection of API keys permissions and the permissions of the user or access
73+
token. The structure of role descriptor is the same as the request for create
74+
role API. For more details, see <<security-api-put-role>>.
75+
76+
`grant_type`::
77+
(Required, string)
78+
The type of grant. Supported grant types are: `access_token`,`password`.
79+
80+
`access_token`:::
81+
(Required*, string)
82+
In this type of grant, you must supply an access token that was created by the
83+
{es} token service. For more information, see
84+
<<security-api-get-token>> and <<tls-http>>.
85+
86+
`password`:::
87+
In this type of grant, you must supply the user ID and password for which you
88+
want to create the API key.
89+
90+
`password`::
91+
(Optional*, string)
92+
The user's password. If you specify the `password` grant type, this parameter is
93+
required. It is not valid with other grant types.
94+
95+
`username`::
96+
(Optional*, string)
97+
The user name that identifies the user. If you specify the `password` grant type,
98+
this parameter is required. It is not valid with other grant types.
99+
100+
[[security-api-grant-api-key-example]]
101+
==== {api-examples-title}
102+
103+
[source,console]
104+
------------------------------------------------------------
105+
POST /_security/api_key/grant
106+
{
107+
"grant_type": "password",
108+
"username" : "test_admin",
109+
"password" : "x-pack-test-password",
110+
"api_key" : {
111+
"name": "my-api-key",
112+
"expiration": "1d",
113+
"role_descriptors": {
114+
"role-a": {
115+
"cluster": ["all"],
116+
"index": [
117+
{
118+
"names": ["index-a*"],
119+
"privileges": ["read"]
120+
}
121+
]
122+
},
123+
"role-b": {
124+
"cluster": ["all"],
125+
"index": [
126+
{
127+
"names": ["index-b*"],
128+
"privileges": ["all"]
129+
}
130+
]
131+
}
132+
}
133+
}
134+
}
135+
------------------------------------------------------------

‎x-pack/docs/en/security/authorization/privileges.asciidoc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ settings update, rerouting, or managing users and roles.
1616
Privileges to create snapshots for existing repositories. Can also list and view
1717
details on existing repositories and snapshots.
1818

19+
`grant_api_key`::
20+
Privileges to create {es} API keys on behalf of other users.
21+
1922
`monitor_snapshot`::
2023
Privileges to list and view details on existing repositories and snapshots.
2124

‎x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"security.grant_api_key":{
3+
"documentation":{
4+
"url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html",
5+
"description":"Creates an API key on behalf of another user."
6+
},
7+
"stability":"stable",
8+
"url":{
9+
"paths":[
10+
{
11+
"path":"/_security/api_key/grant",
12+
"methods":[
13+
"POST"
14+
]
15+
}
16+
]
17+
},
18+
"params":{
19+
"refresh":{
20+
"type":"enum",
21+
"options":[
22+
"true",
23+
"false",
24+
"wait_for"
25+
],
26+
"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."
27+
}
28+
},
29+
"body":{
30+
"description":"The api key request to create an API key",
31+
"required":true
32+
}
33+
}
34+
}

0 commit comments

Comments
 (0)