h1. Custom Realm Extension for X-Pack
h2. Open X-Pack
We have "opened X-Pack":https://www.elastic.co/products/x-pack/open which gives you access to the source code for the X-Pack SecurityExtension feature, and also our test cases for that.
Those test cases are maintained on an ongoing basis, and will always match the latest state of the X-Pack code. As such, we are no longer maintaining this sample realm repository. If you wish to see an example realm, you can see a working, maintained "example in the Elasticsearch repository":https://github.com/elastic/elasticsearch/tree/master/x-pack/qa/security-example-spi-extension
The blog post "How to Develop Your Own Security Extensions and Custom Realms for Elasticsearch":https://www.elastic.co/blog/how-to-develop-your-own-security-extensions-and-custom-realms-for-elasticsearch also provides an example for implementing a custom realm in Elasticsearch 6.3 or above, with commentary to assist.
h2. Elasticsearch Versions and Branches
The "master" branch of the Elasticsearch git repository tracks the most recent deveopment, including unreleased features and changes. The security extension example from @master@ is unlikely to work on any released version of Elasticsearch.
It is important that you browse to the correct version/branch for the version of Elasticsearch that you are running.
- "6.3.0":https://github.com/elastic/elasticsearch/tree/v6.3.0/x-pack/qa/security-example-spi-extension
- "6.2.x":https://github.com/elastic/elasticsearch/tree/cc2dcf51c82b26e26ced56379d3c48a74275f4ed/qa/security-example-extension
h2. Older versions of Elasticsearch
This repository contains versions of the custom realm extension that work with Elasticsearch releases from as far back as 2.0
|. Branch |. Elasticsearch Version | | "6.2":https://github.com/elastic/shield-custom-realm-example/tree/6.2 | 6.2.x | | "6.0":https://github.com/elastic/shield-custom-realm-example/tree/6.0 | 6.0.x | | "5.6":https://github.com/elastic/shield-custom-realm-example/tree/5.6 | 5.6.x | | "5.5":https://github.com/elastic/shield-custom-realm-example/tree/5.5 | 5.5.x | | "5.4":https://github.com/elastic/shield-custom-realm-example/tree/5.4 | 5.4.x | | "5.3":https://github.com/elastic/shield-custom-realm-example/tree/5.3 | 5.3.x | | "5.2":https://github.com/elastic/shield-custom-realm-example/tree/5.2 | 5.2.x | | "5.1":https://github.com/elastic/shield-custom-realm-example/tree/5.1 | 5.1.x | | "5.0":https://github.com/elastic/shield-custom-realm-example/tree/5.0 | 5.0.x | | "2.4":https://github.com/elastic/shield-custom-realm-example/tree/2.4 | 2.4.x | | "2.3":https://github.com/elastic/shield-custom-realm-example/tree/2.3 | 2.3.x | | "2.2":https://github.com/elastic/shield-custom-realm-example/tree/2.2 | 2.2.x | | "2.1":https://github.com/elastic/shield-custom-realm-example/tree/2.1 | 2.1.x | | "2.0":https://github.com/elastic/shield-custom-realm-example/tree/2.0 | 2.0.x |
h2. Creating an X-Pack Extension
For versions prior to 6.3 please follow the instructions in the @README.textile@ file on the correct branch of this repository (see table above).
For versions 6.3.0 and later, Security Extensions have changed and can be loaded using standard Elasticsearch plugin mechanisms. Please read Elasticsearch's "plugin author instructions":https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugin-authors.html In order to registry your @SecurityExtension@ with X-Pack, it must be included in the @resources/META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension@ file of your main jar file, as per the "example project":https://github.com/elastic/elasticsearch/blob/v6.3.0/x-pack/qa/security-example-spi-extension/src/main/resources/META-INF/services/org.elasticsearch.xpack.core.security.SecurityExtension
h2. Questions
p. If you have questions about custom realms, please join us in our "discussion forums":https://discuss.elastic.co where we will be able to help you.