IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« FIPS 140-2 Auditing security settings »

› › ›

Security settings in Elasticsearch

edit

Security settings in Elasticsearch

edit

By default, X-Pack security is disabled when you have a basic or trial license. To enable X-Pack security, use the xpack.security.enabled setting.

You configure xpack.security settings to enable anonymous access and perform message authentication, set up document and field level security, configure realms, encrypt communications with SSL, and audit security events.

All of these settings can be added to the elasticsearch.yml configuration file, with the exception of the secure settings, which you add to the Elasticsearch keystore. For more information about creating and updating the Elasticsearch keystore, see Secure settings.

General security settings

edit

xpack.security.enabled

Set to true to enable X-Pack security on the node.

If set to false, which is the default value for basic and trial licenses, X-Pack security is disabled. It also affects all Kibana instances that connect to this Elasticsearch instance; you do not need to disable X-Pack security in those kibana.yml files. For more information about disabling X-Pack security in specific Kibana instances, see Kibana security settings.

If you have gold or higher licenses, the default value is true; we 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 cluster nodes info API. You can use wildcards to include multiple settings in the list. For example, the following value hides all the settings for the ad1 realm: xpack.security.authc.realms.ad1.*. 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 Elasticsearch instance in a FIPS 140-2 enabled JVM. For more information, see FIPS 140-2. Defaults to false.

Default password security settings

edit

xpack.security.authc.accept_default_password: In elasticsearch.yml, set this to false to disable support for the default "changeme" password.

Password hashing settings

edit

xpack.security.authc.password_hashing.algorithm: Specifies the hashing algorithm that is used for secure user credential storage. See Table 54, “Password hashing algorithms”. Defaults to bcrypt.

Anonymous access settings

edit

You can configure the following anonymous access settings in elasticsearch.yml. For more information, see Enabling anonymous access.

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 resource. When set to false, an HTTP 401 response is returned and the user can provide credentials with the appropriate permissions to gain access. Defaults to true.

Document and field level security settings

edit

You can set the following document and field level security settings in elasticsearch.yml. For more information, see Setting up field and document level security.

xpack.security.dls_fls.enabled: Set to false to prevent document and field level security from being configured. Defaults to true.

Token service settings

edit

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 and http.enabled is true. This prevents sniffing the token from a connection over plain http.
xpack.security.authc.token.passphrase(Secure): [6.0.0] Deprecated in 6.0.0. A secure passphrase that must be the same on each node and greater than 8 characters in length. This passphrase is used to derive a cryptographic key with which the tokens will be encrypted and authenticated. If this setting is not used, the cluster automatically generates a key, which is the recommended method.
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.

Realm settings

edit

You configure realm settings in the xpack.security.authc.realms namespace in elasticsearch.yml. For example:

xpack.security.authc.realms:

    realm1:
        type: native
        order: 0
        ...

    realm2:
        type: ldap
        order: 1
        ...

    realm3:
        type: active_directory
        order: 2
        ...
    ...

The valid settings vary depending on the realm type. For more information, see User authentication.

Settings valid for all realms

edit

