[Kerberos] Add documentation for Kerberos realm

docs/reference/settings/security-settings.asciidoc

@@ -1056,6 +1056,34 @@ Specifies the supported protocols for TLS/SSL.
 Specifies the
 cipher suites that should be supported.
 
+[float]
+[[ref-kerberos-settings]]
+===== Kerberos realm settings
+
+For a Kerberos realm, the `type` must be set to `kerberos`. In addition to the
+<<ref-realm-settings,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 {es} node. It expects the keytab file to be present in `ES_PATH_CONF`
+and 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`) is removed before setting the `username` 
+field in `User`. The shortened `username` value can then used during role mapping. 
+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 {es}
+<<time-units,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.
+
 [float]
 [[load-balancing]]
 ===== Load balancing and failover

x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc

@@ -0,0 +1,182 @@
+[role="xpack"]
+[[configuring-kerberos-realm]]
+=== Configuring a Kerberos realm
+
+Kerberos is used to protect services and uses a ticket-based authentication
+protocol to authenticate users.
+You can configure {es} 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. {es} clients must first obtain a TGT then initiate the process of 
+authenticating with {es}.
+
+For a summary of Kerberos terminology, see {stack-ov}/kerberos-realm.html[Kerberos authentication].
+
+==== Before you begin
+
+. Deploy Kerberos. 
++
+--
+You must have the Kerberos infrastructure set up in your environment.
+
+NOTE: 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 
+http://web.mit.edu/kerberos/www/index.html[MIT Kerberos documentation]
+--
+
+. Configure Java GSS. 
++
+--
+
+{es} uses Java GSS framework support for Kerberos authentication.
+To support Kerberos authentication, {es} needs the following files:
+
+* `krb5.conf`, a Kerberos configuration file
+*  A `keytab` file that contains credentials for the {es} 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 
+https://docs.oracle.com/javase/10/security/kerberos-requirements1.htm[Java GSS Kerberos requirements]
+--
+
+==== Create a Kerberos realm
+
+To configure a Kerberos realm in {es}:
+
+. Enable SSL/TLS for HTTP. 
++
+--
+
+If your {es} cluster is operating in production mode, then you must
+configure the HTTP interface to use SSL/TLS before you can enable
+Kerberos authentication.
+
+For more information, see
+{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications].
+
+--
+
+. Configure the JVM to find the Kerberos configuration file. 
++
+--
+{es} 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 {ref}/jvm-options.html[configuring jvm options]. 
+If this system property is not specified, Java tries to locate the file based on 
+the conventions.
+
+TIP: It is recommended that this system property be configured for {es}.
+The method for setting this property depends on your Kerberos infrastructure. 
+Refer to your Kerberos documentation for more details.
+
+For more information, see http://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html[krb5.conf]
+
+--
+
+. Create a keytab for the service node. 
++
+--
+A keytab is a file that stores pairs of principals and encryption keys. {es} 
+uses the key from the keytab to decrypt the tickets presented by the user. You 
+must create a keytab for {es} 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 `ES_PATH_CONF`.
++
+--
+Make sure that this keytab file has read permissions. This file contains
+credentials, therefore you must take appropriate measures to protect it.
+
+IMPORTANT: On every {es} node, there must be a keytab file for the HTTP
+principal. The keytab files are unique for each node since they include the
+hostname. Usually it will be of format `HTTP/es.domain.local@ES.DOMAIN.LOCAL`.
+An {es} 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 {es}, you must add a Kerberos realm in the 
+realm chain.
+
+NOTE: You can configure only one Kerberos realm on {es} nodes.
+
+To configure a Kerberos realm, there are 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:
+
+[source, yaml]
+------------------------------------------------------------
+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` can then be used for mapping
+roles to the user. There is a realm setting `remove_realm_name` which when
+set to `true` removes the realm part (`@REALM`) and the resulting `username` can 
+then be used for role mapping.
+
+For detailed information of available realm settings,
+see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+
+--
+
+. Restart {es}
+
+. 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 
+{ref}/security-api-role-mapping.html[role-mapping API] or a file stored on each 
+node. 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`:
+
+[source,js]
+--------------------------------------------------
+POST _xpack/security/role_mapping/kerbrolemapping
+{
+  "roles" : [ "monitoring_user" ],
+  "enabled": true,
+  "rules" : {
+    "field" : { "username" : "user@REALM" }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+For more information, see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
+--
+

x-pack/docs/en/security/configuring-es.asciidoc

@@ -77,6 +77,7 @@ user API.
 ** <<configuring-native-realm,Configure a native realm>>.
 ** <<configuring-pki-realm,Configure a PKI realm>>.
 ** <<configuring-saml-realm,Configure a SAML realm>>.
+** <<configuring-kerberos-realm,Configure a Kerberos realm>>.
 
 . Set up roles and users to control access to {es}.
 For example, to grant _John Doe_ full access to all indices that match
@@ -142,5 +143,7 @@ include::authentication/configuring-ldap-realm.asciidoc[]
 include::authentication/configuring-native-realm.asciidoc[]
 include::authentication/configuring-pki-realm.asciidoc[]
 include::authentication/configuring-saml-realm.asciidoc[]
+:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc
+include::authentication/configuring-kerberos-realm.asciidoc[]
 include::{es-repo-dir}/settings/security-settings.asciidoc[]
 include::{es-repo-dir}/settings/audit-settings.asciidoc[]