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