Example of Custom Realm Extension for X-Pack

Introduction

This project contains an example custom realm extension for X-Pack.
This is the follow-on to the custom realm plugin for Shield; examples of that can still be found in the other branches.

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

Branch	Elasticsearch Version
master	5.3.x
5.3	5.3.x
5.2	5.2.x
5.1	5.1.x
5.0	5.0.x
2.4	2.4.x
2.3	2.3.x
2.2	2.2.x
2.1	2.1.x
2.0	2.0.x

Creating an X-Pack Extension

An X-Pack extension is packaged as a zip file consisting of jar files and a descriptor file named x-pack-extension-descriptor.properties. The extension is written in Java. This example uses Gradle to build the extension that implements a custom realm. IMPORTANT: Gradle 2.13 must be used as there are some features of the build that are no longer compatible with newer versions.

In most cases, taking this project and modifying the structure will allow you to start developing your own custom realm for X-Pack quickly.

Building and Testing the Plugin

Checkout the branch that matches the latest version of X-Pack and run gradle clean check. This will compile the extension, run unit tests, package the extension, download Elasticsearch and X-Pack, install the extension, and run tests against an instance of Elasticsearch. The resulting artifacts will be located in the build/distribution directory.

Example Configuration

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

xpack.security:
  authc:
    realms:
      custom:
        type: custom
        order: 0
        users:
          john:
            password: changeme
            roles: user,marvel_user
          jane:
            password: changeme
            roles: admin
      file:
        type: file
        order: 1

In this example, a custom realm is configured alongside a file realm. The users for the custom realm are specified in the configuration along with their roles and passwords. Please note that the definition of users and roles in the configuration file is not secure and is only used to provide an easy to understand example of a custom realm.

Custom realms can be dynamic in that users and user to role mappings do not need to be static; the custom realm needs to be able to:

Extract a token from the ThreadContext
Authenticate a user based on the credentials in the token
Provide the names of the roles that the user is assigned to

Integration Points with X-Pack

This project shows an example of and documents the two integrations points with X-Pack. 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 code comments documenting their functionality.

Questions

If you have questions about custom realms, please join us in our discussion forums where we will be able to help you.