[DOCS] Documentation for Custom Roles Providers

relates elastic/x-pack-elasticsearch#721

Original commit: elastic/x-pack-elasticsearch@67fdba706c

docs/en/security/authorization.asciidoc

@@ -240,7 +240,10 @@ Based on the above definition, users owning the `clicks_admin` role can:
 TIP:  For a complete list of available <<security-privileges, cluster and indices privileges>>
 
 There are two available mechanisms to define roles: using the _Role Management APIs_
-or in local files on the Elasticsearch nodes.
+or in local files on the Elasticsearch nodes.  {security} also supports implementing
+custom roles providers.  If you need to integrate with another system to retrieve
+user roles, you can build a custom roles provider plugin. For more information,
+see <<custom-roles-provider, Custom Roles Provider Extension>>.
 
 [float]
 [[roles-management-ui]]
@@ -404,3 +407,6 @@ include::authorization/mapping-roles.asciidoc[]
 include::authorization/field-and-document-access-control.asciidoc[]
 
 include::authorization/run-as-privilege.asciidoc[]
+
+include::authorization/custom-roles-provider.asciidoc[]
+

docs/en/security/authorization/custom-roles-provider.asciidoc

@@ -0,0 +1,97 @@
+[[custom-roles-provider]]
+=== Custom Roles Provider Extension
+
+If you need to retrieve user roles from a system not supported out-of-the-box
+by {security}, you can create a custom roles provider to retrieve and resolve
+roles. You implement a custom roles provider as an {xpack} extension.
+
+[[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 extends
+  `org.elasticsearch.xpack.extensions.XPackExtension`. 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 `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-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/x-pack/extension` with the `install` sub-command and specify the URL
+  pointing to the zip file that contains the extension. For example:
++
+[source,shell]
+----------------------------------------
+bin/x-pack/extension 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.