Version: 6.x-23

Injecting a Search Guard user

If you are running an Elasticsearch plugin that has access to the ThreadContext, you can inject a Search Guard user directly, bypassing the authentication and authorization steps completely. Use this feature if the product you are integrating Search Guard with performs it’s own authentication and authorization.

Search Guard will implicitly trust any injected user. You do not need to add these users to any backend system like LDAP or the internal user database. You can use all features of the role mapping to map injected users to Search Guard roles.

You can use the Search Guard authentication and authorization features and injected users in parallel: When Search Guard detects an injected user, no authentication and authorization steps are performed. If there is no injected user found, the regular authentication and authorization steps apply.

You can enable this feature in elasticsearch.yml by setting:

searchguard.unsupported.inject_user.enabled: true

Inject a user by adding it as transient header in the ThreadContext:

threadContext.putTransient("injected_user", "user_string");

If you are compiling against Search Guard, instead of using injected_user you can also the the following constant:

Security risks and caveats

By enabling this feature, you make it possible to inject users in the ThreadContext. Usually, this is done by an Elasticsearch plugin running in front of Search Guard. However, it is also possible to use a TransportClient for it. Thus you have to make sure that end users are not able to connect to the Elasticsearch cluster on the transport layer. Otherwise a malicious attacker can inject any user and impersonate as any user, without having to authenticate!

If your plugin registers an HTTP transport to intercept REST calls and to inject users, be aware that you cannot use TLS on the REST layer anymore. This is because Elasticsearch only allows one HTTP transport. So the Search Guard TLS HTTP transport has to be disabled.


The user string has the following format:

username|backend roles|remoteIP:port|custom attributes|tenant
Name Description
username Name of the user. Mandatory.
roles Comma-separated list of backend roles. Optional
remoteIP:port Remote IP and port of the original request. Optional. If missing, Search Guard will perform the standard remote IP lookup.
custom attributes Custom attributes of the user. Comma-separated list of key/value pairs. The number of values has to be an even number. Optional.
tenant The selected tenant for this request. Optional.

The only mandatory field is the username. You can leave all or parts of the other fields empty.


Full example:

Username: admin,
backendroles: ["role1", "role2"],
remoteip: "127.0.0:80",
custom_attributes: {
   key1: "value1",
   key2: "value2"
tenant: "mytenant"

Partial example:

Username: admin,
backendroles: ["role1", "role2"],
remoteip: "(set by Search Guard)",
custom_attributes: {},
tenant: "mytenant"

Minimal example:

Username: admin,
backendroles: [],
remoteip: "(set by Search Guard)",
custom_attributes: {},
tenant: null

Admin access for injected users

You can assign Search Guard admin privileges to any injected user. By doing so, these users will have complete control over the cluster, bypassing any security restriction imposed by Search Guard. Each request these users make will be executed as if a TLS admin certificate was provided.

To activate that feature, configure it in elasticsearch.yml like:

searchguard.unsupported.inject_user.enabled: true

To assign elevated admin privileges to a user, list the username in the searchguard.authcz.admin_dn section in elasticsearch.yml:

  - injectedadmin

Any injected user with username injectedadmin will be assigned admin privileges.

Due to security concerns, this is only possible for injected users. You cannot assign admin privileges for regular users. Use an admin TLS certificate instead.

You can also mix admin access granted by a TLS certificate and admin access for injected users:

  - injectedadmin
  - CN=kirk,OU=client,O=client,L=Test,C=DE"

Any entry that is not a DN will be treated as usernames, whereas DNs are applied to admin certificates.

Not what you were looking for? Try the search.