56 lines
2.9 KiB
Plaintext
56 lines
2.9 KiB
Plaintext
|
[[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.
|