159 lines
5.5 KiB
Plaintext
159 lines
5.5 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-tokens]]
|
|
=== Token Management APIs
|
|
|
|
The `token` API enables you to create and invalidate bearer tokens for access
|
|
without requiring basic authentication.
|
|
|
|
==== Request
|
|
|
|
`POST /_xpack/security/oauth2/token` +
|
|
|
|
`DELETE /_xpack/security/oauth2/token`
|
|
|
|
==== Description
|
|
|
|
The tokens are created by the {es} Token Service, which is automatically enabled
|
|
when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
|
|
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
|
|
except for the use of a JSON request body.
|
|
|
|
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
|
|
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.
|
|
|
|
|
|
==== Request Body
|
|
|
|
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.
|
|
|
|
`password` (required)::
|
|
(string) The user's password.
|
|
|
|
`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.
|
|
|
|
==== Examples
|
|
[[security-api-get-token]]
|
|
To obtain a token, submit a POST request to the `/_xpack/security/oauth2/token`
|
|
endpoint.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_xpack/security/oauth2/token
|
|
{
|
|
"grant_type" : "password",
|
|
"username" : "test_admin",
|
|
"password" : "x-pack-test-password"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The following example output contains the access token, the amount of time (in
|
|
seconds) that the token expires in, and the type:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
|
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
|
|
|
The token returned by this API can be used by sending a request with a
|
|
`Authorization` header with a value having the prefix `Bearer ` followed
|
|
by the value of the `access_token`.
|
|
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
|
|
--------------------------------------------------
|
|
|
|
[[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.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_xpack/security/oauth2/token
|
|
{
|
|
"grant_type": "refresh_token",
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// 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.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// 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.
|