[DOCS] Re-adds custom realm

x-pack/docs/en/security/authentication/custom-realm.asciidoc

@@ -0,0 +1,100 @@
+[role="xpack"]
+[[custom-realms]]
+=== Integrating with other authentication systems
+
+If you are using an authentication system that is not supported out-of-the-box
+by {security}, you can create a custom realm to interact with it to authenticate
+users. You implement a custom realm as an SPI loaded security extension
+as part of an ordinary 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[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.xpack.security.authc.Realm` to communicate with your
+  authentication system to authenticate users.
+. Implement the `org.elasticsearch.xpack.security.authc.Realm.Factory` interface in
+  a class that will be used to create the custom realm.
+. Extend `org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler` to
+  handle authentication failures when using your custom realm.
+
+To package your custom realm as a plugin:
+
+. Implement an extension class for your realm that extends
+  `org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to
+  override one or more of the following methods:
++
+[source,java]
+----------------------------------------------------
+@Override
+public Map<String, Factory> getRealms() {
+    ...
+}
+----------------------------------------------------
++
+The `getRealms` method is used to provide a map of type names to the `Factory` that
+will be used to create the realm.
++
+[source,java]
+----------------------------------------------------
+@Override
+public AuthenticationFailureHandler getAuthenticationFailureHandler() {
+    ...
+}
+----------------------------------------------------
++
+The `getAuthenticationFailureHandler` method is used to optionally provide a
+custom `AuthenticationFailureHandler`, which will control how {security} responds
+in certain authentication failure events.
++
+[source,java]
+----------------------------------------------------
+@Override
+public List<String> getSettingsFilter() {
+    ...
+}
+----------------------------------------------------
++
+The `Plugin#getSettingsFilter` method returns a list of setting names that should be
+filtered from the settings APIs as they may contain sensitive credentials. Note this method is not
+part of the `SecurityExtension` interface, it's available as part of the elasticsearch plugin main class.
+
+. Create a build configuration file for the plugin; Gradle is our recommendation.
+. Create a `META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension` descriptor file for the
+  extension that contains the fully qualified class name of your `org.elasticsearch.xpack.core.security.SecurityExtension` implementation
+. Bundle all in a single zip file.
+
+[[using-custom-realm]]
+==== Using a custom realm to authenticate users
+
+To use a custom realm:
+
+. Install the realm extension on each node in the cluster. You run
+  `bin/elasticsearch-plugin` with the `install` sub-command and specify the URL
+  pointing to the zip file that contains the extension. For example:
++
+[source,shell]
+----------------------------------------
+bin/elasticsearch-plugin install file:///<path>/my-realm-1.0.zip
+----------------------------------------
+
+. Add a realm configuration of the appropriate realm type to `elasticsearch.yml`
+under the `xpack.security.authc.realms` namespace. The options you can set depend
+on the settings exposed by the custom realm. At a minimum, you must set the realm
+`type` to the type defined by the extension. 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. You should make
+sure each configured realm has a distinct `order` setting. In the event that
+two or more realms have the same `order`, they will be processed in realm `name` order.
++
+IMPORTANT: When you configure realms in `elasticsearch.yml`, only the
+realms you specify are used for authentication. If you also want to use the
+`native` or `file` realms, you must include them in the realm chain.
+
+. Restart Elasticsearch.