[DOCS] Splits the token APIs into separate pages (#32865)
This commit is contained in:
Lisa Cawley
GitHub
parent
1efee66d16
commit
fb1c3990d7
|
|
@ -512,3 +512,11 @@ You can use the following APIs to add, remove, and retrieve roles in the native
|
|||
* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
|
||||
* <<security-api-clear-role-cache,Clear roles cache>>
|
||||
* <<security-api-get-role,Get roles>>
|
||||
|
||||
[role="exclude",id="security-api-tokens"]
|
||||
=== Token management APIs
|
||||
|
||||
You can use the following APIs to create and invalidate bearer tokens for access
|
||||
without requiring basic authentication:
|
||||
|
||||
* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ You can use the following APIs to perform {security} activities.
|
|||
* <<security-api-privileges>>
|
||||
* <<security-api-role-mapping>>
|
||||
* <<security-api-ssl>>
|
||||
* <<security-api-tokens>>
|
||||
* <<security-api-users>>
|
||||
|
||||
[float]
|
||||
|
|
@ -22,15 +21,25 @@ You can use the following APIs to add, remove, and retrieve roles in the native
|
|||
* <<security-api-clear-role-cache,Clear roles cache>>
|
||||
* <<security-api-get-role,Get roles>>
|
||||
|
||||
[float]
|
||||
[[security-token-apis]]
|
||||
=== Tokens
|
||||
|
||||
You can use the following APIs to create and invalidate bearer tokens for access
|
||||
without requiring basic authentication:
|
||||
|
||||
* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
|
||||
|
||||
include::security/authenticate.asciidoc[]
|
||||
include::security/change-password.asciidoc[]
|
||||
include::security/clear-cache.asciidoc[]
|
||||
include::security/clear-roles-cache.asciidoc[]
|
||||
include::security/create-roles.asciidoc[]
|
||||
include::security/delete-roles.asciidoc[]
|
||||
include::security/delete-tokens.asciidoc[]
|
||||
include::security/get-roles.asciidoc[]
|
||||
include::security/get-tokens.asciidoc[]
|
||||
include::security/privileges.asciidoc[]
|
||||
include::security/role-mapping.asciidoc[]
|
||||
include::security/ssl.asciidoc[]
|
||||
include::security/tokens.asciidoc[]
|
||||
include::security/users.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
[role="xpack"]
|
||||
[[security-api-invalidate-token]]
|
||||
=== Delete token API
|
||||
|
||||
Invalidates a bearer token for access without requiring basic authentication.
|
||||
|
||||
==== Request
|
||||
|
||||
`DELETE /_xpack/security/oauth2/token`
|
||||
|
||||
==== Description
|
||||
|
||||
The tokens returned by the <<security-api-get-token,get token API>> have a
|
||||
finite period of time for which they are valid and after that time period, they
|
||||
can no longer be used. That time period is defined by the
|
||||
`xpack.security.authc.token.timeout` setting. For more information, see
|
||||
<<token-service-settings>>.
|
||||
|
||||
If you want to invalidate a token immediately, use this delete token API.
|
||||
|
||||
|
||||
==== Request Body
|
||||
|
||||
The following parameters can be specified in the body of a DELETE request and
|
||||
pertain to deleting a token:
|
||||
|
||||
`token` (required)::
|
||||
(string) An access token.
|
||||
|
||||
==== Examples
|
||||
|
||||
The following example invalidates the specified token immediately:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_xpack/security/oauth2/token
|
||||
{
|
||||
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
A successful call returns a JSON structure that indicates whether the token
|
||||
has already been invalidated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"created" : true <1>
|
||||
}
|
||||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
<1> When a token has already been invalidated, `created` is set to false.
|
||||
|
|
@ -1,15 +1,12 @@
|
|||
[role="xpack"]
|
||||
[[security-api-tokens]]
|
||||
=== Token Management APIs
|
||||
[[security-api-get-token]]
|
||||
=== Get token API
|
||||
|
||||
The `token` API enables you to create and invalidate bearer tokens for access
|
||||
without requiring basic authentication.
|
||||
Creates a bearer token for access without requiring basic authentication.
|
||||
|
||||
==== Request
|
||||
|
||||
`POST /_xpack/security/oauth2/token` +
|
||||
|
||||
`DELETE /_xpack/security/oauth2/token`
|
||||
`POST /_xpack/security/oauth2/token`
|
||||
|
||||
==== Description
|
||||
|
||||
|
|
@ -19,20 +16,20 @@ you can explicitly enable the `xpack.security.authc.token.enabled` setting. When
|
|||
you are running in production mode, a bootstrap check prevents you from enabling
|
||||
the token service unless you also enable TLS on the HTTP interface.
|
||||
|
||||
The Get Token API takes the same parameters as a typical OAuth 2.0 token API
|
||||
The get token API takes the same parameters as a typical OAuth 2.0 token API
|
||||
except for the use of a JSON request body.
|
||||
|
||||
A successful Get Token API call returns a JSON structure that contains the access
|
||||
A successful get token API call returns a JSON structure that contains the access
|
||||
token, the amount of time (seconds) that the token expires in, the type, and the
|
||||
scope if available.
|
||||
|
||||
The tokens returned by the Get Token API have a finite period of time for which
|
||||
The tokens returned by the get token API have a finite period of time for which
|
||||
they are valid and after that time period, they can no longer be used. That time
|
||||
period is defined by the `xpack.security.authc.token.timeout` setting. For more
|
||||
information, see <<token-service-settings>>.
|
||||
|
||||
If you want to invalidate a token immediately, you can do so by using the Delete
|
||||
Token API.
|
||||
If you want to invalidate a token immediately, you can do so by using the
|
||||
<<security-api-invalidate-token,delete token API>>.
|
||||
|
||||
|
||||
==== Request Body
|
||||
|
|
@ -41,28 +38,28 @@ The following parameters can be specified in the body of a POST request and
|
|||
pertain to creating a token:
|
||||
|
||||
`grant_type`::
|
||||
(string) The type of grant. Currently only the `password` grant type is supported.
|
||||
(string) The type of grant. Valid grant types are: `password` and `refresh_token`.
|
||||
|
||||
`password` (required)::
|
||||
(string) The user's password.
|
||||
`password`::
|
||||
(string) The user's password. If you specify the `password` grant type, this
|
||||
parameter is required.
|
||||
|
||||
`refresh_token`::
|
||||
(string) If you specify the `refresh_token` grant type, this parameter is
|
||||
required. It contains the string that was returned when you created the token
|
||||
and enables you to extend its life.
|
||||
|
||||
`scope`::
|
||||
(string) The scope of the token. Currently tokens are only issued for a scope of
|
||||
`FULL` regardless of the value sent with the request.
|
||||
|
||||
`username` (required)::
|
||||
(string) The username that identifies the user.
|
||||
|
||||
The following parameters can be specified in the body of a DELETE request and
|
||||
pertain to deleting a token:
|
||||
|
||||
`token`::
|
||||
(string) An access token.
|
||||
`username`::
|
||||
(string) The username that identifies the user. If you specify the `password`
|
||||
grant type, this parameter is required.
|
||||
|
||||
==== Examples
|
||||
[[security-api-get-token]]
|
||||
To obtain a token, submit a POST request to the `/_xpack/security/oauth2/token`
|
||||
endpoint.
|
||||
|
||||
The following example obtains a token for the `test_admin` user:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -101,8 +98,8 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
|
|||
// NOTCONSOLE
|
||||
|
||||
[[security-api-refresh-token]]
|
||||
To extend the life of an existing token, the token api may be called again with the refresh
|
||||
token within 24 hours of the token's creation.
|
||||
To extend the life of an existing token, you can call the API again with the
|
||||
refresh token within 24 hours of the token's creation. For example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -116,7 +113,8 @@ POST /_xpack/security/oauth2/token
|
|||
// TEST[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
||||
// TEST[continued]
|
||||
|
||||
The API will return a new token and refresh token. Each refresh token may only be used one time.
|
||||
The API will return a new token and refresh token. Each refresh token may only
|
||||
be used one time.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
|
@ -129,31 +127,3 @@ The API will return a new token and refresh token. Each refresh token may only b
|
|||
--------------------------------------------------
|
||||
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
||||
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
||||
|
||||
[[security-api-invalidate-token]]
|
||||
If a token must be invalidated immediately, you can do so by submitting a DELETE
|
||||
request to `/_xpack/security/oauth2/token`. For example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
DELETE /_xpack/security/oauth2/token
|
||||
{
|
||||
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
|
||||
}
|
||||
--------------------------------------------------
|
||||
// CONSOLE
|
||||
// TEST[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
||||
// TEST[continued]
|
||||
|
||||
A successful call returns a JSON structure that indicates whether the token
|
||||
has already been invalidated.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"created" : true <1>
|
||||
}
|
||||
--------------------------------------------------
|
||||
// TESTRESPONSE
|
||||
|
||||
<1> When a token has already been invalidated, `created` is set to false.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.get_token": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html#security-api-get-token",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-token.html",
|
||||
"methods": [ "POST" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/oauth2/token",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"xpack.security.invalidate_token": {
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html#security-api-invalidate-token",
|
||||
"documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-token.html",
|
||||
"methods": [ "DELETE" ],
|
||||
"url": {
|
||||
"path": "/_xpack/security/oauth2/token",
|
||||
|
|
|
|||
Loading…
Reference in New Issue