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

› › ›

Configuring a Kerberos realm

edit

Configuring a Kerberos realm

edit

Kerberos is used to protect services and uses a ticket-based authentication protocol to authenticate users. You can configure Elasticsearch to use the Kerberos V5 authentication protocol, which is an industry standard protocol, to authenticate users. In this scenario, clients must present Kerberos tickets for authentication.

In Kerberos, users authenticate with an authentication service and later with a ticket granting service to generate a TGT (ticket-granting ticket). This ticket is then presented to the service for authentication. Refer to your Kerberos installation documentation for more information about obtaining TGT. Elasticsearch clients must first obtain a TGT then initiate the process of authenticating with Elasticsearch.

For a summary of Kerberos terminology, see Kerberos authentication.

Before you begin

edit

Deploy Kerberos.

You must have the Kerberos infrastructure set up in your environment.

Kerberos requires a lot of external services to function properly, such as time synchronization between all machines and working forward and reverse DNS mappings in your domain. Refer to your Kerberos documentation for more details.

These instructions do not cover setting up and configuring your Kerberos deployment. Where examples are provided, they pertain to an MIT Kerberos V5 deployment. For more information, see MIT Kerberos documentation
Configure Java GSS.

Elasticsearch uses Java GSS framework support for Kerberos authentication. To support Kerberos authentication, Elasticsearch needs the following files:
- krb5.conf, a Kerberos configuration file
- A keytab file that contains credentials for the Elasticsearch service principal
The configuration requirements depend on your Kerberos setup. Refer to your Kerberos documentation to configure the krb5.conf file.

For more information on Java GSS, see Java GSS Kerberos requirements

Create a Kerberos realm

edit

To configure a Kerberos realm in Elasticsearch:

Configure the JVM to find the Kerberos configuration file.

Elasticsearch uses Java GSS and JAAS Krb5LoginModule to support Kerberos authentication using a Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) mechanism. The Kerberos configuration file (krb5.conf) provides information such as the default realm, the Key Distribution Center (KDC), and other configuration details required for Kerberos authentication. When the JVM needs some configuration properties, it tries to find those values by locating and loading this file. The JVM system property to configure the file path is java.security.krb5.conf. To configure JVM system properties see configuring jvm options. If this system property is not specified, Java tries to locate the file based on the conventions.

It is recommended that this system property be configured for Elasticsearch. The method for setting this property depends on your Kerberos infrastructure. Refer to your Kerberos documentation for more details.

For more information, see krb5.conf
Create a keytab for the Elasticsearch node.

A keytab is a file that stores pairs of principals and encryption keys. Elasticsearch uses the keys from the keytab to decrypt the tickets presented by the user. You must create a keytab for Elasticsearch by using the tools provided by your Kerberos implementation. For example, some tools that create keytabs are ktpass.exe on Windows and kadmin for MIT Kerberos.
Put the keytab file in the Elasticsearch configuration directory.

Make sure that this keytab file has read permissions. This file contains credentials, therefore you must take appropriate measures to protect it.

Elasticsearch uses Kerberos on the HTTP network layer, therefore there must be a keytab file for the HTTP service principal on every Elasticsearch node. The service principal name must have the format HTTP/es.domain.local@ES.DOMAIN.LOCAL. The keytab files are unique for each node since they include the hostname. An Elasticsearch node can act as any principal a client requests as long as that principal and its credentials are found in the configured keytab.
Create a Kerberos realm.

To enable Kerberos authentication in Elasticsearch, you must add a Kerberos realm in the realm chain.

You can configure only one Kerberos realm on Elasticsearch nodes.

To configure a Kerberos realm, there are a few mandatory realm settings and other optional settings that you need to configure in the elasticsearch.yml configuration file. Add a realm of type kerberos under the xpack.security.authc.realms namespace.

The most common configuration for a Kerberos realm is as follows:
```
xpack.security.authc.realms.kerb1:
  type: kerberos
  order: 3
  keytab.path: es.keytab
  remove_realm_name: false
```
The username is extracted from the ticket presented by user and usually has the format username@REALM. This username is used for mapping roles to the user. If realm setting remove_realm_name is set to true, the realm part (@REALM) is removed. The resulting username is used for role mapping.

For detailed information of available realm settings, see Kerberos realm settings.
Restart Elasticsearch
Map Kerberos users to roles.

The kerberos realm enables you to map Kerberos users to roles. You can configure these role mappings by using the role-mapping API. You identify users by their username field.

The following example uses the role mapping API to map user@REALM to the roles monitoring and user:
```
POST _xpack/security/role_mapping/kerbrolemapping
{
  "roles" : [ "monitoring_user" ],
  "enabled": true,
  "rules" : {
    "field" : { "username" : "user@REALM" }
  }
}
```
For more information, see Mapping users and groups to roles.

« Configuring a SAML realm FIPS 140-2 »