218 lines
6.6 KiB
Plaintext
218 lines
6.6 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-invalidate-token]]
|
|
=== Invalidate token API
|
|
++++
|
|
<titleabbrev>Invalidate token</titleabbrev>
|
|
++++
|
|
|
|
Invalidates one or more access tokens or refresh tokens.
|
|
|
|
==== Request
|
|
|
|
`DELETE /_security/oauth2/token`
|
|
|
|
==== Description
|
|
|
|
The access 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>>.
|
|
|
|
The refresh tokens returned by the <<security-api-get-token,get token API>> are
|
|
only valid for 24 hours. They can also be used exactly once.
|
|
|
|
If you want to invalidate one or more access or refresh tokens immediately, use
|
|
this invalidate token API.
|
|
|
|
|
|
==== Request Body
|
|
|
|
The following parameters can be specified in the body of a DELETE request and
|
|
pertain to invalidating tokens:
|
|
|
|
`token` (optional)::
|
|
(string) An access token. This parameter cannot be used any of `refresh_token`,
|
|
`realm_name` or `username` are used.
|
|
|
|
`refresh_token` (optional)::
|
|
(string) A refresh token. This parameter cannot be used any of `refresh_token`,
|
|
`realm_name` or `username` are used.
|
|
|
|
`realm_name` (optional)::
|
|
(string) The name of an authentication realm. This parameter cannot be used with
|
|
either `refresh_token` or `token`.
|
|
|
|
`username` (optional)::
|
|
(string) The username of a user. This parameter cannot be used with either
|
|
`refresh_token` or `token`
|
|
|
|
NOTE: While all parameters are optional, at least one of them is required. More
|
|
specifically, either one of `token` or `refresh_token` parameters is required.
|
|
If none of these two are specified, then `realm_name` and/or `username` need to
|
|
be specified.
|
|
|
|
==== Examples
|
|
|
|
For example, if you create a token using the `client_credentials` grant type as
|
|
follows:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type" : "client_credentials"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The get token API returns the following information about the access token:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
|
|
|
This access token can now be immediately invalidated, as shown in the following
|
|
example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/oauth2/token
|
|
{
|
|
"token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
|
// TEST[continued]
|
|
|
|
If you used the `password` grant type to obtain a token for a user, the response
|
|
might also contain a refresh token. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type" : "password",
|
|
"username" : "test_admin",
|
|
"password" : "x-pack-test-password"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The get token API returns the following information:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
|
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
|
|
|
The refresh token can now also be immediately invalidated as shown
|
|
in the following example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/oauth2/token
|
|
{
|
|
"refresh_token" : "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
|
// TEST[continued]
|
|
|
|
The following example invalidates all access tokens and refresh tokens for the
|
|
`saml1` realm immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/oauth2/token
|
|
{
|
|
"realm_name" : "saml1"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
The following example invalidates all access tokens and refresh tokens for the
|
|
user `myuser` in all realms immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/oauth2/token
|
|
{
|
|
"username" : "myuser"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
Finally, the following example invalidates all access tokens and refresh tokens
|
|
for the user `myuser` in the `saml1` realm immediately:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
DELETE /_security/oauth2/token
|
|
{
|
|
"username" : "myuser",
|
|
"realm_name" : "saml1"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST
|
|
|
|
A successful call returns a JSON structure that contains the number of tokens
|
|
that were invalidated, the number of tokens that had already been invalidated,
|
|
and potentially a list of errors encountered while invalidating specific tokens.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"invalidated_tokens":9, <1>
|
|
"previously_invalidated_tokens":15, <2>
|
|
"error_count":2, <3>
|
|
"error_details":[ <4>
|
|
{
|
|
"type":"exception",
|
|
"reason":"Elasticsearch exception [type=exception, reason=foo]",
|
|
"caused_by":{
|
|
"type":"exception",
|
|
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=bar]"
|
|
}
|
|
},
|
|
{
|
|
"type":"exception",
|
|
"reason":"Elasticsearch exception [type=exception, reason=boo]",
|
|
"caused_by":{
|
|
"type":"exception",
|
|
"reason":"Elasticsearch exception [type=illegal_argument_exception, reason=far]"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
<1> The number of the tokens that were invalidated as part of this request.
|
|
<2> The number of tokens that were already invalidated.
|
|
<3> The number of errors that were encountered when invalidating the tokens.
|
|
<4> Details about these errors. This field is not present in the response when
|
|
`error_count` is 0.
|