Skip to content

Commit

Permalink
Add API key settings documentation (#38490)
Browse files Browse the repository at this point in the history
This commit adds missing
API key service settings documentation.
  • Loading branch information
bizybot authored Feb 6, 2019
1 parent a7046e0 commit 6ff4a8c
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 1 deletion.
30 changes: 30 additions & 0 deletions docs/reference/settings/security-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,36 @@ 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`.

`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
Expand Down
12 changes: 12 additions & 0 deletions x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,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());
Expand Down

0 comments on commit 6ff4a8c

Please sign in to comment.