202 lines
7.7 KiB
Plaintext
202 lines
7.7 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-get-token]]
|
|
=== Get token API
|
|
++++
|
|
<titleabbrev>Get token</titleabbrev>
|
|
++++
|
|
|
|
Creates a bearer token for access without requiring basic authentication.
|
|
|
|
[[security-api-get-token-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/oauth2/token`
|
|
|
|
|
|
[[security-api-get-token-desc]]
|
|
==== {api-description-title}
|
|
|
|
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
|
|
<<security-api-invalidate-token,invalidate token API>>.
|
|
|
|
|
|
[[security-api-get-token-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
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. Supported grant types are: `password`, `_kerberos`,
|
|
`client_credentials` and `refresh_token`. The `_kerberos` grant type
|
|
is supported internally and implements SPNEGO based Kerberos support. The `_kerberos`
|
|
grant type may change from version to version.
|
|
|
|
`password`::
|
|
(string) The user's password. If you specify the `password` grant type, this
|
|
parameter is required. This parameter is not valid with any other supported
|
|
grant type.
|
|
|
|
`kerberos_ticket`::
|
|
(string) base64 encoded kerberos ticket. If you specify the `_kerberos` grant type,
|
|
this parameter is required. This parameter is not valid with any other supported
|
|
grant type.
|
|
|
|
`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. This parameter is not valid with any other
|
|
supported grant type.
|
|
|
|
`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`::
|
|
(string) The username that identifies the user. If you specify the `password`
|
|
grant type, this parameter is required. This parameter is not valid with any
|
|
other supported grant type.
|
|
|
|
[[security-api-get-token-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example obtains a token using the `client_credentials` grant type,
|
|
which simply creates a token as the authenticated user:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type" : "client_credentials"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The following example output contains the access token, the amount of time (in
|
|
seconds) that the token expires in, and the type:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_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
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
The following example obtains a token for the `test_admin` user using the
|
|
`password` grant type:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type" : "password",
|
|
"username" : "test_admin",
|
|
"password" : "x-pack-test-password"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The following example output contains the access token, the amount of time (in
|
|
seconds) that the token expires in, the type, and the refresh token:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"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-refresh-token]]
|
|
To extend the life of an existing token obtained using the `password` grant type,
|
|
you can call the API again with the refresh token within 24 hours of the token's
|
|
creation. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type": "refresh_token",
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// 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,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
|
|
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
|
|
|
|
The following example obtains a access token and refresh token using the `kerberos` grant type,
|
|
which simply creates a token in exchange for the base64 encoded kerberos ticket:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_security/oauth2/token
|
|
{
|
|
"grant_type" : "_kerberos",
|
|
"kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
The API will return a new token and refresh token if kerberos authentication is successful.
|
|
Each refresh token may only be used one time. When the mutual authentication is requested in the Spnego GSS context,
|
|
a base64 encoded token will be returned by the server in the `kerberos_authentication_response_token`
|
|
for clients to consume and finalize the authentication.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
|
|
"type" : "Bearer",
|
|
"expires_in" : 1200,
|
|
"refresh_token": "vLBPvmAB6KvwvJZr27cS"
|
|
"kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg"
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE |