Shield Docs: New topic about using custom realms.

Original commit: elastic/x-pack-elasticsearch@e07d945d97

shield/docs/public/setting-up-authentication.asciidoc

@@ -13,8 +13,11 @@ _LDAP_::    Authentication via an external Lightweight Directory Protocol. See <
 _Active Directory_::    Authentication via an external Active Directory service. See <<active-directory>>.
 _PKI_:: Authentication through the use of trusted X.509 certificates. See <<pki>>.
 
+The _esusers_, _LDAP_, and _Active Directory_ realms authenticate using the username and password authentication tokens.
 
-NOTE: _esusers_, _LDAP_, and _Active Directory_ realms authenticate using the username and password authentication tokens.
+Shield 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>>. 
 
 Realms live within a _realm chain_. It is essentially a prioritized list of configured realms (typically of various types).
 The order of the list determines the order in which the realms will be consulted. During the authentication process,
@@ -104,5 +107,7 @@ include::setting-up-authentication/configuring-active-directory-realm.asciidoc[]
 
 include::setting-up-authentication/configuring-pki-realm.asciidoc[]
 
+include::setting-up-authentication/integrating-other-auth-systems.asciidoc[]
+
 include::setting-up-authentication/controlling-user-cache.asciidoc[]
 

shield/docs/public/setting-up-authentication/integrating-other-auth-systems.asciidoc

@@ -0,0 +1,56 @@
+[[custom-realms]]
+=== Integrating with Other Authentication Systems
+
+If you are using an authentication system other than LDAP, Active Directory, or PKI, you can
+create a custom realm to interact with the system to authenticate users. You implement a custom 
+realm as an Elasticsearch plugin. 
+
+[[implementing-custom-realm]]
+==== Implementing a Custom Realm
+
+Sample code that illustrates the structure and implementation of a custom realm is provided in the 
+https://github.com/elastic/shield-custom-realm-example[shield-custom-realm-example] repository on 
+GitHub. You can use this code as a starting point for creating your own realm.
+
+To create a custom realm, you need to:
+
+. Extend `org.elasticsearch.shield.authc.Realm` to communicate with your authentication system
+to authenticate users. 
+. Extend `org.elasticsearch.shield.authc.Realm.Factory` to construct your new realm type. 
+. Extend `org.elasticsearch.shield.authc.DefaultAuthenticationFailureHandler` to handle authentication
+failures when using your custom realm.
+
+To package your custom realm as an Elasticsearch plugin:
+
+. Implement a plugin class for your realm that extends `org.elasticsearch.plugins.Plugin`. 
+You need to:
+.. Import your realm implementation files, `org.elasticsearch.plugins.Plugin`, and 
+`org.elasticsearch.shield.authc.AuthenticationModule`.
+.. Implement the `name` and `description` methods.
+.. Implement the `onModule` method to register the custom realm with the Shield `AuthenticationModule`
+and specify your authentication failure handler.
+. Create a Maven configuration file (`pom.xml`) for the plugin. 
+. Create a https://github.com/elastic/elasticsearch/blob/master/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties[plugin-descriptor.properties] file for the plugin.
+
+For more information about Elasticsearch plugins, see https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/index.html[Elasticsearch Plugins and Integrations]. 
+
+[[using-custom-realm]]
+==== Using a Custom Realm to Authenticate Users
+
+To use a custom realm:
+
+. Install the realm plugin on each node in the cluster. You run `bin/plugin` with the `--url` 
+option and specify the location of the zip file that contains the plugin. For example:
++
+[source,shell]
+----------------------------------------
+bin/plugin --url file:///<path>/example-realm-plugin-1.0.zip --install example-realm-plugin
+----------------------------------------
+
+. Add a realm configuration of the appropriate realm type to `elasticsearch.yml` in the 
+`shield.authc.realms` namespace. The options you can set depend on the settings exposed by your
+custom realm. At a minimum, you must set the realm `type` to the type defined in the plugin 
+implementation. If you are configuring multiple realms, you should also explicitly set the 
+`order` attribute to control the order in which the realms are consulted during authentication. 
+
+. Restart Elasticsearch.