[[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 X-Pack 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.