Token API supports the client_credentials grant (#33106)

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.

x-pack/docs/en/rest-api/security/get-tokens.asciidoc

@@ -38,36 +38,39 @@ 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. Valid grant types are: `password` and `refresh_token`.
+(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. 
+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.
+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. 
+grant type, this parameter is required. This parameter is not valid with any
+other supported grant type.
 
 ==== Examples
 
-The following example obtains a token for the `test_admin` user:
+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" : "password",
-  "username" : "test_admin",
-  "password" : "x-pack-test-password"
+  "grant_type" : "client_credentials"
 }
 --------------------------------------------------
 // CONSOLE
@@ -80,12 +83,10 @@ seconds) that the token expires in, and the type:
 {
   "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
   "type" : "Bearer",
-  "expires_in" : 1200,
-  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
+  "expires_in" : 1200
 }
 --------------------------------------------------
 // TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
-// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_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
@@ -97,9 +98,39 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
 --------------------------------------------------
 // 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, you can call the API again with the 
-refresh token within 24 hours of the token's creation. For example:
+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]
 --------------------------------------------------

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/security/action/token/CreateTokenRequest.java

@@ -19,6 +19,10 @@
 
 import java.io.IOException;
 import java.util.Arrays;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Set;
+import java.util.stream.Collectors;
 
 import static org.elasticsearch.action.ValidateActions.addValidationError;
 
