Add API key settings documentation (#38490) (#38499)

This commit adds missing API key service settings documentation.
elastic · Feb 6, 2019 · eccde9c · eccde9c
1 parent 5b6da65
commit eccde9c
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 1 deletion.
diff --git a/docs/reference/settings/security-settings.asciidoc b/docs/reference/settings/security-settings.asciidoc
@@ -147,6 +147,36 @@ method.
 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`.
+
+`xpack.security.authc.api_key.cache.ttl`::
+The time-to-live for cached API key entries. A API key id and a hash of its
+API key are cached for this period of time. Specify the time period using
+the standard {es} <<time-units,time units>>. Defaults to `1d`.
+
+`xpack.security.authc.api_key.cache.max_keys`::
+The maximum number of API key entries that can live in the
+cache at any given time. Defaults to 10,000.
+
+`xpack.security.authc.api_key.cache.hash_algo`:: (Expert Setting)
+The hashing algorithm that is used for the
+in-memory cached API key credentials. For possible values, see <<cache-hash-algo>>.
+Defaults to `ssha256`.
+
 [float]
 [[realm-settings]]
 ==== Realm settings

diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/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
diff --git a/...k/plugin/security/src/main/java/org/elasticsearch/xpack/security/authc/ApiKeyService.java b/...k/plugin/security/src/main/java/org/elasticsearch/xpack/security/authc/ApiKeyService.java
@@ -108,7 +108,7 @@ public class ApiKeyService {
     static final String API_KEY_LIMITED_ROLE_DESCRIPTORS_KEY = "_security_api_key_limited_by_role_descriptors";
 
     public static final Setting<String> PASSWORD_HASHING_ALGORITHM = new Setting<>(
-        "xpack.security.authc.api_key_hashing.algorithm", "pbkdf2", Function.identity(), v -> {
+        "xpack.security.authc.api_key.hashing.algorithm", "pbkdf2", Function.identity(), v -> {
         if (Hasher.getAvailableAlgoStoredHash().contains(v.toLowerCase(Locale.ROOT)) == false) {
             throw new IllegalArgumentException("Invalid algorithm: " + v + ". Valid values for password hashing are " +
                 Hasher.getAvailableAlgoStoredHash().toString());