[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,223 @@
+[role="xpack"]
+[[configuring-kerberos-realm]]
+=== Configuring a Kerberos realm
+
+Kerberos is used to protect services and uses ticket based authentication
+protocol to authenticate users.
+You can configure {security} to support Kerberos V5 authentication,
+an industry standard protocol to authenticate users in {es}.
+This requires clients to present Kerberos tickets for authentication.
+
+In Kerberos, user authenticates with authentication service and later
+with 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 to
+know more on obtaining TGT. {es} clients would need to first obtain
+TGT and then initiate the process of authenticating with {es}.
+
+==== Terminology
+
+Few terms before setting up Kerberos realm for {es}:
+
+_kdc_::
+Key Distribution Center. A service that issues Kerberos tickets.
+
+_principal_::
+A Kerberos _principal_  is a unique identity to which Kerberos can assign
+tickets. It can be used to identify a user or a service provided by a
+server.
+Kerberos V5 principal names are of format `primary/instance@REALM`, where
+
+`primary` is user name.
+
+`instance` is optional string that qualifies the primary and is separated
+by `/` from primary. For a user usually it is not used and in case host
+it is fully qualified domain name of the host.
+
+`REALM` is Kerberos realm. Usually domain name in upper case.
+An example of a typical user principal is `[email protected]` and for
+a typical service principal is `HTTP/[email protected]`.
+
+_realm_::
+They define administrative boundary within which authentication server
+has authority to authenticate users and services.
+
+_keytab_::
+A file that stores pairs of _principal_  and its encryption key.
+
+IMPORTANT: Anyone with read permissions to this file can use the
+credentials in the network to access other services so it is important
+to protect it with proper file permissions.
+
+_krb5.conf_::
+A file containing Kerberos configuration information like default realm
+name, location of Key distribution centers (KDC), realms information,
+mappings from domain names to Kerberos realms, default configurations for
+realm session key encryption types etc.
+
+_ticket granting ticket (TGT)_::
+TGT is an authentication ticket generated by the Kerberos authentication
+server containing encrypted authenticator.
+
+==== Requirements
+
+. Kerberos Deployment
++
+--
+You must have Kerberos infrastructure setup in your environment.
+
+NOTE: Kerberos requires a lot of external services to function properly
+like time synchronization between all machines, a working forward and
+reverse DNS mappings in your domain. Please refer to your Kerberos
+documentation for more details.
+
+Setting up and configuration of Kerberos deployment is out of scope for
+this document. This document uses MIT Kerberos V5 as reference
+implementation.
+
+For more information,
+
+See http://web.mit.edu/kerberos/www/index.html[MIT Kerberos documentation]
+--
+
+. Java GSS Requirements
++
+--
+
+{es} uses Java GSS framework support for Kerberos authentication.
+To support Kerberos authentication {es} needs following:
+
+- _krb5.conf_ Kerberos configuration file
+
+- _keytab_ keytab containing credentials for {es} service principal
+
+The configuration requirements depend on your Kerberos setup and you
+need to refer to your Kerberos documentation to configure _krb5.conf_.
+
+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
+
+Following are the steps to enable Kerberos realm:
+
+. 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 JVM with Kerberos configuration file
++
+--
+
+`krb5.conf` is the Kerberos configuration file. {es} uses Java GSS and
+JAAS Krb5LoginModule to support Kerberos authentication using Spnego
+mechanism. This configuration file provides information like default realm,
+KDC and other configurations required for Kerberos authentication.
+When JVM needs some configuration properties it tries to find those values
+by locating and loading this file. JVM system property to configure the
+file path is `java.security.krb5.conf` and to configure JVM system properties
+see {ref}/jvm-options.html[configuring jvm options]. If this system property
+is not specified then java tries to locate the file based on the conventions.
+It is recommended that this system property be configured for {es}.
+Depending on your Kerberos infrastructure you will need to configure
+appropriate settings. 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 Keytab for service node
++
+--
+
+{es} uses secret key from the configured keytab to decrypt the tickets
+presented by the user. You will need to create keytab for {es} using tools
+provided by your Kerberos implementation. For example, `ktpass.exe` on
+Windows or `kadmin` for MIT Kerberos are some tools that can be used
+for creation of keytabs. Place this keytab file in the `ES_PATH_CONF`.
+Make sure that this keytab file has read permissions. As this file contains
+credentials appropriate measures must be taken to protect it.
+
+IMPORTANT: On every {es} node, there must be a keytab file for HTTP
+principal. The keytab files are unique for each node as they include the
+hostname. Usually it will be of format `HTTP/[email protected]`
+{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 realm
++
+--
+
+Kerberos authentication is enabled by configuring a Kerberos realm
+within the authentication chain for {es}.
+
+NOTE: You can only have one Kerberos realm configured on a {es} node.
+
+To configure Kerberos realm, there are few mandatory realm settings and
+other optional settings that you need to configure in `elasticsearch.yml`
+configuration file. Add realm configuration of type `kerberos` under
+the `xpack.security.authc.realms` namespace.
+
+Most common configuration for 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
+is of 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 resultant
+`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 roles to Kerberos user
++
+--
+
+The `kerberos` realm enables you to map Kerberos users to the roles.
+This role mapping can be configured via the
+{ref}/security-api-role-mapping.html[role-mapping API] or by using a file
+stored on each node. You identify user by its `username` field.
+
+The following example maps `user@REALM` to roles `monitoring`, `user`.
+
+Configured via the role-mapping API:
+[source,js]
+--------------------------------------------------
+POST _xpack/security/role_mapping/kerbrolemapping
+{
+  "roles" : [ "monitoring_user" ],
+  "enabled": true,
+  "rules" : {
+    "field" : { "username" : "user@REALM" }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+--
+

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[]