pugong / shield-custom-realm-example

Example of Custom Realm Plugin for Elasticsearch Shield

Introduction

This plugin contains an example custom realm for Shield.

Please make sure to use the correct branch of this repository that corresponds to the version of elasticsearch that you are developing the plugin for.

Example Plugin Branch	Elasticsearch
master	5.0.0 and above
2.x	2.4.x
2.3	2.3.x
2.2	2.2.x
2.1	2.1.x
2.0	2.0.x

Creating Elasticsearch Plugin

A custom realm must be packaged using a standard Elasticsearch plugin. An Elasticsearch plugin can be written in java and built using maven. More information can be found in the Elasticsearch documentation.

In most cases, taking this project and modifying the structure should allow you get to quickly start developing your own custom realm for Elasticsearch Shield.

Building and Testing the Plugin

Checkout the branch that matches the latest officially released version of Shield and run mvn clean verify. This will compile the plugin, run unit tests, package the plugin, download elasticsearch and install the created plugin, and run tests against a cluster running this plugin.

Example Configuration

In the elasticsearch.yml file you will define a realm as specified in the Shield documentation. An example of this configuration would be:

shield:
  authc:
    realms:
      custom:
        type: custom
        order: 0
        users:
          john:
            password: changeme
            roles: user,marvel_user
          jane:
            password: changeme
            roles: admin
      esusers:
        type: esusers
        order: 1

In the above example, a custom realm is configured alongside an esusers realm. The users for the custom realm are specified in the configuration along with their roles.

Integration Points with Shield

This plugin shows an example and documents the two integrations points with Shield. These are the ability to define one or more custom realms and the ability to define a single custom authentication failure handler to control the challenges sent to the user as part of the authentication process. These classes have lots of code comments documenting their functionality.