Get token API

edit

Creates a bearer token for access without requiring basic authentication.

Request

edit

POST /_security/oauth2/token

Description

edit

The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. See Encrypting HTTP Client communications. 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 invalidate token API.

Request body

edit

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.

Examples

edit

The following example obtains a token using the client_credentials grant type, which simply creates a token as the authenticated user:

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:

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200
}

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.

curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health

The following example obtains a token for the test_admin user using the password grant type:

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:

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

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:

POST /_security/oauth2/token
{
    "grant_type": "refresh_token",
    "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

The API will return a new token and refresh token. Each refresh token may only be used one time.

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

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:

POST /_security/oauth2/token
{
  "grant_type" : "_kerberos",
  "kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
}

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.

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  "kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg"
}