From cdc953c2ced9063678de12beb31b5e291ba07477 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 7 Aug 2019 16:39:32 -0700 Subject: [PATCH 1/3] [DOCS] Edits the get tokens API --- .../en/rest-api/security/get-tokens.asciidoc | 46 ++++++++++--------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc index 6d5644fd38a01..3e63153d1b5bc 100644 --- a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc @@ -12,6 +12,10 @@ Creates a bearer token for access without requiring basic authentication. `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} @@ -37,24 +41,6 @@ information, see <>. If you want to invalidate a token immediately, you can do so by using the <>. -Using the Get Token API requires the `manage_token` cluster privilege. - -==== Grant Types - -Grant type `password` 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 self-service user creation of tokens. - -Grant type `client_credentials` implements the Client Credentials Grant of -OAuth2. This grant type is geared for machine to machine communication and is not -suitable or designed for self-service user creation of tokens. It will only -generate access tokens that cannot be refreshed as 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. - [[security-api-get-token-request-body]] ==== {api-request-body-title} @@ -63,9 +49,27 @@ 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. +`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. `password`:: (string) The user's password. If you specify the `password` grant type, this From 4ea6862e31d8c121358f520e216c455ba102428e Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Mon, 12 Aug 2019 14:21:24 +0300 Subject: [PATCH 2/3] add refresh token info --- x-pack/docs/en/rest-api/security/get-tokens.asciidoc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc index 3e63153d1b5bc..692f53decb6d8 100644 --- a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc @@ -48,7 +48,8 @@ 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`, +(Required, string) The type of grant. +Supported grant types are: `password`, `_kerberos`, `client_credentials` and `refresh_token`. `client_credentials`::: @@ -71,8 +72,12 @@ 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`:: -(string) The user's password. If you specify the `password` grant type, this +(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. From 07564942c351e0d15a6dd46ae2afc7021ea3a23c Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 5 Sep 2019 08:49:51 -0700 Subject: [PATCH 3/3] [DOCS] Identifies required and optional parameters --- .../en/rest-api/security/get-tokens.asciidoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc index 692f53decb6d8..7a3eb9545dffc 100644 --- a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc @@ -77,27 +77,27 @@ 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`:: -(string) The user's password. If you specify the `password` grant type, this +(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`:: -(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. +(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`:: -(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 +(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`:: -(string) The scope of the token. Currently tokens are only issued for a scope of +(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`:: -(string) The username that identifies the user. If you specify the `password` +(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.