Docs
You are looking at preliminary documentation for a future release.
Elastic Stack Overview [6.3] » Securing the Elastic Stack » User authentication » Integrating with other authentication systems
«  SAML authentication     Enabling anonymous access  »

Integrating with other authentication systemsedit

If you are using an authentication system that is not supported out-of-the-box by X-Pack security, you can create a custom realm to interact with it to authenticate users. You implement a custom realm as an SPI loaded security extension as part of an ordinary elasticsearch plugin.

Implementing a custom realmedit

Sample code that illustrates the structure and implementation of a custom realm is provided in the 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.xpack.security.authc.Realm to communicate with your authentication system to authenticate users.
  2. Implement the org.elasticsearch.xpack.security.authc.Realm.Factory interface in a class that will be used to create the custom realm.
  3. Extend org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler to handle authentication failures when using your custom realm.

To package your custom realm as a plugin:

  1. Implement an extension class for your realm that extends org.elasticsearch.xpack.core.security.SecurityExtension. There you need to override one or more of the following methods: 

    @Override
public Map<String, Factory> getRealms() {
    ...
}

    The getRealms method is used to provide a map of type names to the Factory that will be used to create the realm.

    @Override
public AuthenticationFailureHandler getAuthenticationFailureHandler() {
    ...
}

    The getAuthenticationFailureHandler method is used to optionally provide a custom AuthenticationFailureHandler, which will control how X-Pack responds in certain authentication failure events.

    @Override
public List<String> getSettingsFilter() {
    ...
}

    The Plugin#getSettingsFilter method returns a list of setting names that should be filtered from the settings APIs as they may contain sensitive credentials. Note this method is not part of the SecurityExtension interface, it’s available as part of the elasticsearch plugin main class.

  2. Create a build configuration file for the plugin; Gradle is our recommendation.
  3. Create a META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension descriptor file for the extension that contains the fully qualified class name of your org.elasticsearch.xpack.core.security.SecurityExtension implementation
  4. Bundle all in a single zip file.

Using a custom realm to authenticate usersedit

To use a custom realm:

  1. Install the realm extension on each node in the cluster. You run bin/elasticsearch-plugin with the install sub-command and specify the URL pointing to the zip file that contains the extension. For example: 

    bin/elasticsearch-plugin install file:///<path>/my-realm-1.0.zip

  2. Add a realm configuration of the appropriate realm type to elasticsearch.yml under the xpack.security.authc.realms namespace. The options you can set depend on the settings exposed by the custom realm. At a minimum, you must set the realm type to the type defined by the extension. 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. You should make sure each configured realm has a distinct order setting. In the event that two or more realms have the same order, they will be processed in realm name order.

    Important

    When you configure realms in elasticsearch.yml, only the realms you specify are used for authentication. If you also want to use the native or file realms, you must include them in the realm chain.

  3. Restart Elasticsearch.
«  SAML authentication     Enabling anonymous access  »