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

[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 the {es} {security-features}, 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 the
{es} {security-features} respond 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.
You must define your realm within the namespace that matchesto the type defined
by the extension.
The options you can set depend on the settings exposed by the custom realm.
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.