Is there up-to-date documentation for implementing a custom Elasticsearch realm?


I am trying to implement a custom authentication realm for Elasticsearch, as documented at I think I understand the basics, but I suspect there's some version differences between what I see in the documentation and what I'm able to get building.

Specifically, I followed the link to the sample custom realm and tried to implement an extension of the class. According to the sample code, I should be implementing a method with this signature:

public void authenticate(AuthenticationToken authToken, ActionListener<AuthenticationResult> listener)

But when I try to compile my code against the appropriate Elasticsearch jar files, it appears that it is instead expecting this signature:

public User authenticate(AuthenticationToken token)

There are other methods with similar signature mismatches as well. My assumption is that my build is using an old version of the class but I have been unable to confirm or correct the issue. I am building with Gradle, and the only way I seem to express my dependency on these classes is this:

compileOnly group:'org.elasticsearch.plugin', name:'x-pack-api', version: '5.6.1'

So clearly this is an old version of X-pack that doesn't seem to line up with current versions of Elasticsearch. But I can't seem to find newer release of the x-pack-api jar, nor can I find the classes it defines (including in any other Elasticsearch-provided jar file.

What am I missing here? Is there documentation somewhere that describes what ES jar files I should depend on to create a custom realm? Or is the sample code in the above link out of date?

Thanks in advance for any help you can provide...

I have found one clear disconnect between the official documentation and the sample implementation. The documentation here says that the realm to be implemented should extend the class, but the sample code it links to actually extends the class. The core part of the package name was added. I presume that the is the newer and correct version of what we should be using under Elasticsearch 7.8?

Assuming that is true, I would appreciate any information on where I can get a jar file with this class and other related classes that are part of the X-pack core module. Is that published to a public repository somewhere?

To build custom realms for current version of Elasticsearch, you need the following two dependencies:


The 2nd one is where you will find the Realm class.


Thank you for the response. Just so I understand - can you clarify where these jar files are published to? It doesn't appear that the org.elasticsearch.plugin:x-pack-core dependency is published to Maven central - Is that correct?

And is there any documentation that shows the current way to implement a custom realm? Or is the sample code the only current point of reference we can use?


The artefacts are published to elastic's maven repoistory and you can reference it in Gradle like the follows:

repositories {
    maven(url = "")

Unfortunately, the documentation is indeed falling behind. I have openned an issue to address it. For the time being, the sample code is the best and most accurate reference. Thanks!