WARNING: Version 5.6 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Integrating with Other Authentication Systems
editIntegrating with Other Authentication Systems
editIf 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 X-Pack extension.
Implementing a Custom Realm
editSample 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:
-
Extend
org.elasticsearch.xpack.security.authc.Realm
to communicate with your authentication system to authenticate users. -
Implement the
org.elasticsearch.xpack.security.authc.Realm.Factory
interface in a class that will be used to create the custom realm. -
Extend
org.elasticsearch.xpack.security.authc.DefaultAuthenticationFailureHandler
to handle authentication failures when using your custom realm.
To package your custom realm as a plugin:
-
Implement an extension class for your realm that extends
org.elasticsearch.xpack.extensions.XPackExtension
. 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 theFactory
that will be used to create the realm.@Override public AuthenticationFailureHandler getAuthenticationFailureHandler() { ... }
The
getAuthenticationFailureHandler
method is used to optionally provide a customAuthenticationFailureHandler
, which will control how X-Pack responds in certain authentication failure events.@Override public Collection<String> getRestHeaders() { ... }
The
getRestHeaders
method returns a collection of header names that should be copied from the request into theThreadContext
where they can be accessed by the realm.@Override public List<String> getSettingsFilter() { ... }
The
getSettingsFilter
method returns a list of setting names that should be filtered from the settings APIs as they may contain sensitive credentials. - Create a build configuration file for the plugin; Gradle is our recommendation.
-
Create a
x-pack-extension-descriptor.properties
descriptor file for the extension. - Bundle all in a single zip file.
Using a Custom Realm to Authenticate Users
editTo use a custom realm:
-
Install the realm extension on each node in the cluster. You run
bin/x-pack/extension
with theinstall
sub-command and specify the URL pointing to the zip file that contains the extension. For example:bin/x-pack/extension install file:///<path>/my-realm-1.0.zip
-
Add a realm configuration of the appropriate realm type to
elasticsearch.yml
under thexpack.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 realmtype
to the type defined by the extension. 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.When you configure realms in
elasticsearch.yml
, only the realms you specify are used for authentication. If you also want to use thenative
orfile
realms, you must include them in the realm chain. - Restart Elasticsearch.