diff --git a/docs/reference/settings/security-hash-settings.asciidoc b/docs/reference/settings/security-hash-settings.asciidoc index 1f6ca2a25e3..9cc2d960db7 100644 --- a/docs/reference/settings/security-hash-settings.asciidoc +++ b/docs/reference/settings/security-hash-settings.asciidoc @@ -6,8 +6,8 @@ Certain realms store user credentials in memory. To limit exposure to credential theft and mitigate credential compromise, the cache only stores a hashed version of the user credentials in memory. By default, the user cache is hashed with a salted `sha-256` hash algorithm. You can use a different -hashing algorithm by setting the `cache.hash_algo` realm settings to any of the -following values: +hashing algorithm by setting the <> +`cache.hash_algo` realm settings to any of the following values: [[cache-hash-algo]] .Cache hash algorithms @@ -43,10 +43,11 @@ following values: memory dumps and using `ptrace`). |======================= -Likewise, realms that store passwords hash them using cryptographically strong -and password-specific salt values. You can configure the algorithm for password -hashing by setting the `xpack.security.authc.password_hashing.algorithm` setting -to one of the following: +Likewise, realms that store passwords hash them using cryptographically strong +and password-specific salt values. You can configure the algorithm for password +hashing by setting the <> +`xpack.security.authc.password_hashing.algorithm` setting to one of the +following: [[password-hashing-algorithms]] .Password hashing algorithms diff --git a/docs/reference/settings/security-settings.asciidoc b/docs/reference/settings/security-settings.asciidoc index 7780dc97a88..4fffea07529 100644 --- a/docs/reference/settings/security-settings.asciidoc +++ b/docs/reference/settings/security-settings.asciidoc @@ -26,6 +26,7 @@ For more information about creating and updating the {es} keystore, see [[general-security-settings]] ==== General security settings `xpack.security.enabled`:: +(<>) Set to `true` to enable {es} {security-features} on the node. + + -- @@ -42,6 +43,7 @@ recommend that you explicitly add this setting to avoid confusion. -- `xpack.security.hide_settings`:: +(<>) A comma-separated list of settings that are omitted from the results of the <>. You can use wildcards to include multiple settings in the list. For example, the following value hides all the @@ -51,28 +53,35 @@ The API already omits all `ssl` settings, `bind_dn`, and `bind_password` due to the sensitive nature of the information. `xpack.security.fips_mode.enabled`:: +(<>) Enables fips mode of operation. Set this to `true` if you run this {es} instance in a FIPS 140-2 enabled JVM. For more information, see <>. Defaults to `false`. [discrete] [[password-hashing-settings]] ==== Password hashing settings + `xpack.security.authc.password_hashing.algorithm`:: +(<>) Specifies the hashing algorithm that is used for secure user credential storage. See <>. Defaults to `bcrypt`. [discrete] [[anonymous-access-settings]] ==== Anonymous access settings + You can configure the following anonymous access settings in `elasticsearch.yml`. For more information, see <>. `xpack.security.authc.anonymous.username`:: +(<>) The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`. `xpack.security.authc.anonymous.roles`:: +(<>) The roles to associate with the anonymous user. Required. `xpack.security.authc.anonymous.authz_exception`:: +(<>) When `true`, an HTTP 403 response is returned if the anonymous user does not have the appropriate permissions for the requested action. The user is not prompted to provide credentials to access the requested @@ -83,27 +92,32 @@ access. Defaults to `true`. [discrete] [[security-automata-settings]] ==== Automata Settings + In places where the {security-features} accept wildcard patterns (e.g. index patterns in roles, group matches in the role mapping API), each pattern is compiled into an Automaton. The follow settings are available to control this behaviour. `xpack.security.automata.max_determinized_states`:: +(<>) The upper limit on how many automaton states may be created by a single pattern. This protects against too-difficult (e.g. exponentially hard) patterns. Defaults to `100,000`. `xpack.security.automata.cache.enabled`:: +(<>) Whether to cache the compiled automata. Compiling automata can be CPU intensive and may slowdown some operations. The cache reduces the frequency with which automata need to be compiled. Defaults to `true`. `xpack.security.automata.cache.size`:: +(<>) The maximum number of items to retain in the automata cache. Defaults to `10,000`. `xpack.security.automata.cache.ttl`:: +(<>) The length of time to retain in an item in the automata cache (based on most recent usage). Defaults to `48h` (48 hours). @@ -117,16 +131,19 @@ settings in `elasticsearch.yml`. For more information, see <>. `xpack.security.dls_fls.enabled`:: +(<>) Set to `false` to prevent document and field level security from being configured. Defaults to `true`. `xpack.security.dls.bitset.cache.ttl`:: +(<>) The time-to-live for cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Defaults to expire entries that are unused for `168h` (7 days). `xpack.security.dls.bitset.cache.size`:: +(<>) The maximum memory usage of cached `BitSet` entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Defaults to `50mb`, after which @@ -140,11 +157,13 @@ You can set the following token service settings in `elasticsearch.yml`. `xpack.security.authc.token.enabled`:: +(<>) Set to `false` to disable the built-in token service. Defaults to `true` unless `xpack.security.http.ssl.enabled` is `false`. This prevents sniffing the token from a connection over plain http. `xpack.security.authc.token.timeout`:: +(<>) 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. @@ -156,24 +175,29 @@ 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 <>. 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} <>. 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) +`xpack.security.authc.api_key.cache.hash_algo`:: +(<>, Expert) The hashing algorithm that is used for the in-memory cached API key credentials. For possible values, see <>. Defaults to `ssha256`. @@ -217,11 +241,13 @@ information, see <>. ===== Settings valid for all realms // tag::realm-order-tag[] `order`:: +(<>) The priority of the realm within the realm chain. Realms with a lower order are consulted first. Although not required, use of this setting is strongly recommended when you configure multiple realms. Defaults to `Integer.MAX_VALUE`. `enabled`:: +(<>) Indicates whether a realm is enabled. You can use this setting to disable a realm without removing its configuration information. Defaults to `true`. @@ -232,18 +258,26 @@ For a native realm, the `type` must be set to `native`. In addition to the <>, you can specify the following optional settings: -`cache.ttl`:: The time-to-live for cached user entries. A user and a hash of its +`cache.ttl`:: +(<>) +The time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Specify the time period using the standard {es} <>. Defaults to `20m`. -`cache.max_users`:: The maximum number of user entries that can live in the +`cache.max_users`:: +(<>) +The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. -`cache.hash_algo`:: (Expert Setting) The hashing algorithm that is used for the +`cache.hash_algo`:: +(<>, Expert) +The hashing algorithm that is used for the in-memory cached user credentials. For possible values, see <>. Defaults to `ssha256`. -`authentication.enabled`:: If set to `false`, disables authentication support in +`authentication.enabled`:: +(<>) +If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the <> and <> features). @@ -259,20 +293,25 @@ The `type` setting must be set to `file`. In addition to the the following settings: `cache.ttl`:: +(<>) The time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Defaults to `20m`. Specify values using the standard {es} <>. Defaults to `20m`. `cache.max_users`:: +(<>) The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. `cache.hash_algo`:: -(Expert Setting) The hashing algorithm that is used for the in-memory cached +(<>, Expert) +The hashing algorithm that is used for the in-memory cached user credentials. See <>. Defaults to `ssha256`. -`authentication.enabled`:: If set to `false`, disables authentication support in +`authentication.enabled`:: +(<>) +If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the <> and <> features). @@ -286,6 +325,7 @@ The `type` setting must be set to `ldap`. In addition to the <>, you can specify the following settings: `url`:: +(<>) One or more LDAP URLs in the `ldap[s]://:` format. Required. + To provide multiple URLs, use a YAML array (`["ldap://server1:636", "ldap://server2:636"]`) @@ -294,16 +334,19 @@ or comma-separated string (`"ldap://server1:636, ldap://server2:636"`). While both are supported, you can't mix the `ldap` and `ldaps` protocols. `load_balance.type`:: +(<>) The behavior to use when there are multiple LDAP URLs defined. For supported values see <>. Defaults to `failover`. `load_balance.cache_ttl`:: +(<>) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. `bind_dn`:: +(<>) The DN of the user that is used to bind to the LDAP and perform searches. Only applicable in user search mode. If not specified, an anonymous bind is attempted. @@ -311,17 +354,19 @@ Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the <>. `bind_password`:: +(<>) deprecated[6.3] Use `secure_bind_password` instead. The password for the user that is used to bind to the LDAP directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the <>. - -`secure_bind_password` (<>):: +`secure_bind_password`:: +(<>) The password for the user that is used to bind to the LDAP directory. Defaults to Empty. `user_dn_templates`:: +(<>) The DN template that replaces the user name with the string `{0}`. This setting is multivalued; you can specify multiple user contexts. Required to operate in user template mode. If `user_search.base_dn` is specified, @@ -329,6 +374,7 @@ this setting is not valid. For more information on the different modes, see <>. `authorization_realms`:: +(<>) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the LDAP realm does not perform role mapping and instead loads the user from the listed realms. The referenced realms are @@ -342,17 +388,20 @@ NOTE: If any settings starting with `user_search` are specified, the -- `user_group_attribute`:: +(<>) Specifies the attribute to examine on the user for group membership. If any `group_search` settings are specified, this setting is ignored. Defaults to `memberOf`. `user_search.base_dn`:: +(<>) Specifies a container DN to search for users. Required to operated in user search mode. If `user_dn_templates` is specified, this setting is not valid. For more information on the different modes, see <>. `user_search.scope`:: +(<>) The scope of the user search. Valid values are `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. @@ -360,48 +409,58 @@ The scope of the user search. Valid values are `sub_tree`, `one_level` or the only user considered. Defaults to `sub_tree`. `user_search.filter`:: +(<>) Specifies the filter used to search the directory in attempts to match an entry with the username provided by the user. Defaults to `(uid={0})`. `{0}` is substituted with the username provided when searching. `user_search.attribute`:: +(<>) deprecated[5.6] Use `user_search.filter` instead. The attribute to match with the username sent with the request. Defaults to `uid`. `user_search.pool.enabled`:: +(<>) Enables or disables connection pooling for user search. If set to `false`, a new connection is created for every search. The default is `true` when `bind_dn` is set. `user_search.pool.size`:: +(<>) The maximum number of connections to the LDAP server to allow in the connection pool. Defaults to `20`. `user_search.pool.initial_size`:: +(<>) The initial number of connections to create to the LDAP server on startup. Defaults to `0`. If the LDAP server is down, values greater than `0` could cause startup failures. `user_search.pool.health_check.enabled`:: +(<>) Enables or disables a health check on LDAP connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. `user_search.pool.health_check.dn`:: +(<>) The distinguished name that is retrieved as part of the health check. Defaults to the value of `bind_dn` if present; if not, falls back to `user_search.base_dn`. `user_search.pool.health_check.interval`:: +(<>) The interval to perform background checks of connections in the pool. Defaults to `60s`. `group_search.base_dn`:: +(<>) The container DN to search for groups in which the user has membership. When this element is absent, {es} searches for the attribute specified by `user_group_attribute` set on the user in order to determine group membership. `group_search.scope`:: +(<>) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` only searches objects directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. @@ -409,6 +468,7 @@ Specifies whether the group search should be `sub_tree`, `one_level` or only group considered. Defaults to `sub_tree`. `group_search.filter`:: +(<>) Specifies a filter to use to look up a group. When not set, the realm searches for `group`, `groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the attributes `member`, `memberOf`, or `memberUid`. Any @@ -416,133 +476,166 @@ instance of `{0}` in the filter is replaced by the user attribute defined in `group_search.user_attribute`. `group_search.user_attribute`:: +(<>) Specifies the user attribute that is fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter. Defaults to Empty. `unmapped_groups_as_roles`:: +(<>) If set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. A group is considered to be _unmapped_ if it is not referenced in a <>. API-based role mappings are not considered. Defaults to `false`. `files.role_mapping`:: +(<>) The <> for the <>. Defaults to `ES_PATH_CONF/role_mapping.yml`. `follow_referrals`:: +(<>) Specifies whether {es} should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (for example, search). Defaults to `true`. `metadata`:: +(<>) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user's metadata field. `timeout.tcp_connect`:: +(<>) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `timeout.tcp_read`:: +(<>) deprecated[7.7] The TCP read timeout period after establishing an LDAP connection. This is equivalent to and is deprecated in favor of `timeout.response` and they cannot be used simultaneously. An `s` at the end indicates seconds, or `ms` indicates milliseconds. `timeout.response`:: +(<>) The time interval to wait for the response from the LDAP server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.ldap_search`:: +(<>) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `ssl.key`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem] + If the LDAP server requires client authentication, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `ssl.key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase] -`ssl.secure_key_passphrase` (<>):: +`ssl.secure_key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase] `ssl.certificate`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate] + This certificate is presented to clients when they connect. `ssl.certificate_authorities`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities] + You cannot use this setting and `ssl.truststore.path` at the same time. `ssl.keystore.path`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] + You cannot use this setting and `ssl.key` at the same time. `ssl.keystore.type`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12] `ssl.keystore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] -`ssl.keystore.secure_password` (<>):: +`ssl.keystore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] `ssl.keystore.key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] `ssl.keystore.secure_key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] `ssl.truststore.path`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] + You cannot use this setting and `ssl.certificate_authorities` at the same time. `ssl.truststore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] -`ssl.truststore.secure_password` (<>):: +`ssl.truststore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] `ssl.truststore.type`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11] `ssl.verification_mode`:: +(<>) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values] `ssl.supported_protocols`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols] -`ssl.cipher_suites`:: Specifies the cipher suites that should be supported when +`ssl.cipher_suites`:: +(<>) +Specifies the cipher suites that should be supported when communicating with the LDAP server. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values] `cache.ttl`:: +(<>) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {es} <>. Defaults to `20m`. `cache.max_users`:: +(<>) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `cache.hash_algo`:: -(Expert Setting) Specifies the hashing algorithm that is used for the +(<>, Expert) +Specifies the hashing algorithm that is used for the in-memory cached user credentials. See <>. Defaults to `ssha256`. -`authentication.enabled`:: If set to `false`, disables authentication support in +`authentication.enabled`:: +(<>) +If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the <> and <> features). @@ -557,6 +650,7 @@ The `type` setting must be set to `active_directory`. In addition to the the following settings: `url`:: +(<>) One or more LDAP URLs in the `ldap[s]://:` format. Defaults to `ldap://:389`. This setting is required when connecting using SSL/TLS or when using a custom port. @@ -571,50 +665,60 @@ default uses the `domain_name` setting value and assumes an unencrypted connection to port 389. `load_balance.type`:: +(<>) The behavior to use when there are multiple LDAP URLs defined. For supported values see <>. Defaults to `failover`. `load_balance.cache_ttl`:: +(<>) When using `dns_failover` or `dns_round_robin` as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. `domain_name`:: +(<>) The domain name of Active Directory. If the `url` and the `user_search.base_dn` settings are not specified, the cluster can derive those values from this setting. Required. `bind_dn`:: +(<>) The DN of the user that is used to bind to Active Directory and perform searches. Defaults to Empty. Due to its potential security impact, `bind_dn` is not exposed via the <>. `bind_password`:: +(<>) deprecated[6.3] Use `secure_bind_password` instead. The password for the user that is used to bind to Active Directory. Defaults to Empty. Due to its potential security impact, `bind_password` is not exposed via the <>. -`secure_bind_password` (<>):: +`secure_bind_password`:: +(<>) The password for the user that is used to bind to Active Directory. Defaults to Empty. `unmapped_groups_as_roles`:: +(<>) If set to `true`, the names of any unmapped Active Directory groups are used as role names and assigned to the user. A group is considered _unmapped_ when it is not referenced in any role-mapping files. API-based role mappings are not considered. Defaults to `false`. `files.role_mapping`:: +(<>) The <> for the YAML role mapping configuration file. Defaults to `ES_PATH_CONF/role_mapping.yml`. `user_search.base_dn`:: +(<>) The context to search for a user. Defaults to the root of the Active Directory domain. `user_search.scope`:: +(<>) Specifies whether the user search should be `sub_tree`, `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` @@ -622,6 +726,7 @@ specifies that the `base_dn` is a user object, and that it is the only user considered. Defaults to `sub_tree`. `user_search.filter`:: +(<>) Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`. If specified, this must be a valid LDAP user search filter. @@ -630,6 +735,7 @@ see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.upn_filter`:: +(<>) Specifies a filter to use to lookup a user given a user principal name. The default filter looks up `user` objects with a matching `userPrincipalName`. If specified, this @@ -639,6 +745,7 @@ provided by the user. For more information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.down_level_filter`:: +(<>) Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up `user` objects with a matching `sAMAccountName` in the domain provided. If specified, this @@ -647,38 +754,46 @@ must be a valid LDAP user search filter. For example, https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.pool.enabled`:: +(<>) Enables or disables connection pooling for user search. When disabled a new connection is created for every search. The default is `true` when `bind_dn` is provided. `user_search.pool.size`:: +(<>) The maximum number of connections to the Active Directory server to allow in the connection pool. Defaults to `20`. `user_search.pool.initial_size`:: +(<>) The initial number of connections to create to the Active Directory server on startup. Defaults to `0`. If the LDAP server is down, values greater than 0 could cause startup failures. `user_search.pool.health_check.enabled`:: +(<>) Enables or disables a health check on Active Directory connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. `user_search.pool.health_check.dn`:: +(<>) The distinguished name to be retrieved as part of the health check. Defaults to the value of `bind_dn` if that setting is present. Otherwise, it defaults to the value of the `user_search.base_dn` setting. `user_search.pool.health_check.interval`:: +(<>) The interval to perform background checks of connections in the pool. Defaults to `60s`. `group_search.base_dn`:: +(<>) The context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain. `group_search.scope`:: +(<>) Specifies whether the group search should be `sub_tree`, `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. @@ -686,15 +801,18 @@ Specifies whether the group search should be `sub_tree`, `one_level` or the only group considered. Defaults to `sub_tree`. `metadata`:: +(<>) A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user's metadata field. `timeout.tcp_connect`:: +(<>) The TCP connect timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `timeout.tcp_read`:: +(<>) deprecated[7.7] The TCP read timeout period after establishing an LDAP connection. This is equivalent to and is deprecated in favor of `timeout.response` and they cannot be used simultaneously. An `s` at the end @@ -702,106 +820,133 @@ indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.response`:: +(<>) The time interval to wait for the response from the AD server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to the value of `timeout.ldap_search`. `timeout.ldap_search`:: +(<>) The timeout period for an LDAP search. The value is specified in the request and is enforced by the receiving LDAP Server. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to `5s` (5 seconds ). `ssl.certificate`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate] + This certificate is presented to clients when they connect. `ssl.certificate_authorities`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities] + You cannot use this setting and `ssl.truststore.path` at the same time. `ssl.key`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem] + If the Active Directory server requires client authentication, it uses this file. You cannot use this setting and `ssl.keystore.path` at the same time. `ssl.key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase] -`ssl.secure_key_passphrase` (<>):: +`ssl.secure_key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase] `ssl.keystore.key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] -`ssl.keystore.secure_key_password` (<>):: +`ssl.keystore.secure_key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] `ssl.keystore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] -`ssl.secure_keystore.password` (<>):: +`ssl.secure_keystore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] //TBD: Why/how is this different than `ssl.keystore.secure_password`? `ssl.keystore.path`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] + You cannot use this setting and `ssl.key` at the same time. `ssl.keystore.type`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12] `ssl.truststore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] -`ssl.truststore.secure_password` (<>):: +`ssl.truststore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] `ssl.truststore.path`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] + You cannot use this setting and `ssl.certificate_authorities` at the same time. `ssl.truststore.type`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11] `ssl.verification_mode`:: +(<>) Indicates the type of verification when using `ldaps` to protect against man in the middle attacks and certificate forgery. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values] `ssl.supported_protocols`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols] -`ssl.cipher_suites`:: Specifies the cipher suites that should be supported when +`ssl.cipher_suites`:: +(<>) +Specifies the cipher suites that should be supported when communicating with the Active Directory server. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values] `cache.ttl`:: +(<>) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this configured period of time. Use the standard Elasticsearch <>). Defaults to `20m`. `cache.max_users`:: +(<>) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `cache.hash_algo`:: -(Expert Setting) Specifies the hashing algorithm that is used for +(<>, Expert) +Specifies the hashing algorithm that is used for the in-memory cached user credentials. See <>. Defaults to `ssha256`. -`authentication.enabled`:: If set to `false`, disables authentication support in +`authentication.enabled`:: +(<>) +If set to `false`, disables authentication support in this realm, so that it only supports user lookups. (See the <> and <> features). Defaults to `true`. `follow_referrals`:: +(<>) If set to `true`, {es} follows referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (such as `search`). Defaults to `true`. @@ -815,51 +960,62 @@ The `type` setting must be set to `pki`. In addition to the the following settings: `username_pattern`:: +(<>) The regular expression pattern used to extract the username from the certificate DN. The first match group is the used as the username. Defaults to `CN=(.*?)(?:,\|$)`. `certificate_authorities`:: +(<>) List of paths to the PEM certificate files that should be used to authenticate a user's certificate as trusted. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `truststore.path`. `truststore.algorithm`:: +(<>) Algorithm for the truststore. Defaults to `SunX509`. `truststore.password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] If `truststore.path` is set, this setting is required. -`truststore.secure_password` (<>):: +`truststore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] `truststore.path`:: +(<>) The path of a truststore to use. Defaults to the trusted certificates configured for SSL. This setting cannot be used with `certificate_authorities`. `files.role_mapping`:: +(<>) Specifies the <> of the <>. Defaults to `ES_PATH_CONF/role_mapping.yml`. `authorization_realms`:: +(<>) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the PKI realm does not perform role mapping and instead loads the user from the listed realms. See <>. `cache.ttl`:: +(<>) Specifies the time-to-live for cached user entries. A user and a hash of its credentials are cached for this period of time. Use the standard {es} <>). Defaults to `20m`. `cache.max_users`:: +(<>) Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `delegation.enabled`:: +(<>) Generally, in order for the clients to be authenticated by the PKI realm they must connect directly to {es}. That is, they must not pass through proxies which terminate the TLS connection. In order to allow for a *trusted* and @@ -881,6 +1037,7 @@ the following settings. // tag::saml-idp-entity-id-tag[] `idp.entity_id` {ess-icon}:: +(<>) The Entity ID of the SAML Identity Provider. An Entity ID is a URI with a maximum length of 1024 characters. It can be a URL (https://idp.example.com/) or a URN (`urn:example.com:idp`) and can be found in the configuration or the SAML @@ -889,6 +1046,7 @@ metadata of the Identity Provider. // tag::saml-idp-metadata-path-tag[] `idp.metadata.path` {ess-icon}:: +(<>) The path _(recommended)_ or URL to a SAML 2.0 metadata file describing the capabilities and configuration of the Identity Provider. If a path is provided, then it is resolved relative to the {es} config @@ -904,12 +1062,14 @@ HTTPS resources are polled at a frequency determined by the realm's // tag::saml-idp-metadata-http-refresh-tag[] `idp.metadata.http.refresh` {ess-icon}:: +(<>) Controls the frequency with which `https` metadata is checked for changes. Defaults to `1h` (1 hour). // end::saml-idp-metadata-http-refresh-tag[] // tag::saml-idp-use-single-logout-tag[] `idp.use_single_logout` {ess-icon}:: +(<>) Indicates whether to utilise the Identity Provider's Single Logout service (if one exists in the IdP metadata file). Defaults to `true`. @@ -917,6 +1077,7 @@ Defaults to `true`. // tag::saml-sp-entity-id-tag[] `sp.entity_id` {ess-icon}:: +(<>) The Entity ID to use for this SAML Service Provider. This should be entered as a URI. We recommend that you use the base URL of your Kibana instance. For example, `https://kibana.example.com/`. @@ -924,6 +1085,7 @@ URI. We recommend that you use the base URL of your Kibana instance. For example // tag::saml-sp-acs-tag[] `sp.acs` {ess-icon}:: +(<>) The URL of the Assertion Consumer Service within {kib}. Typically this is the "api/security/saml/callback" endpoint of your Kibana server. For example, `https://kibana.example.com/api/security/saml/callback`. @@ -931,6 +1093,7 @@ The URL of the Assertion Consumer Service within {kib}. Typically this is the // tag::saml-sp-logout-tag[] `sp.logout` {ess-icon}:: +(<>) The URL of the Single Logout service within {kib}. Typically this is the "logout" endpoint of your Kibana server. For example, `https://kibana.example.com/logout`. @@ -938,32 +1101,38 @@ The URL of the Single Logout service within {kib}. Typically this is the // tag::saml-attributes-principal-tag[] `attributes.principal` {ess-icon}:: +(<>) The Name of the SAML attribute that contains the user's principal (username). // end::saml-attributes-principal-tag[] // tag::saml-attributes-groups-tag[] `attributes.groups` {ess-icon}:: +(<>) The Name of the SAML attribute that contains the user's groups. // end::saml-attributes-groups-tag[] // tag::saml-attributes-name-tag[] `attributes.name` {ess-icon}:: +(<>) The Name of the SAML attribute that contains the user's full name. // end::saml-attributes-name-tag[] // tag::saml-attributes-mail-tag[] `attributes.mail` {ess-icon}:: +(<>) The Name of the SAML attribute that contains the user's email address. // end::saml-attributes-mail-tag[] // tag::saml-attributes-dn-tag[] `attributes.dn` {ess-icon}:: +(<>) The Name of the SAML attribute that contains the user's X.50 _Distinguished Name_. // end::saml-attributes-dn-tag[] // tag::saml-attributes-patterns-principal-tag[] `attribute_patterns.principal` {ess-icon}:: +(<>) A Java regular expression that is matched against the SAML attribute specified by `attributes.pattern` before it is applied to the user's _principal_ property. The attribute value must match the pattern and the value of the first @@ -974,44 +1143,54 @@ the principal. // tag::saml-attributes-patterns-groups-tag[] `attribute_patterns.groups` {ess-icon}:: +(<>) As per `attribute_patterns.principal`, but for the _group_ property. // end::saml-attributes-patterns-groups-tag[] // tag::saml-attributes-patterns-name-tag[] `attribute_patterns.name` {ess-icon}:: +(<>) As per `attribute_patterns.principal`, but for the _name_ property. // end::saml-attributes-patterns-name-tag[] // tag::saml-attributes-patterns-mail-tag[] `attribute_patterns.mail` {ess-icon}:: +(<>) As per `attribute_patterns.principal`, but for the _mail_ property. // end::saml-attributes-patterns-mail-tag[] // tag::saml-attributes-patterns-dn-tag[] `attribute_patterns.dn` {ess-icon}:: +(<>) As per `attribute_patterns.principal`, but for the _dn_ property. // end::saml-attributes-patterns-dn-tag[] // tag::saml-nameid-format-tag[] `nameid_format` {ess-icon}:: +(<>) The NameID format that should be requested when asking the IdP to authenticate the current user. Defaults to requesting _transient_ names (`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`). // end::saml-nameid-format-tag[] // tag::saml-nameid-allow-create-tag[] -`nameid.allow_create` {ess-icon}:: The value of the `AllowCreate` attribute of the +`nameid.allow_create` {ess-icon}:: +(<>) +The value of the `AllowCreate` attribute of the `NameIdPolicy` element in an authentication request. The default value is false. // end::saml-nameid-allow-create-tag[] // tag::saml-nameid-sp-qualifier-tag[] -`nameid.sp_qualifier` {ess-icon}:: The value of the `SPNameQualifier` attribute of the +`nameid.sp_qualifier` {ess-icon}:: +(<>) +The value of the `SPNameQualifier` attribute of the `NameIdPolicy` element in an authentication request. The default is to not include the `SPNameQualifier` attribute. // end::saml-nameid-sp-qualifier-tag[] // tag::saml-force-authn-tag[] `force_authn` {ess-icon}:: +(<>) Specifies whether to set the `ForceAuthn` attribute when requesting that the IdP authenticate the current user. If set to `true`, the IdP is required to verify the user’s identity, irrespective of any existing sessions they might have. @@ -1020,11 +1199,13 @@ Defaults to `false`. // tag::saml-populate-user-metadata-tag[] `populate_user_metadata` {ess-icon}:: +(<>) Specifies whether to populate the {es} user's metadata with the values that are provided by the SAML attributes. Defaults to `true`. // end::saml-populate-user-metadata-tag[] `authorization_realms`:: +(<>) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the SAML realm does not perform role mapping and instead loads the user from the listed realms. @@ -1032,6 +1213,7 @@ See <>. // tag::saml-allowed-clock-skew-tag[] `allowed_clock_skew` {ess-icon}:: +(<>) The maximum amount of skew that can be tolerated between the IdP's clock and the {es} node's clock. Defaults to `3m` (3 minutes). @@ -1039,6 +1221,7 @@ Defaults to `3m` (3 minutes). // tag::saml-req-authn-context-tag[] `req_authn_context_class_ref` {ess-icon}:: +(<>) A comma separated list of Authentication Context Class Reference values to be included in the Requested Authentication Context when requesting the IdP to authenticate the current user. The Authentication Context of the corresponding @@ -1059,6 +1242,7 @@ Signing can be configured using the following settings: // tag::saml-signing-messages-tag[] `signing.saml_messages` {ess-icon}:: +(<>) A list of SAML message types that should be signed or `*` to sign all messages. Each element in the list should be the local name of a SAML XML Element. Supported element types are `AuthnRequest`, `LogoutRequest` and `LogoutResponse`. @@ -1068,16 +1252,19 @@ Defaults to `*`. // tag::saml-signing-key-tag[] `signing.key` {ess-icon}:: +(<>) Specifies the path to the PEM encoded private key to use for SAML message signing. `signing.key` and `signing.keystore.path` cannot be used at the same time. // end::saml-signing-key-tag[] -`signing.secure_key_passphrase` (<>) {ess-icon}:: +`signing.secure_key_passphrase` {ess-icon}:: +(<>) Specifies the passphrase to decrypt the PEM encoded private key (`signing.key`) if it is encrypted. // tag::saml-signing-certificate-tag[] `signing.certificate` {ess-icon}:: +(<>) Specifies the path to the PEM encoded certificate (or certificate chain) that corresponds to the `signing.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to allow for @@ -1086,6 +1273,7 @@ signature validation. This setting can only be used if `signing.key` is set. // tag::saml-signing-keystore-path-tag[] `signing.keystore.path` {ess-icon}:: +(<>) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `signing.key` at the same time. @@ -1093,6 +1281,7 @@ either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and // tag::saml-signing-keystore-type-tag[] `signing.keystore.type` {ess-icon}:: +(<>) The type of the keystore in `signing.keystore.path`. Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. @@ -1100,15 +1289,18 @@ or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. // tag::saml-signing-keystore-alias-tag[] `signing.keystore.alias` {ess-icon}:: +(<>) Specifies the alias of the key within the keystore that should be used for SAML message signing. If the keystore contains more than one private key, this setting must be specified. // end::saml-signing-keystore-alias-tag[] -`signing.keystore.secure_password` (<>) {ess-icon}:: +`signing.keystore.secure_password` {ess-icon}:: +(<>) The password to the keystore in `signing.keystore.path`. -`signing.keystore.secure_key_password` (<>) {ess-icon}:: +`signing.keystore.secure_key_password` {ess-icon}:: +(<>) The password for the key in the keystore (`signing.keystore.path`). Defaults to the keystore password. @@ -1124,17 +1316,20 @@ content. Encryption can be configured using the following settings: // tag::saml-encryption-key-tag[] `encryption.key` {ess-icon}:: +(<>) Specifies the path to the PEM encoded private key to use for SAML message decryption. `encryption.key` and `encryption.keystore.path` cannot be used at the same time. // end::saml-encryption-key-tag[] -`encryption.secure_key_passphrase` (<>):: +`encryption.secure_key_passphrase`:: +(<>) Specifies the passphrase to decrypt the PEM encoded private key (`encryption.key`) if it is encrypted. // tag::saml-encryption-certificate-tag[] `encryption.certificate` {ess-icon}:: +(<>) Specifies the path to the PEM encoded certificate (or certificate chain) that is associated with the `encryption.key`. This certificate must also be included in the Service Provider metadata or manually configured within the IdP to enable @@ -1143,6 +1338,7 @@ message encryption. This setting can be used only if `encryption.key` is set. // tag::saml-encryption-keystore-path-tag[] `encryption.keystore.path` {ess-icon}:: +(<>) The path to the keystore that contains a private key and certificate. It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and `encryption.key` at the same time. @@ -1150,6 +1346,7 @@ either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and // tag::saml-encryption-keystore-type-tag[] `encryption.keystore.type` {ess-icon}:: +(<>) The type of the keystore (`encryption.keystore.path`). Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. @@ -1157,15 +1354,18 @@ or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`. // tag::saml-encryption-keystore-alias-tag[] `encryption.keystore.alias` {ess-icon}:: +(<>) Specifies the alias of the key within the keystore (`encryption.keystore.path`) that should be used for SAML message decryption. If not specified, all compatible key pairs from the keystore are considered as candidate keys for decryption. // end::saml-encryption-keystore-alias-tag[] -`encryption.keystore.secure_password` (<>):: +`encryption.keystore.secure_password`:: +(<>) The password to the keystore (`encryption.keystore.path`). -`encryption.keystore.secure_key_password` (<>):: +`encryption.keystore.secure_key_password`:: +(<>) The password for the key in the keystore (`encryption.keystore.path`). Only a single password is supported. If you are using multiple decryption keys, they cannot have individual passwords. @@ -1185,91 +1385,109 @@ over https. // tag::saml-ssl-key-tag[] `ssl.key` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem] // end::saml-ssl-key-tag[] // tag::saml-ssl-key-passphrase-tag[] `ssl.key_passphrase` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase] // end::saml-ssl-key-passphrase-tag[] -`ssl.secure_key_passphrase` (<>):: +`ssl.secure_key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase] + You cannot use this setting and `ssl.key_passphrase` at the same time. // tag::saml-ssl-certificate-tag[] `ssl.certificate` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate] // end::saml-ssl-certificate-tag[] // tag::saml-ssl-certificate-authorities-tag[] `ssl.certificate_authorities` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities] // end::saml-ssl-certificate-authorities-tag[] // tag::saml-ssl-keystore-path-tag[] `ssl.keystore.path` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] // end::saml-ssl-keystore-path-tag[] // tag::saml-ssl-keystore-type[] `ssl.keystore.type` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12] // end::saml-ssl-keystore-type[] // tag::saml-ssl-keystore-password-tag[] `ssl.keystore.password` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] // end::saml-ssl-keystore-password-tag[] -`ssl.keystore.secure_password` (<>):: +`ssl.keystore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] + You cannot use this setting and `ssl.keystore.password` at the same time. `ssl.keystore.key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] + You cannot use this setting and `ssl.keystore.secure_key_password` at the same time. -`ssl.keystore.secure_key_password` (<>):: +`ssl.keystore.secure_key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] You cannot use this setting and `ssl.keystore.key_password` at the same time. // tag::saml-ssl-truststore-path-tag[] `ssl.truststore.path` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] // end::saml-ssl-truststore-path-tag[] // tag::saml-ssl-truststore-type-tag[] `ssl.truststore.type` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type] // end::saml-ssl-truststore-type-tag[] // tag::saml-ssl-truststore-password-tag[] `ssl.truststore.password` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] // end::saml-ssl-truststore-password-tag[] -`ssl.truststore.secure_password` (<>):: +`ssl.truststore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] + This setting cannot be used with `ssl.truststore.password`. // tag::saml-ssl-verification-mode-tag[] `ssl.verification_mode` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values] // end::saml-ssl-verification-mode-tag[] // tag::saml-ssl-supported-prototols-tag[] `ssl.supported_protocols` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols] // end::saml-ssl-supported-prototols-tag[] // tag::saml-ssl-cipher-suites-tag[] `ssl.cipher_suites` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values] // end::saml-ssl-cipher-suites-tag[] @@ -1283,34 +1501,45 @@ the following settings: // end::kerberos-description-tag[] // tag::kerberos-keytab-path-tag[] -`keytab.path` {ess-icon}:: Specifies the path to the Kerberos keytab file that contains the +`keytab.path` {ess-icon}:: +(<>) +Specifies the path to the Kerberos keytab file that contains the service principal used by this {es} node. This must be a location within the {es} configuration directory and the file must have read permissions. Required. // end::kerberos-keytab-path-tag[] // tag::kerberos-remove-realm-name-tag[] -`remove_realm_name` {ess-icon}:: Set to `true` to remove the realm part of principal names. +`remove_realm_name` {ess-icon}:: +(<>) +Set to `true` to remove the realm part of principal names. Principal names in Kerberos have the form `user/instance@REALM`. If this option is `true`, the realm part (`@REALM`) will not be included in the username. Defaults to `false`. // end::kerberos-remove-realm-name-tag[] -`krb.debug`:: Set to `true` to enable debug logs for the Java login module that +`krb.debug`:: +(<>) +Set to `true` to enable debug logs for the Java login module that provides support for Kerberos authentication. Defaults to `false`. // tag::kerberos-cache-ttl-tag[] -`cache.ttl` {ess-icon}:: The time-to-live for cached user entries. A user is cached for +`cache.ttl` {ess-icon}:: +(<>) +The time-to-live for cached user entries. A user is cached for this period of time. Specify the time period using the standard {es} <>. Defaults to `20m`. // end::kerberos-cache-ttl-tag[] // tag::kerberos-cache-max-users-tag[] -`cache.max_users` {ess-icon}:: The maximum number of user entries that can live in the +`cache.max_users` {ess-icon}:: +(<>) +The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000. // end::kerberos-cache-max-users-tag[] // tag::kerberos-authorization-realms-tag[] `authorization_realms` {ess-icon}:: +(<>) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the Kerberos realm does not perform role mapping and instead loads the user from the listed realms. @@ -1327,6 +1556,7 @@ can specify the following settings. // tag::oidc-op-issuer-tag[] `op.issuer` {ess-icon}:: +(<>) A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or @@ -1336,6 +1566,7 @@ Connect Provider. // tag::oidc-op-auth-endpoint-tag[] `op.authorization_endpoint` {ess-icon}:: +(<>) The URL for the Authorization Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. @@ -1343,24 +1574,28 @@ Connect Provider. // tag::oidc-token-endpoint-tag[] `op.token_endpoint` {ess-icon}:: +(<>) The URL for the Token Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. // end::oidc-token-endpoint-tag[] // tag::oidc-userinfo-endpoint-tag[] `op.userinfo_endpoint` {ess-icon}:: +(<>) The URL for the User Info Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. // end::oidc-userinfo-endpoint-tag[] // tag::oidc-endsession-endpoint-tag[] `op.endsession_endpoint` {ess-icon}:: +(<>) The URL for the End Session Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider. // end::oidc-endsession-endpoint-tag[] // tag::oidc-op-jwkset-path-tag[] `op.jwkset_path` {ess-icon}:: +(<>) The path or URL to a JSON Web Key Set with the key material that the OpenID Connect Provider uses for signing tokens and claims responses. If a path is provided, then it is resolved relative to the {es} config @@ -1377,16 +1612,19 @@ File-based resources are polled at a frequency determined by the global {es} // tag::rp-client-id-tag[] `rp.client_id` {ess-icon}:: +(<>) The OAuth 2.0 Client Identifier that was assigned to {es} during registration at the OpenID Connect Provider. // end::rp-client-id-tag[] -`rp.client_secret`(<>):: +`rp.client_secret`:: +(<>) The OAuth 2.0 Client Secret that was assigned to {es} during registration at the OpenID Connect Provider. // tag::rp-redirect-uri-tag[] `rp.redirect_uri` {ess-icon}:: +(<>) The Redirect URI within {kib}. If you want to use the authorization code flow, this is the `api/security/oidc/callback` endpoint of your {kib} server. If you want to use the implicit flow, it is the `api/security/oidc/implicit` endpoint. For example, `https://kibana.example.com/api/security/oidc/callback`. @@ -1394,6 +1632,7 @@ For example, `https://kibana.example.com/api/security/oidc/callback`. // tag::rp-response-type-tag[] `rp.response_type` {ess-icon}:: +(<>) OAuth 2.0 Response Type value that determines the authorization processing flow to be used. Can be `code` for authorization code grant flow, or one of `id_token`, `id_token token` for the implicit flow. @@ -1401,6 +1640,7 @@ or one of `id_token`, `id_token token` for the implicit flow. // tag::rp-signature-algorithm-tag[] `rp.signature_algorithm` {ess-icon}:: +(<>) The signature algorithm that will be used by {es} in order to verify the signature of the id tokens it will receive from the OpenID Connect Provider. Defaults to `RSA256`. @@ -1408,44 +1648,52 @@ Defaults to `RSA256`. // tag::rp-requested-scopes-tag[] `rp.requested_scopes` {ess-icon}:: +(<>) The scope values that will be requested by the OpenID Connect Provider as part of the Authentication Request. Optional, defaults to `openid` // end::rp-requested-scopes-tag[] // tag::rp-post-logout-redirect-url-tag[] `rp.post_logout_redirect_uri` {ess-icon}:: +(<>) The Redirect URI (usually within {kib}) that the OpenID Connect Provider should redirect the browser to after a successful Single Logout. // end::rp-post-logout-redirect-url-tag[] // tag::oidc-claims-principal-tag[] `claims.principal`:: +(<>) The name of the OpenID Connect claim that contains the user's principal (username). // end::oidc-claims-principal-tag[] // tag::oidc-claims-groups-tag[] `claims.groups` {ess-icon}:: +(<>) The name of the OpenID Connect claim that contains the user's groups. // end::oidc-claims-groups-tag[] // tag::oidc-claims-mail-tag[] `claims.name` {ess-icon}:: +(<>) The name of the OpenID Connect claim that contains the user's full name. // end::oidc-claims-mail-tag[] // tag::oidc-claims-mail-tag[] `claims.mail` {ess-icon}:: +(<>) The name of the OpenID Connect claim that contains the user's email address. // end::oidc-claims-mail-tag[] // tag::oidc-claims-dn-tag[] `claims.dn` {ess-icon}:: +(<>) The name of the OpenID Connect claim that contains the user's X.509 _Distinguished Name_. // end::oidc-claims-dn-tag[] // tag::oidc-claim-pattern-principal-tag[] `claim_patterns.principal` {ess-icon}:: +(<>) A Java regular expression that is matched against the OpenID Connect claim specified by `claims.principal` before it is applied to the user's _principal_ property. The attribute value must match the pattern and the value of the first @@ -1456,37 +1704,44 @@ the principal. // tag::oidc-claim-pattern-groups-tag[] `claim_patterns.groups` {ess-icon}:: +(<>) As per `claim_patterns.principal`, but for the _group_ property. // end::oidc-claim-pattern-groups-tag[] // tag::oidc-claim-pattern-name-tag[] `claim_patterns.name` {ess-icon}:: +(<>) As per `claim_patterns.principal`, but for the _name_ property. // end::oidc-claim-pattern-name-tag[] // tag::oidc-claim-pattern-mail-tag[] `claim_patterns.mail` {ess-icon}:: +(<>) As per `claim_patterns.principal`, but for the _mail_ property. // end::oidc-claim-pattern-mail-tag[] // tag::oidc-claim-pattern-dn-tag[] `claim_patterns.dn` {ess-icon}:: +(<>) As per `claim_patterns.principal`, but for the _dn_ property. // end::oidc-claim-pattern-dn-tag[] // tag::oidc-allowed-clock-skew-tag[] `allowed_clock_skew` {ess-icon}:: +(<>) The maximum allowed clock skew to be taken into consideration when validating id tokens with regards to their creation and expiration times. // end::oidc-allowed-clock-skew-tag[] // tag::oidc-populate-user-metadata-tag[] `populate_user_metadata` {ess-icon}:: +(<>) Specifies whether to populate the {es} user's metadata with the values that are provided by the OpenID Connect claims. Defaults to `true`. // end::oidc-populate-user-metadata-tag[] `http.proxy.host`:: +(<>) Specifies the address of the proxy server that will be used by the internal http client for all back-channel communication to the OpenID Connect Provider endpoints. This includes requests to the Token Endpoint, the Userinfo Endpoint @@ -1494,18 +1749,21 @@ and requests to fetch the JSON Web Key Set from the OP if `op.jwkset_path` is set as a URL. `http.proxy.scheme`:: +(<>) Specifies the protocol to use to connect to the proxy server that will be used by the http client for all back-channel communication to the OpenID Connect Provider endpoints. Defaults to `http`. Allowed values are `http` or `https`. `http.proxy.port`:: +(<>) Specifies the port of the proxy server that will be used by the http client for all backchannel communication to the OpenID Connect Provider endpoints. Defaults to `80`. // tag::oidc-http-connect-timeout-tag[] `http.connect_timeout` {ess-icon}:: +(<>) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout until a connection is established. A value of zero means the timeout is not used. Defaults to `5s`. @@ -1513,6 +1771,7 @@ the OpenID Connect Provider endpoints. Specifies the timeout until a connection // tag::oidc-http-read-timeout-tag[] `http.connection_read_timeout` {ess-icon}:: +(<>) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the timeout used when requesting a connection from the connection manager. Defaults to `5s` @@ -1520,6 +1779,7 @@ requesting a connection from the connection manager. Defaults to `5s` // tag::oidc-http-socket-timeout[] `http.socket_timeout` {ess-icon}:: +(<>) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT) in milliseconds, which is the timeout for waiting for data or, put differently, @@ -1529,6 +1789,7 @@ a maximum period inactivity between two consecutive data packets). Defaults to // tag::oidc-http-max-connections-tag[] `http.max_connections` {ess-icon}:: +(<>) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed across all endpoints. @@ -1536,6 +1797,7 @@ connections allowed across all endpoints. // tag::oidc-http-max-endpoint-connections-tag[] `http.max_endpoint_connections` {ess-icon}:: +(<>) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the maximum number of connections allowed per endpoint. @@ -1555,93 +1817,111 @@ NOTE: These settings are _only_ used for the back-channel communication between // tag::oidc-ssl-key-tag[] `ssl.key` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem] // end::oidc-ssl-key-tag[] // tag::oidc-ssl-key-passphrase-tag[] `ssl.key_passphrase` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase] // end::oidc-ssl-key-passphrase-tag[] -`ssl.secure_key_passphrase` (<>):: +`ssl.secure_key_passphrase`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase] + You cannot use this setting and `ssl.key_passphrase` at the same time. // tag::oidc-ssl-certificate-tag[] `ssl.certificate` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate] // end::oidc-ssl-certificate-tag[] // tag::oidc-ssl-certificate-authorities-tag[] `ssl.certificate_authorities` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities] // end::oidc-ssl-certificate-authorities-tag[] // tag::oidc-ssl-keystore-path-tag[] `ssl.keystore.path` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] // end::oidc-ssl-keystore-path-tag[] // tag::oidc-ssl-keystore-type-tag[] `ssl.keystore.type` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12] // end::oidc-ssl-keystore-type-tag[] // tag::oidc-ssl-keystore-password-tag[] `ssl.keystore.password` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] // end::oidc-ssl-keystore-password-tag[] -`ssl.keystore.secure_password` (<>):: +`ssl.keystore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] + You cannot use this setting and `ssl.keystore.password` at the same time. `ssl.keystore.key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] + You cannot use this setting and `ssl.keystore.secure_key_password` at the same time. -`ssl.keystore.secure_key_password` (<>):: +`ssl.keystore.secure_key_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] + You cannot use this setting and `ssl.keystore.key_password` at the same time. // tag::oidc-ssl-truststore-path-tag[] `ssl.truststore.path` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] // end::oidc-ssl-truststore-path-tag[] // tag::oidc-ssl-truststore-type-tag[] `ssl.truststore.type` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type] // end::oidc-ssl-truststore-type-tag[] // tag::oidc-ssl-truststore-password-tag[] `ssl.truststore.password` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] // end::oidc-ssl-truststore-password-tag[] -`ssl.truststore.secure_password` (<>):: +`ssl.truststore.secure_password`:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] + You cannot use this setting and `ssl.truststore.password` at the same time. // tag::oidc-ssl-verification-mode-tag[] `ssl.verification_mode` {ess-icon}:: +(<>) Controls the verification of certificates. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values] // end::oidc-ssl-verification-mode-tag[] // tag::oidc-ssl-supported-protocols-tag[] `ssl.supported_protocols` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols] // end::oidc-ssl-supported-protocols-tag[] // tag::oidc-ssl-cipher-suites-tag[] `ssl.cipher_suites` {ess-icon}:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values] // end::oidc-ssl-cipher-suites-tag[] @@ -1649,7 +1929,8 @@ include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-value [[load-balancing]] ===== Load balancing and failover -The `load_balance.type` setting can have the following values: +The <> `load_balance.type` setting can have the +following values: * `failover`: The URLs specified are used in the order that they are specified. The first server that can be connected to will be used for all subsequent @@ -1675,6 +1956,7 @@ through the list of URLs will continue until a successful connection is made. [[ssl-tls-settings]] ==== General TLS settings `xpack.security.ssl.diagnose.trust`:: +(<>) Controls whether to output diagnostic messages for SSL/TLS trust failures. If this is `true` (the default), a message will be printed to the Elasticsearch log whenever an SSL connection (incoming or outgoing) is rejected due to a failure @@ -1749,21 +2031,27 @@ setting, this would be `transport.profiles.$PROFILE.xpack.security.ssl.key`. You can configure the following settings for <>. `xpack.security.transport.filter.allow`:: +(<>) List of IP addresses to allow. `xpack.security.transport.filter.deny`:: +(<>) List of IP addresses to deny. `xpack.security.http.filter.allow`:: +(<>) List of IP addresses to allow just for HTTP. `xpack.security.http.filter.deny`:: +(<>) List of IP addresses to deny just for HTTP. `transport.profiles.$PROFILE.xpack.security.filter.allow`:: +(<>) List of IP addresses to allow for this profile. `transport.profiles.$PROFILE.xpack.security.filter.deny`:: +(<>) List of IP addresses to deny for this profile. include::security-hash-settings.asciidoc[] diff --git a/docs/reference/settings/ssl-settings.asciidoc b/docs/reference/settings/ssl-settings.asciidoc index 9905e47a2ee..33588c1bc1b 100644 --- a/docs/reference/settings/ssl-settings.asciidoc +++ b/docs/reference/settings/ssl-settings.asciidoc @@ -3,14 +3,17 @@ You can configure the following TLS/SSL settings. ifdef::server[] +{ssl-prefix}.ssl.enabled+:: +(<>) Used to enable or disable TLS/SSL. The default is `false`. endif::server[] +{ssl-prefix}.ssl.supported_protocols+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols] ifdef::server[] +{ssl-prefix}.ssl.client_authentication+:: +(<>) Controls the server's behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` @@ -25,11 +28,13 @@ endif::server[] ifdef::verifies[] +{ssl-prefix}.ssl.verification_mode+:: +(<>) Controls the verification of certificates. include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values] endif::verifies[] +{ssl-prefix}.ssl.cipher_suites+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values] [#{ssl-context}-tls-ssl-key-trusted-certificate-settings] @@ -50,18 +55,23 @@ endif::server[] When using PEM encoded files, use the following settings: +{ssl-prefix}.ssl.key+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem] +{ssl-prefix}.ssl.key_passphrase+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase] +{ssl-prefix}.ssl.secure_key_passphrase+ (<>):: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase] +{ssl-prefix}.ssl.certificate+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate] +{ssl-prefix}.ssl.certificate_authorities+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities] ===== Java keystore files @@ -70,27 +80,35 @@ When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings: +{ssl-prefix}.ssl.keystore.path+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] +{ssl-prefix}.ssl.keystore.password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] -+{ssl-prefix}.ssl.keystore.secure_password+ (<>):: ++{ssl-prefix}.ssl.keystore.secure_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] +{ssl-prefix}.ssl.keystore.key_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] -+{ssl-prefix}.ssl.keystore.secure_key_password+ (<>):: ++{ssl-prefix}.ssl.keystore.secure_key_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] +{ssl-prefix}.ssl.truststore.path+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] +{ssl-prefix}.ssl.truststore.password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] -+{ssl-prefix}.ssl.truststore.secure_password+ (<>):: ++{ssl-prefix}.ssl.truststore.secure_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] [#{ssl-context}-pkcs12-files] @@ -102,34 +120,44 @@ that contain the private key, certificate and certificates that should be truste PKCS#12 files are configured in the same way as Java keystore files: +{ssl-prefix}.ssl.keystore.path+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path] +{ssl-prefix}.ssl.keystore.type+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12] +{ssl-prefix}.ssl.keystore.password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password] -+{ssl-prefix}.ssl.keystore.secure_password+ (<>):: ++{ssl-prefix}.ssl.keystore.secure_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password] +{ssl-prefix}.ssl.keystore.key_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password] -+{ssl-prefix}.ssl.keystore.secure_key_password+ (<>):: ++{ssl-prefix}.ssl.keystore.secure_key_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password] +{ssl-prefix}.ssl.truststore.path+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path] +{ssl-prefix}.ssl.truststore.type+:: +(<>) Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file. //TBD:Should this use the ssl-truststore-type-pkcs11 or ssl-truststore-type definition and default values? +{ssl-prefix}.ssl.truststore.password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password] -+{ssl-prefix}.ssl.truststore.secure_password+ (<>):: ++{ssl-prefix}.ssl.truststore.secure_password+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password] [#{ssl-context}-pkcs11-tokens] @@ -142,10 +170,12 @@ PKCS#11 token require additional configuration on the JVM level and can be enabl via the following settings: +{ssl-prefix}.keystore.type+:: +(<>) Set this to `PKCS11` to indicate that the PKCS#11 token should be used as a keystore. //TBD: Is the default value `jks`? +{ssl-prefix}.truststore.type+:: +(<>) include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11] [NOTE]