@@ -29,6 +33,37 @@
  */
 public final class CreateTokenRequest extends ActionRequest {
 
+    public enum GrantType {
+        PASSWORD("password"),
+        REFRESH_TOKEN("refresh_token"),
+        AUTHORIZATION_CODE("authorization_code"),
+        CLIENT_CREDENTIALS("client_credentials");
+
+        private final String value;
+
+        GrantType(String value) {
+            this.value = value;
+        }
+
+        public String getValue() {
+            return value;
+        }
+
+        public static GrantType fromString(String grantType) {
+            if (grantType != null) {
+                for (GrantType type : values()) {
+                    if (type.getValue().equals(grantType)) {
+                        return type;
+                    }
+                }
+            }
+            return null;
+        }
+    }
+
+    private static final Set<GrantType> SUPPORTED_GRANT_TYPES = Collections.unmodifiableSet(
+        EnumSet.of(GrantType.PASSWORD, GrantType.REFRESH_TOKEN, GrantType.CLIENT_CREDENTIALS));
+
     private String grantType;
     private String username;
     private SecureString password;
@@ -49,33 +84,58 @@ public CreateTokenRequest(String grantType, @Nullable String username, @Nullable
     @Override
     public ActionRequestValidationException validate() {
         ActionRequestValidationException validationException = null;
-        if ("password".equals(grantType)) {
-            if (Strings.isNullOrEmpty(username)) {
-                validationException = addValidationError("username is missing", validationException);
-            }
-            if (password == null || password.getChars() == null || password.getChars().length == 0) {
-                validationException = addValidationError("password is missing", validationException);
-            }
-            if (refreshToken != null) {
-                validationException =
-                        addValidationError("refresh_token is not supported with the password grant_type", validationException);
-            }
-        } else if ("refresh_token".equals(grantType)) {
-            if (username != null) {
-                validationException =
-                        addValidationError("username is not supported with the refresh_token grant_type", validationException);
-            }
-            if (password != null) {
-                validationException =
-                        addValidationError("password is not supported with the refresh_token grant_type", validationException);
-            }
-            if (refreshToken == null) {
-                validationException = addValidationError("refresh_token is missing", validationException);
+        GrantType type = GrantType.fromString(grantType);
+        if (type != null) {
+            switch (type) {
+                case PASSWORD:
+                    if (Strings.isNullOrEmpty(username)) {
+                        validationException = addValidationError("username is missing", validationException);
+                    }
+                    if (password == null || password.getChars() == null || password.getChars().length == 0) {
+                        validationException = addValidationError("password is missing", validationException);
+                    }
+                    if (refreshToken != null) {
+                        validationException =
+                            addValidationError("refresh_token is not supported with the password grant_type", validationException);
+                    }
+                    break;
+                case REFRESH_TOKEN:
+                    if (username != null) {
+                        validationException =
+                            addValidationError("username is not supported with the refresh_token grant_type", validationException);
+                    }
+                    if (password != null) {
+                        validationException =
+                            addValidationError("password is not supported with the refresh_token grant_type", validationException);
+                    }
+                    if (refreshToken == null) {
+                        validationException = addValidationError("refresh_token is missing", validationException);
+                    }
+                    break;
+                case CLIENT_CREDENTIALS:
+                    if (username != null) {
+                        validationException =
+                            addValidationError("username is not supported with the client_credentials grant_type", validationException);
+                    }
+                    if (password != null) {
+                        validationException =
+                            addValidationError("password is not supported with the client_credentials grant_type", validationException);
+                    }
+                    if (refreshToken != null) {
+                        validationException = addValidationError("refresh_token is not supported with the client_credentials grant_type",
+                            validationException);
+                    }
+                    break;
+                default:
+                    validationException = addValidationError("grant_type only supports the values: [" +
+                            SUPPORTED_GRANT_TYPES.stream().map(GrantType::getValue).collect(Collectors.joining(", ")) + "]",
+                        validationException);
             }
         } else {
-            validationException = addValidationError("grant_type only supports the values: [password, refresh_token]", validationException);
+            validationException = addValidationError("grant_type only supports the values: [" +
+                    SUPPORTED_GRANT_TYPES.stream().map(GrantType::getValue).collect(Collectors.joining(", ")) + "]",
+                validationException);
         }
-
         return validationException;
     }
 
@@ -126,6 +186,11 @@ public String getRefreshToken() {
     @Override
     public void writeTo(StreamOutput out) throws IOException {
         super.writeTo(out);
+        if (out.getVersion().before(Version.V_7_0_0_alpha1) && GrantType.CLIENT_CREDENTIALS.getValue().equals(grantType)) {
+            throw new IllegalArgumentException("a request with the client_credentials grant_type cannot be sent to version [" +
+                out.getVersion() + "]");
+        }
+
         out.writeString(grantType);
         if (out.getVersion().onOrAfter(Version.V_6_2_0)) {
             out.writeOptionalString(username);

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/security/action/token/CreateTokenResponse.java

@@ -59,8 +59,14 @@ public void writeTo(StreamOutput out) throws IOException {
         out.writeString(tokenString);
         out.writeTimeValue(expiresIn);
         out.writeOptionalString(scope);
-        if (out.getVersion().onOrAfter(Version.V_6_2_0)) {
-            out.writeString(refreshToken);
+        if (out.getVersion().onOrAfter(Version.V_7_0_0_alpha1)) { // TODO change to V_6_5_0 after backport
+            out.writeOptionalString(refreshToken);
+        } else if (out.getVersion().onOrAfter(Version.V_6_2_0)) {
+            if (refreshToken == null) {
+                out.writeString("");
+            } else {
+                out.writeString(refreshToken);
+            }
         }
     }
 
@@ -70,7 +76,9 @@ public void readFrom(StreamInput in) throws IOException {
         tokenString = in.readString();
         expiresIn = in.readTimeValue();
         scope = in.readOptionalString();
-        if (in.getVersion().onOrAfter(Version.V_6_2_0)) {
+        if (in.getVersion().onOrAfter(Version.V_7_0_0_alpha1)) { // TODO change to V_6_5_0 after backport
+            refreshToken = in.readOptionalString();
+        } else if (in.getVersion().onOrAfter(Version.V_6_2_0)) {
             refreshToken = in.readString();
         }
     }
@@ -90,4 +98,20 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
         }
         return builder.endObject();
     }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        CreateTokenResponse that = (CreateTokenResponse) o;
+        return Objects.equals(tokenString, that.tokenString) &&
+            Objects.equals(expiresIn, that.expiresIn) &&
+            Objects.equals(scope, that.scope) &&
+            Objects.equals(refreshToken, that.refreshToken);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(tokenString, expiresIn, scope, refreshToken);
+    }
 }

x-pack/plugin/security/src/test/java/org/elasticsearch/xpack/security/action/token/CreateTokenRequestTests.java → x-pack/plugin/core/src/test/java/org/elasticsearch/xpack/core/security/action/token/CreateTokenRequestTests.java

@@ -3,7 +3,7 @@
  * or more contributor license agreements. Licensed under the Elastic License;
  * you may not use this file except in compliance with the Elastic License.
  */
-package org.elasticsearch.xpack.security.action.token;
+package org.elasticsearch.xpack.core.security.action.token;
 
 import org.elasticsearch.action.ActionRequestValidationException;
 import org.elasticsearch.common.settings.SecureString;
@@ -20,7 +20,7 @@ public void testRequestValidation() {
         ActionRequestValidationException ve = request.validate();
         assertNotNull(ve);
         assertEquals(1, ve.validationErrors().size());
-        assertThat(ve.validationErrors().get(0), containsString("[password, refresh_token]"));
+        assertThat(ve.validationErrors().get(0), containsString("[password, refresh_token, client_credentials]"));
         assertThat(ve.validationErrors().get(0), containsString("grant_type"));
 
         request.setGrantType("password");
@@ -72,5 +72,19 @@ public void testRequestValidation() {
         assertNotNull(ve);
         assertEquals(1, ve.validationErrors().size());
         assertThat(ve.validationErrors(), hasItem("refresh_token is missing"));
+
+        request.setGrantType("client_credentials");
+        ve = request.validate();
+        assertNull(ve);
+
+        request.setUsername(randomAlphaOfLengthBetween(1, 32));
+        request.setPassword(new SecureString(randomAlphaOfLengthBetween(1, 32).toCharArray()));
+        request.setRefreshToken(randomAlphaOfLengthBetween(1, 32));
+        ve = request.validate();
+        assertNotNull(ve);
+        assertEquals(3, ve.validationErrors().size());
+        assertThat(ve.validationErrors(), hasItem(containsString("username is not supported")));
+        assertThat(ve.validationErrors(), hasItem(containsString("password is not supported")));
+        assertThat(ve.validationErrors(), hasItem(containsString("refresh_token is not supported")));
     }
 }