229 lines
9.0 KiB
Plaintext
229 lines
9.0 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-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have the `manage_token` cluster privilege.
|
|
|
|
[[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`::
|
|
(Required, string) The type of grant.
|
|
Supported grant types are: `password`, `_kerberos`,
|
|
`client_credentials` and `refresh_token`.
|
|
|
|
`client_credentials`:::
|
|
This grant type implements the Client Credentials Grant of OAuth2. It is geared
|
|
for machine to machine communication and is not suitable or designed for the
|
|
self-service user creation of tokens. It generates only access tokens that
|
|
cannot be refreshed. The premise is that the entity that uses
|
|
`client_credentials` has constant access to a set of (client, not end-user)
|
|
credentials and can authenticate itself at will.
|
|
|
|
`_kerberos`:::
|
|
This grant type is supported internally and implements SPNEGO based Kerberos
|
|
support. The `_kerberos` grant type may change from version to version.
|
|
|
|
`password`:::
|
|
This grant type implements the Resource Owner Password Credentials Grant of
|
|
OAuth2. In this grant, a trusted client exchanges the end user's credentials
|
|
for an access token and (possibly) a refresh token. The request needs to be made
|
|
by an authenticated user but happens _on behalf_ of another authenticated user
|
|
(the one whose credentials are passed as request parameters). This grant type is
|
|
not suitable or designed for the self-service user creation of tokens.
|
|
|
|
`refresh_token`:::
|
|
This grant type implements the Refresh Token Grant of OAuth2.
|
|
In this grant a user exchanges a previously issued refresh token for a new access token and a new refresh token.
|
|
|
|
`password`::
|
|
(Optional^*^, 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`::
|
|
(Optional^*^, string) The 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`::
|
|
(Optional^*^, string) The string that was returned when you created the token,
|
|
which enables you to extend its life. If you specify the `refresh_token` grant
|
|
type, this parameter is required. This parameter is not valid with any other
|
|
supported grant type.
|
|
|
|
`scope`::
|
|
(Optional, 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`::
|
|
(Optional^*^, 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 |