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