mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-03 09:29:11 +00:00
5d9c270608
This change adds support for the client credentials grant type to the token api. The client credentials grant allows for a client to authenticate with the authorization server and obtain a token to access as itself. Per RFC 6749, a refresh token should not be included with the access token and as such a refresh token is not issued when the client credentials grant is used. The addition of the client credentials grant will allow users authenticated with mechanisms such as kerberos or PKI to obtain a token that can be used for subsequent access.
160 lines
5.8 KiB
Plaintext
160 lines
5.8 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-get-token]]
|
|
=== Get token API
|
|
|
|
Creates a bearer token for access without requiring basic authentication.
|
|
|
|
==== Request
|
|
|
|
`POST /_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
|
|
<<security-api-invalidate-token,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. Supported grant types are: `password`,
|
|
`client_credentials` and `refresh_token`.
|
|
|
|
`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.
|
|
|
|
`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
|
|
|
|
The following example obtains a token using the `client_credentials` grant type,
|
|
which simply creates a token as the authenticated user:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_xpack/security/oauth2/token
|
|
{
|
|
"grant_type" : "client_credentials"
|
|
}
|
|
--------------------------------------------------
|
|
// 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
|
|
}
|
|
--------------------------------------------------
|
|
// 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,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, the type, and the refresh token:
|
|
|
|
[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-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,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/] |