type: The type of the realm: native, `ldap, active_directory, pki, or file. Required.
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.

Native realm settings

edit

For a native realm, the type must be set to native. In addition to the settings that are valid for all realms, you can specify the following optional settings:

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 Elasticsearch time units. Defaults to 20m.
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 in-memory cached user credentials. For possible values, see Table 53, “Cache hash algorithms”. Defaults to ssha256.

File realm settings

edit

The type setting must be set to file. In addition to the settings that are valid for all realms, you can specify 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 Elasticsearch time units. 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 user credentials. See Table 53, “Cache hash algorithms”. Defaults to ssha256.

LDAP realm settings

edit

The type setting must be set to ldap. In addition to the Settings valid for all realms, you can specify the following settings:

url

Specifies one or more LDAP URLs in the format ldap[s]://<server>:<port>. Multiple URLs can be defined using a comma separated value or array syntax: [ "ldaps://server1:636", "ldaps://server2:636" ]. ldaps and ldap URL protocols cannot be mixed in the same realm. Required.

load_balance.type

The behavior to use when there are multiple LDAP URLs defined. For supported values see load balancing and failover types. 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. Defaults to Empty. Due to its potential security impact, bind_dn is not exposed via the nodes info API.

bind_password

[6.3] Deprecated in 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 nodes info API.

secure_bind_password (Secure)

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, this setting is not valid. For more information on the different modes, see LDAP user authentication.

If any settings starting with user_search are specified, the user_dn_templates settings are ignored.

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 LDAP user authentication.

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. base specifies that the base_dn is the user object, and that it is 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

[5.6] Deprecated in 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, X-Pack security 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. base specifies that the base_dn is a group object, and that it is the 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 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 role-mapping file. API-based role mappings are not considered. Defaults to false.

files.role_mapping

The location for the YAML role mapping configuration file. Defaults to ES_PATH_CONF/role_mapping.yml.

follow_referrals

Specifies whether X-Pack security 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

The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).

timeout.ldap_search

The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).

ssl.key

Path to a PEM encoded file containing the private key, which is used if the LDAP server requires client authentication. ssl.key and ssl.keystore.path cannot be used at the same time.

ssl.key_passphrase

The passphrase that is used to decrypt the private key. This value is optional as the key may not be encrypted.

ssl.secure_key_passphrase (Secure)

The passphrase that is used to decrypt the private key.

ssl.certificate

Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.

ssl.certificate_authorities

List of paths to PEM encoded certificate files that should be trusted. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.keystore.path

The path to the Java Keystore file that contains a private key and certificate. ssl.key and ssl.keystore.path may not be used at the same time.

ssl.keystore.type

The format of the keystore file. Should be jks to use the Java Keystore format, PKCS12 to use PKCS#12 files, or PKCS11 to use a PKCS#11 token. The default is jks.

ssl.keystore.password

The password to the keystore.

ssl.keystore.secure_password (Secure)

The password to the keystore.

ssl.keystore.key_password

The password for the key in the keystore. Defaults to the keystore password.

ssl.keystore.secure_key_password

The password for the key in the keystore. Defaults to the keystore password.

ssl.truststore.path

The path to the Java Keystore file that contains the certificates to trust. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.truststore.password

The password to the truststore.

ssl.truststore.secure_password (Secure)

The password to the truststore.

ssl.truststore.type

The format of the keystore file. Should be jks to use the Java Keystore format, PKCS12 to use PKCS#12 files, or PKCS11 to use a PKCS#11 token. The default is jks.

ssl.verification_mode

Indicates the type of verification when using ldaps to protect against man in the middle attacks and certificate forgery. Values are none, certificate, and full. Defaults to the value of xpack.ssl.verification_mode.

See xpack.ssl.verification_mode for an explanation of these values.

ssl.supported_protocols

Supported protocols for TLS/SSL (with versions). Defaults to the value of xpack.ssl.supported_protocols.

ssl.cipher_suites

Specifies the cipher suites that should be supported when communicating with the LDAP server. Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

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 Elasticsearch time units. 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 in-memory cached user credentials. See Table 53, “Cache hash algorithms”. Defaults to ssha256.

Active Directory realm settings

edit

The type setting must be set to active_directory. In addition to the settings that are valid for all realms, you can specify the following settings:

url

An LDAP URL of the form ldap[s]://<server>:<port>. X-Pack security attempts to authenticate against this URL. If the URL is not specified, it is derived from the domain_name setting and assumes an unencrypted connection to port 389. Defaults to ldap://<domain_name>:389. This setting is required when connecting using SSL/TLS or when using a custom port.

load_balance.type

The behavior to use when there are multiple LDAP URLs defined. For supported values see load balancing and failover types. 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_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 nodes info API.

bind_password

[6.3] Deprecated in 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 nodes info API.

secure_bind_password (Secure)

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 location 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 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. For example (&(objectClass=user)(sAMAccountName={0})). For more information, see 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 must be a valid LDAP user search filter. For example, (&(objectClass=user)(userPrincipalName={1})). {1} is the full user principal name provided by the user. For more information, see 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 must be a valid LDAP user search filter. For example, (&(objectClass=user)(sAMAccountName={0})). For more information, see 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. base specifies that the base_dn is a group object, and that it is 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

The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).

timeout.ldap_search

The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).

ssl.certificate

Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.

ssl.certificate_authorities

List of paths to PEM encoded certificate files that should be trusted. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.key

Path to the PEM encoded file containing the private key, which is used when the Active Directory server requires client authentication. ssl.key and ssl.keystore.path cannot be used at the same time.

ssl.key_passphrase

The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.

ssl.secure_key_passphrase (Secure)

The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.

ssl.keystore.key_password

The password for the key in the keystore. Defaults to the keystore password.

ssl.keystore.secure_key_password (Secure)

The password for the key in the keystore. Defaults to the keystore password.

ssl.keystore.password

The password to the keystore.

ssl.secure_keystore.password (Secure)

The password to the keystore.

ssl.keystore.path

The path to the Java Keystore file that contains a private key and certificate. ssl.key and ssl.keystore.path cannot be used at the same time.

ssl.keystore.type

The format of the keystore file. Should be jks to use the Java Keystore format, PKCS12 to use PKCS#12 files, or PKCS11 to use a PKCS#11 token. The default is jks.

ssl.truststore.password

The password to the truststore.

ssl.truststore.secure_password (Secure)

The password to the truststore.

ssl.truststore.path

The path to the Java Keystore file that contains the certificates to trust. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.truststore.type

The format of the truststore file. Should be jks to use the Java Keystore format, PKCS12 to use PKCS#12 files, or PKCS11 to use a PKCS#11 token. The default is jks.

ssl.verification_mode

See xpack.ssl.verification_mode for an explanation of these values.

ssl.supported_protocols

Supported protocols for TLS/SSL (with versions). Defaults to the value of xpack.ssl.supported_protocols.

ssl.cipher_suites

Specifies the cipher suites that should be supported when communicating with the Active Directory server. Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

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 time units). 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 in-memory cached user credentials. See Table 53, “Cache hash algorithms”. Defaults to ssha256.

follow_referrals

If set to true X-Pack security 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.

PKI realm settings

edit

The type setting must be set to pki. In addition to the settings that are valid for all realms, you can specify 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: The password for the truststore. Must be provided if truststore.path is set.
truststore.secure_password (Secure): The password for the truststore.
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 location of the YAML role mapping configuration file. Defaults to ES_PATH_CONF/role_mapping.yml.
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 Elasticsearch time units). Defaults to 20m.
cache.max_users: Specifies the maximum number of user entries that the cache can contain. Defaults to 100000.

SAML realm settings

edit

The type setting must be set to saml. In addition to the settings that are valid for all realms, you can specify the following settings:

idp.entity_id

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 metadata of the Identity Provider.

idp.metadata.path

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 Elasticsearch config directory. If a URL is provided, then it must be either a file URL or a https URL. X-Pack security automatically polls this metadata resource and reloads the IdP configuration when changes are detected. File based resources are polled at a frequency determined by the global Elasticsearch resource.reload.interval.high setting, which defaults to 5 seconds. HTTPS resources are polled at a frequency determined by the realm’s idp.metadata.http.refresh setting.

idp.metadata.http.refresh

Controls the frequency with which https metadata is checked for changes. Defaults to 1h (1 hour).

idp.use_single_logout

Indicates whether to utilise the Identity Provider’s Single Logout service (if one exists in the IdP metadata file). Defaults to true.

sp.entity_id

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/.

sp.acs

The URL of the Assertion Consumer Service within Kibana. Typically this is the "api/security/v1/saml" endpoint of your Kibana server. For example, https://kibana.example.com/api/security/v1/saml.

sp.logout

The URL of the Single Logout service within Kibana. Typically this is the "logout" endpoint of your Kibana server. For example, https://kibana.example.com/logout.

attributes.principal

The Name of the SAML attribute that should be used as the X-Pack security user’s principal (username).

attributes.groups

The Name of the SAML attribute that should be used to populate X-Pack security user’s groups.

attributes.name

The Name of the SAML attribute that should be used to populate X-Pack security user’s full name.

attributes.mail

The Name of the SAML attribute that should be used to populate X-Pack security user’s email address.

attributes.dn

The Name of the SAML attribute that should be used to populate X-Pack security user’s X.500 Distinguished Name.

attribute_patterns.principal

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 capturing group is used as the principal. For example, ^([^@]+)@example\\.com$ matches email addresses from the "example.com" domain and uses the local-part as the principal.

attribute_patterns.groups

As per attribute_patterns.principal, but for the group property.

attribute_patterns.name

As per attribute_patterns.principal, but for the name property.

attribute_patterns.mail

As per attribute_patterns.principal, but for the mail property.

attribute_patterns.dn

As per attribute_patterns.principal, but for the dn property.

nameid_format

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).

nameid.allow_create

The value of the AllowCreate attribute of the NameIdPolicy element in an authentication request. Defaults to false.

nameid.sp_qualifier

The value of the SPNameQualifier attribute of the NameIdPolicy element in an authentication request. The default is to not include the SPNameQualifier attribute.

force_authn

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. Defaults to false.

populate_user_metadata

Specifies whether to populate the Elasticsearch user’s metadata with the values that are provided by the SAML attributes. Defaults to true.

allowed_clock_skew

The maximum amount of skew that can be tolerated between the IdP’s clock and the Elasticsearch node’s clock. Defaults to 3m (3 minutes).

req_authn_context_class_ref

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 authentication response should contain at least one of the requested values.

For more information, see Requesting specific authentication methods.

SAML realm signing settings

edit

If a signing key is configured (that is, either signing.key or signing.keystore.path is set), then X-Pack security signs outgoing SAML messages. Signing can be configured using the following settings:

signing.saml_messages: 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. Only valid if signing.key or signing.keystore.path is also specified. Defaults to *.
signing.key: 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.
signing.secure_key_passphrase (Secure): Specifies the passphrase to decrypt the PEM encoded private key (signing.key) if it is encrypted.
signing.certificate: 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 signature validation. This setting can only be used if signing.key is set.
signing.keystore.path: The path to the keystore that contains a private key and certificate. Must be either a Java Keystore (jks) or a PKCS#12 file. signing.key and signing.keystore.path cannot be used at the same time.
signing.keystore.type: 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.
signing.keystore.alias: 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.
signing.keystore.secure_password (Secure): The password to the keystore in signing.keystore.path.
signing.keystore.secure_key_password (Secure): The password for the key in the keystore (signing.keystore.path). Defaults to the keystore password.

SAML realm encryption settings

edit

If an encryption key is configured (that is, either encryption.key or encryption.keystore.path is set), then X-Pack security publishes an encryption certificate when generating metadata and attempts to decrypt incoming SAML content. Encryption can be configured using the following settings:

encryption.key: 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.
encryption.secure_key_passphrase (Secure): Specifies the passphrase to decrypt the PEM encoded private key (encryption.key) if it is encrypted.
encryption.certificate: 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 message encryption. This setting can be used only if encryption.key is set.
encryption.keystore.path: The path to the keystore that contains a private key and certificate. Must be either a Java Keystore (jks) or a PKCS#12 file. encryption.key and encryption.keystore.path cannot be used at the same time.
encryption.keystore.type: 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.
encryption.keystore.alias: 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.
encryption.keystore.secure_password (Secure): The password to the keystore (encryption.keystore.path).
encryption.keystore.secure_key_password (Secure): 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.

SAML realm SSL settings

edit

If you are loading the IdP metadata over SSL/TLS (that is, idp.metadata.path is a URL using the https protocol), the following settings can be used to configure SSL. If these are not specified, then the default SSL settings are used.

These settings are not used for any purpose other than loading metadata over https.

ssl.key

Specifies the path to the PEM encoded private key to use for http client authentication (if required). ssl.key and ssl.keystore.path cannot be used at the same time.

ssl.key_passphrase

Specifies the passphrase to decrypt the PEM encoded private key (ssl.key) if it is encrypted. Cannot be used with ssl.secure_key_passphrase.

ssl.secure_key_passphrase (Secure)

Specifies the passphrase to decrypt the PEM encoded private key (ssl.key) if it is encrypted. Cannot be used with ssl.key_passphrase.

ssl.certificate

Specifies the path to the PEM encoded certificate (or certificate chain) that is associated with the key (ssl.key). This setting can be used only if ssl.key is set.

ssl.certificate_authorities

Specifies the paths to the PEM encoded certificate authority certificates that should be trusted. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.keystore.path

Specifies the path to the keystore that contains a private key and certificate. Must be either a Java Keystore (jks) or a PKCS#12 file. ssl.key and ssl.keystore.path cannot be used at the same time.

ssl.keystore.type

The type of the keystore (ssl.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.

ssl.keystore.password

The password to the keystore (ssl.keystore.path). This setting cannot be used with ssl.keystore.secure_password.

ssl.keystore.secure_password (Secure)

The password to the keystore (ssl.keystore.path). This setting cannot be used with ssl.keystore.password.

ssl.keystore.key_password

The password for the key in the keystore (ssl.keystore.path). Defaults to the keystore password. This setting cannot be used with ssl.keystore.secure_key_password.

ssl.keystore.secure_key_password (Secure)

The password for the key in the keystore (ssl.keystore.path). Defaults to the keystore password. This setting cannot be used with ssl.keystore.key_password.

ssl.truststore.path

The path to the keystore that contains the certificates to trust. Must be either a Java Keystore (jks) or a PKCS#12 file. ssl.certificate_authorities and ssl.truststore.path cannot be used at the same time.

ssl.truststore.type

The type of the truststore (ssl.truststore.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.

ssl.truststore.password

The password to the truststore (ssl.truststore.path). This setting cannot be used with ssl.truststore.secure_password.

ssl.truststore.secure_password (Secure)

The password to the truststore (ssl.truststore.path). This setting cannot be used with ssl.truststore.password.

ssl.verification_mode

One of full (verify the hostname and the certificate path), certificate (verify the certificate path, but not the hostname) or none (perform no verification). Defaults to full.

See xpack.ssl.verification_mode for a more detailed explanation of these values.

ssl.supported_protocols

Specifies the supported protocols for TLS/SSL.

ssl.cipher_suites

Specifies the cipher suites that should be supported.

Kerberos realm settings

edit

For a Kerberos realm, the type must be set to kerberos. In addition to the settings that are valid for all realms, you can specify the following settings:

keytab.path: Specifies the path to the Kerberos keytab file that contains the service principal used by this Elasticsearch node. This must be a location within the Elasticsearch configuration directory and the file must have read permissions. Required.
remove_realm_name: 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.
krb.debug: Set to true to enable debug logs for the Java login module that provides support for Kerberos authentication. Defaults to false.
cache.ttl: The time-to-live for cached user entries. A user is cached for this period of time. Specify the time period using the standard Elasticsearch time units. Defaults to 20m.
cache.max_users: The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000.

Load balancing and failover

edit

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 connections. If a connection to that server fails then the next server that a connection can be established to will be used for subsequent connections.
dns_failover: In this mode of operation, only a single URL may be specified. This URL must contain a DNS name. The system will be queried for all IP addresses that correspond to this DNS name. Connections to the Active Directory or LDAP server will always be tried in the order in which they were retrieved. This differs from failover in that there is no reordering of the list and if a server has failed at the beginning of the list, it will still be tried for each subsequent connection.
round_robin: Connections will continuously iterate through the list of provided URLs. If a server is unavailable, iterating through the list of URLs will continue until a successful connection is made.
dns_round_robin: In this mode of operation, only a single URL may be specified. This URL must contain a DNS name. The system will be queried for all IP addresses that correspond to this DNS name. Connections will continuously iterate through the list of addresses. If a server is unavailable, iterating through the list of URLs will continue until a successful connection is made.

Default TLS/SSL settings

edit

You can configure the following TLS/SSL settings in elasticsearch.yml. For more information, see Encrypting communications. These settings will be used for all of X-Pack unless they have been overridden by more specific settings such as those for HTTP or Transport.

xpack.ssl.supported_protocols

Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1.

If xpack.security.fips_mode.enabled is true, you cannot use SSLv2Hello or SSLv3. See FIPS 140-2.

xpack.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 requests a client certificate but the client is not required to present one. Defaults to required. This global setting is not applicable for HTTP, see HTTP TLS/SSL Settings.

xpack.ssl.verification_mode

Controls the verification of certificates. Valid values are:

full, which verifies that the provided certificate is signed by a trusted authority (CA) and also verifies that the server’s hostname (or IP address) matches the names identified within the certificate.
certificate, which verifies that the provided certificate is signed by a trusted authority (CA), but does not perform any hostname verification.
none, which performs no verification of the server’s certificate. This mode disables many of the security benefits of SSL/TLS and should only be used after very careful consideration. It is primarily intended as a temporary diagnostic mechanism when attempting to resolve TLS errors, and its use on production clusters is strongly discouraged.

The default value is full.

xpack.ssl.cipher_suites

Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA. If the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files has been installed, the default value also includes TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA.

Default TLS/SSL key and trusted certificate settings

edit

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. If none of the settings below are specified, this will default to the X-Pack defaults. If no trusted certificates are configured, the default certificates that are trusted by the JVM will be trusted along with the certificate(s) from the key settings. The key and certificate must be in place for connections that require client authentication or when acting as a SSL enabled server.

PEM encoded files

edit

When using PEM encoded files, use the following settings:

xpack.ssl.key: Path to the PEM encoded file containing the private key.
xpack.ssl.key_passphrase: The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.ssl.secure_key_passphrase (Secure): The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.ssl.certificate: Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.
xpack.ssl.certificate_authorities: List of paths to the PEM encoded certificate files that should be trusted.

Java keystore files

edit

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.ssl.keystore.path: Path to the keystore that holds the private key and certificate.
xpack.ssl.keystore.password: Password to the keystore.
xpack.ssl.keystore.secure_password (Secure): Password to the keystore.
xpack.ssl.keystore.key_password: Password for the private key in the keystore. Defaults to the same value as xpack.ssl.keystore.password.
xpack.ssl.keystore.secure_key_password (Secure): Password for the private key in the keystore.
xpack.ssl.truststore.path: Path to the truststore file.
xpack.ssl.truststore.password: Password to the truststore.
xpack.ssl.truststore.secure_password (Secure): Password to the truststore.

If xpack.security.fips_mode.enabled is true, you cannot use Java keystore files. See FIPS 140-2.

PKCS#12 files

edit

When using PKCS#12 container files (.p12 or .pfx), which contain the private key, certificate, and certificates that should be trusted, use the following settings:

xpack.ssl.keystore.path: Path to the PKCS#12 file that holds the private key and certificate.
xpack.ssl.keystore.type: Set this to PKCS12.
xpack.ssl.keystore.password: Password to the PKCS#12 file.
xpack.ssl.keystore.secure_password (Secure): Password to the PKCS#12 file.
xpack.ssl.keystore.key_password: Password for the private key in the PKCS12 file. Defaults to the same value as xpack.ssl.keystore.password.
xpack.ssl.keystore.secure_key_password (Secure): Password for the private key in the PKCS12 file.
xpack.ssl.truststore.path: Path to the truststore file.
xpack.ssl.truststore.type: Set this to PKCS12.
xpack.ssl.truststore.password: Password to the truststore.
xpack.ssl.truststore.secure_password (Secure): Password to the truststore.

If xpack.security.fips_mode.enabled is true, you cannot use PKCS#12 keystore files. See FIPS 140-2.

Storing trusted certificates in a PKCS#12 file, although supported, is uncommon in practice. The elasticsearch-certutil tool, as well as Java’s keytool, are designed to generate PKCS#12 files that can be used both as a keystore and as a truststore, but this may not be the case for container files that are created using other tools. Usually, PKCS#12 files only contain secret and private entries. To confirm that a PKCS#12 container includes trusted certificate ("anchor") entries look for 2.16.840.1.113894.746875.1.1: <Unsupported tag 6> in the openssl pkcs12 -info output, or trustedCertEntry in the keytool -list output.

PKCS#11 tokens

edit

When using a PKCS#11 cryptographic token, which contains the private key, certificate, and certificates that should be trusted, use the following settings:

xpack.ssl.keystore.type: Set this to PKCS11.
xpack.ssl.truststore.type: Set this to PKCS11.

When configuring the PKCS#11 token that your JVM is configured to use as a keystore or a truststore for Elasticsearch, the PIN for the token can be configured by setting the appropriate value to xpack.ssl.truststore.password or xpack.ssl.truststore.secure_password. In the absence of the above, Elasticsearch will fallback to use he appropriate JVM setting (-Djavax.net.ssl.trustStorePassword) if that s set. Since there can only be one PKCS#11 token configured, only one keystore and truststore will be usable for configuration in Elasticsearch. This in turn means that only one certificate can be used for TLS both in the transport and the http layer.

HTTP TLS/SSL Settings

edit

You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.

xpack.security.http.ssl.enabled: Used to enable or disable TLS/SSL. The default is false.
xpack.security.http.ssl.supported_protocols: Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1. Defaults to the value of xpack.ssl.supported_protocols.
xpack.security.http.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 requests a client certificate but the client is not required to present one. Defaults to none.
xpack.security.http.ssl.cipher_suites: Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

HTTP TLS/SSL Key and Trusted Certificate Settings

edit

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. A private key and certificate must be configured. If none of the settings below are specified, the Default TLS/SSL Settings are used.

PEM Encoded Files

edit

When using PEM encoded files, use the following settings:

xpack.security.http.ssl.key: Path to a PEM encoded file containing the private key.
xpack.security.http.ssl.key_passphrase: The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.http.ssl.secure_key_passphrase (Secure): The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.http.ssl.certificate: Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.
xpack.security.http.ssl.certificate_authorities: List of paths to the PEM encoded certificate files that should be trusted.

Java Keystore Files

edit

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.security.http.ssl.keystore.path: Path to the keystore that holds the private key and certificate.
xpack.security.http.ssl.keystore.password: Password to the keystore.
xpack.security.http.ssl.keystore.secure_password (Secure): Password to the keystore.
xpack.security.http.ssl.keystore.key_password: Password for the private key in the keystore. Defaults to the same value as xpack.security.http.ssl.keystore.password.
xpack.security.http.ssl.keystore.secure_key_password (Secure): Password for the private key in the keystore.
xpack.security.http.ssl.truststore.path: Path to the truststore file.
xpack.security.http.ssl.truststore.password: Password to the truststore.
xpack.security.http.ssl.truststore.secure_password (Secure): Password to the truststore.

PKCS#12 Files

edit

X-Pack security can be configured to use PKCS#12 container files (.p12 or .pfx files) that contain the private key, certificate and certificates that should be trusted.

PKCS#12 files are configured in the same way as Java Keystore Files:

xpack.security.http.ssl.keystore.path: Path to the PKCS#12 file that holds the private key and certificate.
xpack.security.http.ssl.keystore.type: Set this to PKCS12 to indicate that the keystore is a PKCS#12 file.
xpack.security.http.ssl.keystore.password: Password to the PKCS#12 file.
xpack.security.http.ssl.keystore.secure_password (Secure): Password to the PKCS#12 file.
xpack.security.http.ssl.keystore.key_password: Password for the private key stored in the PKCS#12 file. Defaults to the same value as xpack.security.http.ssl.keystore.password.
xpack.security.http.ssl.keystore.secure_key_password (Secure): Password for the private key stored in the PKCS#12 file.
xpack.security.http.ssl.truststore.path: Path to the PKCS#12 file that holds the certificates to be trusted.
xpack.security.http.ssl.truststore.type: Set this to PKCS12 to indicate that the truststore is a PKCS#12 file.
xpack.security.http.ssl.truststore.password: Password to the PKCS#12 file.
xpack.security.http.ssl.truststore.secure_password (Secure): Password to the PKCS#12 file.

PKCS#11 Tokens

edit

X-Pack security can be configured to use a PKCS#11 token that contains the private key, certificate and certificates that should be trusted.

PKCS#11 token require additional configuration on the JVM level and can be enabled via the following settings:

xpack.security.http.keystore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a keystore.
xpack.security.http.truststore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a truststore.

Transport TLS/SSL Settings

edit

You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.

xpack.security.transport.ssl.enabled: Used to enable or disable TLS/SSL. The default is false.
xpack.security.transport.ssl.supported_protocols: Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1. Defaults to the value of xpack.ssl.supported_protocols.
xpack.security.transport.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 requests a client certificate but the client is not required to present one. Defaults to the value of xpack.ssl.client_authentication.
xpack.security.transport.ssl.verification_mode: Controls the verification of certificates. Valid values are none, certificate, and full. See xpack.ssl.verification_mode for a description of these values. Defaults to the value of xpack.ssl.verification_mode.
xpack.security.transport.ssl.cipher_suites: Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

Transport TLS/SSL Key and Trusted Certificate Settings

edit

PEM Encoded Files

edit

When using PEM encoded files, use the following settings:

xpack.security.transport.ssl.key: Path to a PEM encoded file containing the private key.
xpack.security.transport.ssl.key_passphrase: The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.transport.ssl.secure_key_passphrase (Secure): The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.transport.ssl.certificate: Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.
xpack.security.transport.ssl.certificate_authorities: List of paths to the PEM encoded certificate files that should be trusted.

Java Keystore Files

edit

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.security.transport.ssl.keystore.path: Path to the keystore that holds the private key and certificate.
xpack.security.transport.ssl.keystore.password: Password to the keystore.
xpack.security.transport.ssl.keystore.secure_password (Secure): Password to the keystore.
xpack.security.transport.ssl.keystore.key_password: Password for the private key in the keystore. Defaults to the same value as xpack.security.transport.ssl.keystore.password.
xpack.security.transport.ssl.keystore.secure_key_password (Secure): Password for the private key in the keystore.
xpack.security.transport.ssl.truststore.path: Path to the truststore file.
xpack.security.transport.ssl.truststore.password: Password to the truststore.
xpack.security.transport.ssl.truststore.secure_password (Secure): Password to the truststore.

PKCS#12 Files

edit

X-Pack security can be configured to use PKCS#12 container files (.p12 or .pfx files) that contain the private key, certificate and certificates that should be trusted.

PKCS#12 files are configured in the same way as Java Keystore Files:

xpack.security.transport.ssl.keystore.path: Path to the PKCS#12 file that holds the private key and certificate.
xpack.security.transport.ssl.keystore.type: Set this to PKCS12 to indicate that the keystore is a PKCS#12 file.
xpack.security.transport.ssl.keystore.password: Password to the PKCS#12 file.
xpack.security.transport.ssl.keystore.secure_password (Secure): Password to the PKCS#12 file.
xpack.security.transport.ssl.keystore.key_password: Password for the private key stored in the PKCS#12 file. Defaults to the same value as xpack.security.transport.ssl.keystore.password.
xpack.security.transport.ssl.keystore.secure_key_password (Secure): Password for the private key stored in the PKCS#12 file.
xpack.security.transport.ssl.truststore.path: Path to the PKCS#12 file that holds the certificates to be trusted.
xpack.security.transport.ssl.truststore.type: Set this to PKCS12 to indicate that the truststore is a PKCS#12 file.
xpack.security.transport.ssl.truststore.password: Password to the PKCS#12 file.
xpack.security.transport.ssl.truststore.secure_password (Secure): Password to the PKCS#12 file.

PKCS#11 Tokens

edit

X-Pack security can be configured to use a PKCS#11 token that contains the private key, certificate and certificates that should be trusted.

PKCS#11 token require additional configuration on the JVM level and can be enabled via the following settings:

xpack.security.transport.keystore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a keystore.
xpack.security.transport.truststore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a truststore.

Transport profile TLS/SSL settings

edit

The same settings that are available for the default transport are also available for each transport profile. By default, the settings for a transport profile will be the same as the default transport unless they are specified.

As an example, lets look at the key setting. For the default transport this is xpack.security.transport.ssl.key. In order to use this setting in a transport profile, use the prefix transport.profiles.$PROFILE.xpack.security. and append the portion of the setting after xpack.security.transport.. For the key setting, this would be transport.profiles.$PROFILE.xpack.security.ssl.key.

Auditing TLS/SSL Settings

edit

You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.

xpack.security.audit.index.client.xpack.ssl.supported_protocols: Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1. Defaults to the value of xpack.ssl.supported_protocols.
xpack.security.audit.index.client.xpack.ssl.verification_mode: Controls the verification of certificates. Valid values are none, certificate, and full. See xpack.ssl.verification_mode for a description of these values. Defaults to the value of xpack.ssl.verification_mode.
xpack.security.audit.index.client.xpack.ssl.cipher_suites: Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

Auditing TLS/SSL Key and Trusted Certificate Settings

edit

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. A private key and certificate are optional and would be used if the server requires client authentication for PKI authentication. If none of the settings below are specified, the Default TLS/SSL Settings are used.

PEM Encoded Files

edit

When using PEM encoded files, use the following settings:

xpack.security.audit.index.client.xpack.ssl.key: Path to a PEM encoded file containing the private key.
xpack.security.audit.index.client.xpack.ssl.key_passphrase: The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.audit.index.client.xpack.ssl.secure_key_passphrase (Secure): The passphrase that is used to decrypt the private key. This value is optional as the key might not be encrypted.
xpack.security.audit.index.client.xpack.ssl.certificate: Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.
xpack.security.audit.index.client.xpack.ssl.certificate_authorities: List of paths to the PEM encoded certificate files that should be trusted.

Java Keystore Files

edit

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.security.audit.index.client.xpack.ssl.keystore.path: Path to the keystore that holds the private key and certificate.
xpack.security.audit.index.client.xpack.ssl.keystore.password: Password to the keystore.
xpack.security.audit.index.client.xpack.ssl.keystore.secure_password (Secure): Password to the keystore.
xpack.security.audit.index.client.xpack.ssl.keystore.key_password: Password for the private key in the keystore. Defaults to the same value as xpack.security.audit.index.client.xpack.ssl.keystore.password.
xpack.security.audit.index.client.xpack.ssl.keystore.secure_key_password (Secure): Password for the private key in the keystore.
xpack.security.audit.index.client.xpack.ssl.truststore.path: Path to the truststore file.
xpack.security.audit.index.client.xpack.ssl.truststore.password: Password to the truststore.
xpack.security.audit.index.client.xpack.ssl.truststore.secure_password (Secure): Password to the truststore.

PKCS#12 Files

edit

X-Pack security can be configured to use PKCS#12 container files (.p12 or .pfx files) that contain the private key, certificate and certificates that should be trusted.

PKCS#12 files are configured in the same way as Java Keystore Files:

xpack.security.audit.index.client.xpack.ssl.keystore.path: Path to the PKCS#12 file that holds the private key and certificate.
xpack.security.audit.index.client.xpack.ssl.keystore.type: Set this to PKCS12 to indicate that the keystore is a PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.keystore.password: Password to the PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.keystore.secure_password (Secure): Password to the PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.keystore.key_password: Password for the private key stored in the PKCS#12 file. Defaults to the same value as xpack.security.audit.index.client.xpack.ssl.keystore.password.
xpack.security.audit.index.client.xpack.ssl.keystore.secure_key_password (Secure): Password for the private key stored in the PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.truststore.path: Path to the PKCS#12 file that holds the certificates to be trusted.
xpack.security.audit.index.client.xpack.ssl.truststore.type: Set this to PKCS12 to indicate that the truststore is a PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.truststore.password: Password to the PKCS#12 file.
xpack.security.audit.index.client.xpack.ssl.truststore.secure_password (Secure): Password to the PKCS#12 file.

PKCS#11 Tokens

edit

X-Pack security can be configured to use a PKCS#11 token that contains the private key, certificate and certificates that should be trusted.

PKCS#11 token require additional configuration on the JVM level and can be enabled via the following settings:

xpack.security.audit.index.client.xpack.keystore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a keystore.
xpack.security.audit.index.client.xpack.truststore.type: Set this to PKCS11 to indicate that the PKCS#11 token should be used as a truststore.

IP filtering settings

edit

You can configure the following settings for IP filtering.

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.

User cache and password hash algorithms

edit

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:

Table 53. Cache hash algorithms

Algorithm			Description
`ssha256`			Uses a salted `sha-256` algorithm (default).
`md5`			Uses `MD5` algorithm.
`sha1`			Uses `SHA1` algorithm.
`bcrypt`			Uses `bcrypt` algorithm with salt generated in 1024 rounds.
`bcrypt4`			Uses `bcrypt` algorithm with salt generated in 16 rounds.
`bcrypt5`			Uses `bcrypt` algorithm with salt generated in 32 rounds.
`bcrypt6`			Uses `bcrypt` algorithm with salt generated in 64 rounds.
`bcrypt7`			Uses `bcrypt` algorithm with salt generated in 128 rounds.
`bcrypt8`			Uses `bcrypt` algorithm with salt generated in 256 rounds.
`bcrypt9`			Uses `bcrypt` algorithm with salt generated in 512 rounds.
`pbkdf2`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 10000 iterations.
`pbkdf2_1000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 1000 iterations.
`pbkdf2_10000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 10000 iterations.
`pbkdf2_50000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 50000 iterations.
`pbkdf2_100000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 100000 iterations.
`pbkdf2_500000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 500000 iterations.
`pbkdf2_1000000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 1000000 iterations.
`noop`,`clear_text`			Doesn’t hash the credentials and keeps it in clear text in memory. CAUTION: keeping clear text is considered insecure and can be compromised at the OS level (for example through 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:

Table 54. Password hashing algorithms

Algorithm			Description
`bcrypt`			Uses `bcrypt` algorithm with salt generated in 1024 rounds. (default)
`bcrypt4`			Uses `bcrypt` algorithm with salt generated in 16 rounds.
`bcrypt5`			Uses `bcrypt` algorithm with salt generated in 32 rounds.
`bcrypt6`			Uses `bcrypt` algorithm with salt generated in 64 rounds.
`bcrypt7`			Uses `bcrypt` algorithm with salt generated in 128 rounds.
`bcrypt8`			Uses `bcrypt` algorithm with salt generated in 256 rounds.
`bcrypt9`			Uses `bcrypt` algorithm with salt generated in 512 rounds.
`bcrypt10`			Uses `bcrypt` algorithm with salt generated in 1024 rounds.
`bcrypt11`			Uses `bcrypt` algorithm with salt generated in 2048 rounds.
`bcrypt12`			Uses `bcrypt` algorithm with salt generated in 4096 rounds.
`bcrypt13`			Uses `bcrypt` algorithm with salt generated in 8192 rounds.
`bcrypt14`			Uses `bcrypt` algorithm with salt generated in 16384 rounds.
`pbkdf2`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 10000 iterations.
`pbkdf2_1000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 1000 iterations.
`pbkdf2_10000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 10000 iterations.
`pbkdf2_50000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 50000 iterations.
`pbkdf2_100000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 100000 iterations.
`pbkdf2_500000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 500000 iterations.
`pbkdf2_1000000`			Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a pseudorandom function using 1000000 iterations.

« FIPS 140-2 Auditing security settings »