Kerberos authentication

Deploy Kerberos.

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

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:

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

Enable TLS for HTTP.

If your Elasticsearch cluster is operating in production mode, you must configure the HTTP interface to use SSL/TLS before you can enable Kerberos authentication. For more information, see Encrypt HTTP client communications for Elasticsearch.

This step is necessary to support Kerberos authentication via Kibana. It is not required for Kerberos authentication directly against the Elasticsearch Rest API.

Enable the token service

The Elasticsearch Kerberos implementation makes use of the Elasticsearch token service. If you configure TLS on the HTTP interface, this service is automatically enabled. It can be explicitly configured by adding the following setting in your elasticsearch.yml file:

xpack.security.authc.token.enabled: true

This step is necessary to support Kerberos authentication via Kibana. It is not required for Kerberos authentication directly against the Elasticsearch Rest API.

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 Set JVM options. If this system property is not specified, Java tries to locate the file based on the conventions.

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.

Create a Kerberos realm.

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

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 configuration under the xpack.security.authc.realms.kerberos namespace.

The most common configuration for a Kerberos realm is as follows:

xpack.security.authc.realms.kerberos.kerb1:
  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.

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 create or update role mappings 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:

resp = client.security.put_role_mapping(
    name="kerbrolemapping",
    roles=[
        "monitoring_user"
    ],
    enabled=True,
    rules={
        "field": {
            "username": "user@REALM"
        }
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "kerbrolemapping",
  roles: ["monitoring_user"],
  enabled: true,
  rules: {
    field: {
      username: "user@REALM",
    },
  },
});
console.log(response);

POST /_security/role_mapping/kerbrolemapping
{
  "roles" : [ "monitoring_user" ],
  "enabled": true,
  "rules" : {
    "field" : { "username" : "user@REALM" }
  }
}

In case you want to support Kerberos cross realm authentication you may need to map roles based on the Kerberos realm name. For such scenarios following are the additional user metadata available for role mapping: - kerberos_realm will be set to Kerberos realm name. - kerberos_user_principal_name will be set to user principal name from the Kerberos ticket.

For more information, see Mapping users and groups to roles.