Custom roles provider extension
editCustom roles provider extension
editIf you need to retrieve user roles from a system not supported out-of-the-box by X-Pack security, 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 a custom roles provider
editTo 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:@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, ifgetRolesProviders
returns two instances of roles providers, and both of them are able to resolve roleA
, then the resolved role descriptor that will be used for roleA
will be the one resolved by the first roles provider in the list.@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 theSecurityExtension
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 yourorg.elasticsearch.xpack.core.security.SecurityExtension
implementation - Bundle all in a single zip file.
Using a custom roles provider to resolve roles
editTo use a custom roles provider:
-
Install the roles provider extension on each node in the cluster. You run
bin/elasticsearch-plugin
with theinstall
sub-command and specify the URL pointing to the zip file that contains the extension. For example: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 yourelasticsearch.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: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.