[DOCS] Enable testing for API key examples (#39583)
This commit is contained in:
Lisa Cawley
lcawl
parent
69f5869707
commit
696cb22e4a
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[security-api-create-api-key]]
|
||||
=== Create API Key API
|
||||
=== Create API key API
|
||||
++++
|
||||
<titleabbrev>Create API keys</titleabbrev>
|
||||
++++
|
||||
|
|
@ -20,14 +20,15 @@ you can explicitly enable the `xpack.security.authc.api_key.enabled` setting. Wh
|
|||
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 create API key API call returns a JSON structure that contains
|
||||
the unique id, the name to identify API key, the API key and the expiration if
|
||||
applicable for the API key in milliseconds.
|
||||
A successful create 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 at the time of
|
||||
creation for the API keys.
|
||||
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.
|
||||
See <<api-key-service-settings>> for configuration settings related to API key
|
||||
service.
|
||||
|
||||
==== Request Body
|
||||
|
||||
|
|
@ -36,15 +37,16 @@ The following parameters can be specified in the body of a POST or PUT request:
|
|||
`name`::
|
||||
(string) Specifies the name for this API key.
|
||||
|
||||
`role_descriptors`::
|
||||
(array-of-role-descriptor) Optional array of role descriptor for this API key. The role descriptor
|
||||
must be a subset of permissions of the authenticated user. The structure of role
|
||||
descriptor is same as the request for create role API. For more details on role
|
||||
see <<security-api-roles, Role Management APIs>>.
|
||||
If the role descriptors are not provided then permissions of the authenticated user are applied.
|
||||
`role_descriptors` (required)::
|
||||
(array-of-role-descriptor) An array of role descriptors for this API key. This
|
||||
parameter is required but can be an empty array, which applies the permissions
|
||||
of the authenticated user. If you supply role descriptors, they must be a subset
|
||||
of the authenticated user's permissions. The structure of role descriptor is the
|
||||
same as the request for create role API. For more details, see
|
||||
<<security-api-roles,role management APIs>>.
|
||||
|
||||
`expiration`::
|
||||
(string) Optional expiration time for the API key. By default API keys never expire.
|
||||
(string) Optional expiration time for the API key. By default, API keys never expire.
|
||||
|
||||
==== Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[security-api-get-api-key]]
|
||||
=== Get API Key information API
|
||||
=== Get API key information API
|
||||
++++
|
||||
<titleabbrev>Get API key information</titleabbrev>
|
||||
++++
|
||||
|
|
@ -22,38 +22,70 @@ The following parameters can be specified in the query parameters of a GET reque
|
|||
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.
|
||||
(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.
|
||||
(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`.
|
||||
(string) The name of an authentication realm. This parameter cannot be used with
|
||||
either `id` or `name`.
|
||||
|
||||
`username` (optional)::
|
||||
(string) The username of a user. This parameter cannot be used with either `id` or `name`.
|
||||
(string) The username of a user. This parameter cannot be used with either `id`
|
||||
or `name`.
|
||||
|
||||
NOTE: While all parameters are optional, at least one of them is required.
|
||||
|
||||
==== Examples
|
||||
|
||||
The following example to retrieve the API key identified by specified `id`:
|
||||
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]
|
||||
--------------------------------------------------
|
||||
GET /_security/api_key?id=dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==
|
||||
{
|
||||
"id":"VuaCfGcBCdbkQm-e5aOx",
|
||||
"name":"my-api-key",
|
||||
"api_key":"ui2lp2axTNmsyakw9tvNnw"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
||||
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
|
||||
|
||||
whereas the following example to retrieve the API key identified by specified `name`:
|
||||
You can use the following example to retrieve the API key by ID:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /_security/api_key?name=hadoop_myuser_key
|
||||
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// 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:
|
||||
|
||||
|
|
@ -61,7 +93,8 @@ The following example retrieves all API keys for the `native1` realm:
|
|||
--------------------------------------------------
|
||||
GET /_security/api_key?realm_name=native1
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The following example retrieves all API keys for the user `myuser` in all realms:
|
||||
|
||||
|
|
@ -69,7 +102,8 @@ The following example retrieves all API keys for the user `myuser` in all realms
|
|||
--------------------------------------------------
|
||||
GET /_security/api_key?username=myuser
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
Finally, the following example retrieves all API keys for the user `myuser` in
|
||||
the `native1` realm immediately:
|
||||
|
|
@ -78,7 +112,8 @@ Finally, the following example retrieves all API keys for the user `myuser` in
|
|||
--------------------------------------------------
|
||||
GET /_security/api_key?username=myuser&realm_name=native1
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved.
|
||||
|
||||
|
|
@ -112,7 +147,8 @@ A successful call returns a JSON structure that contains the information of one
|
|||
<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, `true` if the key has been invalidated else `false`
|
||||
<7> principal for which this API key was created
|
||||
<8> realm name of the principal for which this API key was created
|
||||
<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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[security-api-invalidate-api-key]]
|
||||
=== Invalidate API Key API
|
||||
=== Invalidate API key API
|
||||
++++
|
||||
<titleabbrev>Invalidate API key</titleabbrev>
|
||||
++++
|
||||
|
|
@ -13,8 +13,8 @@ Invalidates one or more API keys.
|
|||
|
||||
==== Description
|
||||
|
||||
The API keys created by <<security-api-create-api-key,create API Key>> can be invalidated
|
||||
using this API.
|
||||
The API keys created by <<security-api-create-api-key,create API Key>> can be
|
||||
invalidated using this API.
|
||||
|
||||
==== Request Body
|
||||
|
||||
|
|
@ -22,46 +22,79 @@ 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.
|
||||
(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.
|
||||
(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 `api_key_id` or `api_key_name`.
|
||||
(string) The name of an authentication realm. This parameter cannot be used with
|
||||
either `api_key_id` or `api_key_name`.
|
||||
|
||||
`username` (optional)::
|
||||
(string) The username of a user. This parameter cannot be used with either `api_key_id` or `api_key_name`.
|
||||
(string) The username of a user. This parameter cannot be used with either
|
||||
`api_key_id` or `api_key_name`.
|
||||
|
||||
NOTE: While all parameters are optional, at least one of them is required.
|
||||
|
||||
==== Examples
|
||||
|
||||
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/]
|
||||
|
||||
The following example invalidates the API key identified by specified `id` immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_security/api_key
|
||||
{
|
||||
"id" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
|
||||
"id" : "VuaCfGcBCdbkQm-e5aOx"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
|
||||
// TEST[continued]
|
||||
|
||||
whereas the following example invalidates the API key identified by specified `name` immediately:
|
||||
The following example invalidates the API key identified by specified `name` immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_security/api_key
|
||||
{
|
||||
"name" : "hadoop_myuser_key"
|
||||
"name" : "my-api-key"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
The following example invalidates all API keys for the `native1` realm immediately:
|
||||
The following example invalidates all API keys for the `native1` realm
|
||||
immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -70,9 +103,11 @@ DELETE /_security/api_key
|
|||
"realm_name" : "native1"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
The following example invalidates all API keys for the user `myuser` in all realms immediately:
|
||||
The following example invalidates all API keys for the user `myuser` in all
|
||||
realms immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -81,7 +116,8 @@ DELETE /_security/api_key
|
|||
"username" : "myuser"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
Finally, the following example invalidates all API keys for the user `myuser` in
|
||||
the `native1` realm immediately:
|
||||
|
|
@ -94,7 +130,8 @@ DELETE /_security/api_key
|
|||
"realm_name" : "native1"
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
// CONSOLE
|
||||
// TEST
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue