mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
100 lines
4.2 KiB
Text
100 lines
4.2 KiB
Text
[role="xpack"]
|
|
[[custom-realms]]
|
|
=== Integrating with other authentication systems
|
|
|
|
If you are using an authentication system that is not supported out-of-the-box
|
|
by the {es} {security-features}, 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-custom-realm]]
|
|
==== Implementing a custom realm
|
|
|
|
Sample code that illustrates the structure and implementation of a custom realm
|
|
is provided in https://github.com/elastic/elasticsearch/tree/{branch}/x-pack/qa/security-example-spi-extension. 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.core.security.SecurityExtension`. There you need to
|
|
override one or more of the following methods:
|
|
+
|
|
[source,java]
|
|
----------------------------------------------------
|
|
@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.
|
|
+
|
|
[source,java]
|
|
----------------------------------------------------
|
|
@Override
|
|
public AuthenticationFailureHandler getAuthenticationFailureHandler() {
|
|
...
|
|
}
|
|
----------------------------------------------------
|
|
+
|
|
The `getAuthenticationFailureHandler` method is used to optionally provide a
|
|
custom `AuthenticationFailureHandler`, which will control how the
|
|
{es} {security-features} respond in certain authentication failure events.
|
|
+
|
|
[source,java]
|
|
----------------------------------------------------
|
|
@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.
|
|
|
|
. Create a build configuration file for the plugin; Gradle is our recommendation.
|
|
. 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
|
|
. Bundle all in a single zip file.
|
|
|
|
[[using-custom-realm]]
|
|
==== Using a custom realm to authenticate users
|
|
|
|
To use a custom realm:
|
|
|
|
. 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:
|
|
+
|
|
[source,shell]
|
|
----------------------------------------
|
|
bin/elasticsearch-plugin install file:///<path>/my-realm-1.0.zip
|
|
----------------------------------------
|
|
|
|
. Add a realm configuration of the appropriate realm type to `elasticsearch.yml`
|
|
under the `xpack.security.authc.realms` namespace.
|
|
You must define your realm within the namespace that matches the type defined
|
|
by the extension.
|
|
The options you can set depend on the settings exposed by the custom realm.
|
|
At a minimum, you must explicitly set the `order` attribute to control the
|
|
order in which the realms are consulted during authentication. You must also
|
|
make sure each configured realm has a distinct `order` setting. In the event
|
|
that two or more realms have the same `order`, the node will fail to start.
|
|
+
|
|
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.
|
|
|
|
. Restart Elasticsearch.
|