Add API key settings documentation

docs/reference/settings/security-settings.asciidoc

@@ -144,6 +144,22 @@ Set to `false` to disable the built-in token service. Defaults to `true` unless
 The length of time that a token is valid for. By default this value is `20m` or
 20 minutes. The maximum value is 1 hour.
 
+[float]
+[[api-key-service-settings]]
+==== API key service settings
+
+You can set the following API key service settings in
+`elasticsearch.yml`.
+
+`xpack.security.authc.api_key.enabled`::
+Set to `false` to disable the built-in API key service. Defaults to `true` unless
+ `xpack.security.http.ssl.enabled` is `false`. This prevents sniffing the API key
+  from a connection over plain http.
+
+`xpack.security.authc.api_key_hashing.algorithm`::
+Specifies the hashing algorithm that is used for securing API key credentials. 
+See <<password-hashing-algorithms>>. Defaults to `pbkdf2`.
+
 [float]
 [[realm-settings]]
 ==== Realm settings

x-pack/docs/en/rest-api/security/create-api-keys.asciidoc

@@ -24,6 +24,8 @@ applicable for the API key in milliseconds.
 NOTE: By default API keys never expire. You can specify expiration at the time of 
 creation for the API keys. 
 
+See <<api-key-service-settings>> for configuration settings related to API key service.
+
 ==== Request Body
 
 The following parameters can be specified in the body of a POST or PUT request:
@@ -97,3 +99,13 @@ API key information.
 <1> unique id for this API key
 <2> optional expiration in milliseconds for this API key
 <3> generated API key
+
+The API key returned by this API can then be used by sending a request with a
+`Authorization` header with a value having the prefix `ApiKey ` followed
+by the _credentials_, where _credentials_ is the base64 encoding of `id` and `api_key` joined by a colon.
+
+[source,shell]
+--------------------------------------------------
+curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE

x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/security/authz/permission/Role.java

@@ -48,7 +48,6 @@ public class Role {
         this.runAs = Objects.requireNonNull(runAs);
     }
 
-
     public String[] names() {
         return names;
     }

x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/authc/TokenService.java

@@ -157,7 +157,7 @@ public final class TokenService {
 
     public static final String THREAD_POOL_NAME = XPackField.SECURITY + "-token-key";
     public static final Setting<TimeValue> TOKEN_EXPIRATION = Setting.timeSetting("xpack.security.authc.token.timeout",
-            TimeValue.timeValueMinutes(20L), TimeValue.timeValueSeconds(1L), Property.NodeScope);
+            TimeValue.timeValueMinutes(20L), TimeValue.timeValueSeconds(1L), TimeValue.timeValueHours(1L), Property.NodeScope);
     public static final Setting<TimeValue> DELETE_INTERVAL = Setting.timeSetting("xpack.security.authc.token.delete.interval",
             TimeValue.timeValueMinutes(30L), Property.NodeScope);
     public static final Setting<TimeValue> DELETE_TIMEOUT = Setting.timeSetting("xpack.security.authc.token.delete.timeout",

x-pack/plugin/security/src/test/java/org/elasticsearch/xpack/security/authc/TokenServiceTests.java

@@ -66,6 +66,7 @@
 import static java.time.Clock.systemUTC;
 import static org.elasticsearch.repositories.ESBlobStoreTestCase.randomBytes;
 import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.notNullValue;
 import static org.hamcrest.Matchers.nullValue;
 import static org.mockito.Matchers.any;
@@ -414,6 +415,29 @@ public void testComputeSecretKeyIsConsistent() throws Exception {
         assertArrayEquals(key.getEncoded(), key2.getEncoded());
     }
 
+    public void testTokenExpiryConfig() {
+        TimeValue expiration =  TokenService.TOKEN_EXPIRATION.get(tokenServiceEnabledSettings);
+        assertThat(expiration, equalTo(TimeValue.timeValueMinutes(20L)));
+        // Configure Minimum expiration
+        tokenServiceEnabledSettings = Settings.builder().put(TokenService.TOKEN_EXPIRATION.getKey(), "1s").build();
+        expiration =  TokenService.TOKEN_EXPIRATION.get(tokenServiceEnabledSettings);
+        assertThat(expiration, equalTo(TimeValue.timeValueSeconds(1L)));
+        // Configure Maximum expiration
+        tokenServiceEnabledSettings = Settings.builder().put(TokenService.TOKEN_EXPIRATION.getKey(), "60m").build();
+        expiration =  TokenService.TOKEN_EXPIRATION.get(tokenServiceEnabledSettings);
+        assertThat(expiration, equalTo(TimeValue.timeValueHours(1L)));
+        // Outside range should fail
+        tokenServiceEnabledSettings = Settings.builder().put(TokenService.TOKEN_EXPIRATION.getKey(), "1ms").build();
+        IllegalArgumentException ile = expectThrows(IllegalArgumentException.class,
+                () -> TokenService.TOKEN_EXPIRATION.get(tokenServiceEnabledSettings));
+        assertThat(ile.getMessage(),
+                containsString("failed to parse value [1ms] for setting [xpack.security.authc.token.timeout], must be >= [1s]"));
+        tokenServiceEnabledSettings = Settings.builder().put(TokenService.TOKEN_EXPIRATION.getKey(), "120m").build();
+        ile = expectThrows(IllegalArgumentException.class, () -> TokenService.TOKEN_EXPIRATION.get(tokenServiceEnabledSettings));
+        assertThat(ile.getMessage(),
+                containsString("failed to parse value [120m] for setting [xpack.security.authc.token.timeout], must be <= [1h]"));
+    }
+
     public void testTokenExpiry() throws Exception {
         ClockMock clock = ClockMock.frozen();
         TokenService tokenService = new TokenService(tokenServiceEnabledSettings, clock, client, securityIndex, clusterService);