From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.
« Using PKI to Authenticate Users [1.3.0] Added in 1.3.0. Controlling the User Cache »
Elastic Docs ›Shield Reference [2.0] ›Setting Up User Authentication

Integrating with Other Authentication Systems

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Integrating with Other Authentication Systems

edit

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 a Custom Realm

edit

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:

  1. Extend org.elasticsearch.shield.authc.Realm to communicate with your authentication system to authenticate users.
  2. Extend org.elasticsearch.shield.authc.Realm.Factory to construct your new realm type.
  3. Extend org.elasticsearch.shield.authc.DefaultAuthenticationFailureHandler to handle authentication failures when using your custom realm.

To package your custom realm as an Elasticsearch plugin:

  1. Implement a plugin class for your realm that extends org.elasticsearch.plugins.Plugin. You need to:

    1. Import your realm implementation files, org.elasticsearch.plugins.Plugin, and org.elasticsearch.shield.authc.AuthenticationModule.
    2. Implement the name and description methods.
    3. Implement the onModule method to register the custom realm with the Shield AuthenticationModule and specify your authentication failure handler.
  2. Create a Maven configuration file (pom.xml) for the plugin.
  3. 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

edit

To use a custom realm:

  1. Install the realm plugin on each node in the cluster. You run bin/plugin with the install 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
  2. 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.
  3. Restart Elasticsearch.
« Using PKI to Authenticate Users [1.3.0] Added in 1.3.0. Controlling the User Cache »