Invalidate token API
editInvalidate token API
editInvalidates one or more access tokens or refresh tokens.
Request
editDELETE /_security/oauth2/token
Description
editThe access 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.
The refresh tokens returned by the 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
editThe 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
orusername
are used. -
refresh_token
-
(Optional, string) A refresh token. This parameter cannot be used any of
refresh_token
,realm_name
orusername
are used. -
realm_name
-
(Optional, string) The name of an authentication realm. This parameter cannot be
used with either
refresh_token
ortoken
. -
username
-
(Optional, string) The username of a user. This parameter cannot be used with
either
refresh_token
ortoken
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.
Response body
editA 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.
Examples
editFor example, if you create a token using the client_credentials
grant type as
follows:
resp = client.security.get_token( grant_type="client_credentials", ) print(resp)
const response = await client.security.getToken({ grant_type: "client_credentials", }); console.log(response);
POST /_security/oauth2/token { "grant_type" : "client_credentials" }
The get token API returns the following information about the access token:
{ "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", "type" : "Bearer", "expires_in" : 1200, "authentication" : { "username" : "test_admin", "roles" : [ "superuser" ], "full_name" : null, "email" : null, "metadata" : { }, "enabled" : true, "authentication_realm" : { "name" : "file", "type" : "file" }, "lookup_realm" : { "name" : "file", "type" : "file" }, "authentication_type" : "realm" } }
This access token can now be immediately invalidated, as shown in the following example:
resp = client.security.invalidate_token( token="dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", ) print(resp)
const response = await client.security.invalidateToken({ token: "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", }); console.log(response);
DELETE /_security/oauth2/token { "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" }
If you used the password
grant type to obtain a token for a user, the response
might also contain a refresh token. For example:
resp = client.security.get_token( grant_type="password", username="test_admin", password="x-pack-test-password", ) print(resp)
const response = await client.security.getToken({ grant_type: "password", username: "test_admin", password: "x-pack-test-password", }); console.log(response);
POST /_security/oauth2/token { "grant_type" : "password", "username" : "test_admin", "password" : "x-pack-test-password" }
The get token API returns the following information:
{ "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", "type" : "Bearer", "expires_in" : 1200, "refresh_token": "vLBPvmAB6KvwvJZr27cS", "authentication" : { "username" : "test_admin", "roles" : [ "superuser" ], "full_name" : null, "email" : null, "metadata" : { }, "enabled" : true, "authentication_realm" : { "name" : "file", "type" : "file" }, "lookup_realm" : { "name" : "file", "type" : "file" }, "authentication_type" : "realm" } }
The refresh token can now also be immediately invalidated as shown in the following example:
resp = client.security.invalidate_token( refresh_token="vLBPvmAB6KvwvJZr27cS", ) print(resp)
const response = await client.security.invalidateToken({ refresh_token: "vLBPvmAB6KvwvJZr27cS", }); console.log(response);
DELETE /_security/oauth2/token { "refresh_token" : "vLBPvmAB6KvwvJZr27cS" }
The following example invalidates all access tokens and refresh tokens for the
saml1
realm immediately:
resp = client.security.invalidate_token( realm_name="saml1", ) print(resp)
const response = await client.security.invalidateToken({ realm_name: "saml1", }); console.log(response);
DELETE /_security/oauth2/token { "realm_name" : "saml1" }
The following example invalidates all access tokens and refresh tokens for the
user myuser
in all realms immediately:
resp = client.security.invalidate_token( username="myuser", ) print(resp)
const response = await client.security.invalidateToken({ username: "myuser", }); console.log(response);
DELETE /_security/oauth2/token { "username" : "myuser" }
Finally, the following example invalidates all access tokens and refresh tokens
for the user myuser
in the saml1
realm immediately:
resp = client.security.invalidate_token( username="myuser", realm_name="saml1", ) print(resp)
const response = await client.security.invalidateToken({ username: "myuser", realm_name: "saml1", }); console.log(response);
DELETE /_security/oauth2/token { "username" : "myuser", "realm_name" : "saml1" }
{ "invalidated_tokens":9, "previously_invalidated_tokens":15, "error_count":2, "error_details":[ { "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]" } } ] }