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.
Sample 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:
org.elasticsearch.shield.authc.Realmto communicate with your authentication system to authenticate users.
org.elasticsearch.shield.authc.Realm.Factoryto construct your new realm type.
org.elasticsearch.shield.authc.DefaultAuthenticationFailureHandlerto 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,
onModulemethod to register the custom realm with the Shield
AuthenticationModuleand 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.
To use a custom realm:
Install the realm plugin on each node in the cluster. You run
installoption 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
shield.authc.realmsnamespace. The options you can set depend on the settings exposed by your custom realm. At a minimum, you must set the realm
typeto the type defined in the plugin implementation. If you are configuring multiple realms, you should also explicitly set the
orderattribute to control the order in which the realms are consulted during authentication.
- Restart Elasticsearch.