Integrating with Other Authentication Systems
editIntegrating with Other Authentication Systems
editIf 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 a Custom Realm
editSample code that illustrates the structure and implementation of a custom realm is provided in the 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
, andorg.elasticsearch.shield.authc.AuthenticationModule
. -
Implement the
name
anddescription
methods. -
Implement the
onModule
method to register the custom realm with the ShieldAuthenticationModule
and specify your authentication failure handler.
-
Import your realm implementation files,
-
Create a Maven configuration file (
pom.xml
) for the plugin. - Create a plugin-descriptor.properties file for the plugin.
For more information about Elasticsearch plugins, see Elasticsearch Plugins and Integrations.
Using a Custom Realm to Authenticate Users
editTo use a custom realm:
-
Install the realm plugin on each node in the cluster. You run
bin/plugin
with theinstall
option and specify the location of the zip file that contains the plugin. For example:bin/plugin install file:///<path>/example-realm-plugin-1.0.zip
-
Add a realm configuration of the appropriate realm type to
elasticsearch.yml
in theshield.authc.realms
namespace. The options you can set depend on the settings exposed by your custom realm. At a minimum, you must set the realmtype
to the type defined in the plugin implementation. If you are configuring multiple realms, you should also explicitly set theorder
attribute to control the order in which the realms are consulted during authentication. - Restart Elasticsearch.