Merge pull request #98 from bizybot/kerberos-stack-documentation

This commit adds documentation for Kerberos realm in
stack-docs. It briefly talks about Kerberos authentication,
terminology, its support and then points to settings and 
configuration documentation.

Author: bizybot

docs/en/stack/security/authentication/index.asciidoc

@@ -9,6 +9,7 @@ include::ldap-realm.asciidoc[]
 include::native-realm.asciidoc[]
 include::pki-realm.asciidoc[]
 include::saml-realm.asciidoc[]
+include::kerberos-realm.asciidoc[]
 
 :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/custom-realm.asciidoc
 include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]

docs/en/stack/security/authentication/kerberos-realm.asciidoc

@@ -0,0 +1,63 @@
+[role="xpack"]
+[[kerberos-realm]]
+=== Kerberos authentication
+
+You can configure {security} to support Kerberos V5 authentication,
+an industry standard protocol to authenticate users in {es}.
+
+NOTE: You cannot use the Kerberos realm to authenticate users in {kib}
+and on the transport network layer.
+
+To authenticate users with Kerberos, you need to
+{ref}/configuring-kerberos-realm.html[configure a Kerberos realm] and
+<<mapping-roles, map users to {security} roles>>.
+For more information on realm settings, see
+{ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+
+[[kerberos-terms]]
+==== Key concepts
+
+There are a few terms and concepts that you'll encounter when you're setting up 
+Kerberos realms:
+
+_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 a user name.
+
+`instance` is an optional string that qualifies the primary and is separated
+by a slash(`/`) from the primary. For a user, usually it is not used; for
+service hosts, it is the fully qualified domain name of the host.
+
+`REALM` is the Kerberos realm. Usually it is is the domain name in upper case.
+An example of a typical user principal is `[email protected]`. An example of 
+a typical service principal is `HTTP/[email protected]`.
+--
+
+_realm_::
+Realms define the administrative boundary within which the authentication server
+has authority to authenticate users and services.
+
+_keytab_::
+A file that stores pairs of principals and encryption keys.
+
+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 that contains Kerberos configuration information such as the default realm
+name, the location of Key distribution centers (KDC), realms information,
+mappings from domain names to Kerberos realms, and default configurations for
+realm session key encryption types.
+
+_ticket granting ticket (TGT)_::
+A TGT is an authentication ticket generated by the Kerberos authentication
+server. It contains an encrypted authenticator.

docs/en/stack/security/authentication/realms.asciidoc

@@ -39,6 +39,10 @@ A realm that facilitates authentication using the SAML 2.0 Web SSO protocol.
 This realm is designed to support authentication through {kib} and is not
 intended for use in the REST API.  See <<saml-realm>>.
 
+_kerberos_::
+A realm that authenticates a user using Kerberos authentication. Users are
+authenticated on the basis of Kerberos tickets. See <<kerberos-realm>>.
+
 {security} also supports custom realms. If you need to integrate with another
 authentication system, you can build a custom realm plugin. For more information,
 see <<custom-realms, Integrating with Other Authentication Systems>>.
@@ -121,4 +125,4 @@ External::  Realms that require interaction with parties/components external to
             systems. Unlike internal realms, there can be as many external realms
             as one would like - each with its own unique name and configuration.
             {security} provides the following external realm types: `ldap`,
-            `active_directory`, `saml`, and `pki`.
+            `active_directory`, `saml`, `kerberos` and `pki`.