honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Format tokens API (elastic/x-pack-elasticsearch#2578) 

* [DOCS] Format tokens API

* [DOCS] Cleaned up tokens API comment

Original commit: elastic/x-pack-elasticsearch@f818367c68
This commit is contained in:
Lisa Cawley 2017-09-22 09:56:32 -07:00 committed by GitHub
parent 5630ca6322
commit 42f90b25e3
1 changed files with 51 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/en/rest-api/security/tokens.asciidoc
View File

@ -3,10 +3,54 @@
=== Token Management APIs
The `token` API enables you to create and invalidate bearer tokens for access
without requiring basic authentication. 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.
without requiring basic authentication.
==== Request
`POST /_xpack/security/oauth2/token` +
`DELETE /_xpack/security/oauth2/token`
==== Description
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. However,
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.
@ -22,22 +66,8 @@ POST /_xpack/security/oauth2/token
--------------------------------------------------
// CONSOLE
.Token Request Fields
[cols="4,^2,10"]
|=======================
| Name | Required | Description
| `username` | yes | The username that identifies the user.
| `password` | yes | The user's password.
| `grant_type`| yes | The type of grant. Currently only the `password`
grant type is supported.
| `scope` | no | The scope of the token. Currently tokens are only
issued for a scope of `FULL` regardless of the value
sent with the request.
|=======================
A successful 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 following example output contains the access token, the amount of time (in
seconds) that the token expires in, and the type:
[source,js]
--------------------------------------------------
@ -49,9 +79,6 @@ available.
--------------------------------------------------
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
A successful call returns a JSON structure that shows whether the user has been
created or updated.
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`.
@ -62,10 +89,8 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
--------------------------------------------------
[[security-api-invalidate-token]]
The tokens returned from this API have a finite period of time for which they
are valid and after that time period, they can no longer be used. However, if
a token must be invalidated immediately, you can do so by submitting a DELETE
request to `/_xpack/security/oauth2/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]
--------------------------------------------------