102 lines
4.7 KiB
Plaintext
102 lines
4.7 KiB
Plaintext
[role="xpack"]
|
|
[[custom-roles-provider]]
|
|
=== Custom roles provider extension
|
|
|
|
If you need to retrieve user roles from a system not supported out-of-the-box
|
|
by the {es} {security-features}, you can create a custom roles provider to
|
|
retrieve and resolve
|
|
roles. You implement a custom roles provider as an SPI loaded security extension
|
|
as part of an ordinary elasticsearch plugin.
|
|
|
|
[[implementing-custom-roles-provider]]
|
|
==== Implementing a custom roles provider
|
|
|
|
To create a custom roles provider:
|
|
|
|
. Implement the interface `BiConsumer<Set<String>, ActionListener<Set<RoleDescriptor>>>`.
|
|
That is to say, the implementation consists of one method that takes a set of strings,
|
|
which are the role names to resolve, and an ActionListener, on which the set of resolved
|
|
role descriptors are passed on as the response.
|
|
. The custom roles provider implementation must take special care to not block on any I/O
|
|
operations. It is the responsibility of the implementation to ensure asynchronous behavior
|
|
and non-blocking calls, which is made easier by the fact that the `ActionListener` is
|
|
provided on which to send the response when the roles have been resolved and the response
|
|
is ready.
|
|
|
|
To package your custom roles provider as a plugin:
|
|
|
|
. Implement an extension class for your roles provider that implements
|
|
`org.elasticsearch.xpack.core.security.SecurityExtension`. There you need to
|
|
override one or more of the following methods:
|
|
+
|
|
[source,java]
|
|
----------------------------------------------------
|
|
@Override
|
|
public List<BiConsumer<Set<String>, ActionListener<Set<RoleDescriptor>>>>
|
|
getRolesProviders(Settings settings, ResourceWatcherService resourceWatcherService) {
|
|
...
|
|
}
|
|
----------------------------------------------------
|
|
+
|
|
The `getRolesProviders` method is used to provide a list of custom roles providers that
|
|
will be used to resolve role names, if the role names could not be resolved by the reserved
|
|
roles or native roles stores. The list should be returned in the order that the custom role
|
|
providers should be invoked to resolve roles. For example, if `getRolesProviders` returns two
|
|
instances of roles providers, and both of them are able to resolve role `A`, then the resolved
|
|
role descriptor that will be used for role `A` will be the one resolved by the first roles
|
|
provider in the list.
|
|
+
|
|
[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-roles-provider]]
|
|
==== Using a custom roles provider to resolve roles
|
|
|
|
To use a custom roles provider:
|
|
|
|
. Install the roles provider 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-roles-provider-1.0.zip
|
|
----------------------------------------
|
|
|
|
. Add any configuration parameters for any of the custom roles provider implementations
|
|
to `elasticsearch.yml`. The settings are not namespaced and you have access to any
|
|
settings when constructing the custom roles providers, although it is recommended to
|
|
have a namespacing convention for custom roles providers to keep your `elasticsearch.yml`
|
|
configuration easy to understand.
|
|
+
|
|
For example, if you have a custom roles provider that
|
|
resolves roles from reading a blob in an S3 bucket on AWS, then you would specify settings
|
|
in `elasticsearch.yml` such as:
|
|
+
|
|
[source,js]
|
|
----------------------------------------
|
|
custom_roles_provider.s3_roles_provider.bucket: roles
|
|
custom_roles_provider.s3_roles_provider.region: us-east-1
|
|
custom_roles_provider.s3_roles_provider.secret_key: xxx
|
|
custom_roles_provider.s3_roles_provider.access_key: xxx
|
|
----------------------------------------
|
|
+
|
|
These settings will be available as the first parameter in the `getRolesProviders` method, from
|
|
where you will create and return the custom roles provider instances.
|
|
|
|
. Restart Elasticsearch.
|