Version: SG FLX

Proxy based authentication

The proxy based authentication enables you to use a single sign on (SSO) solution - which you might already have - instead of the Search Guard authentication backend.

Most of these solutions work as a proxy in front of Elasticsearch. Usually the request is routed to the SSO proxy first. The SSO proxy authenticates the user. If authentication succeeds, the (verified) username and its (verified) roles are set in HTTP header fields. The names of these fields are dependent on the SSO solution you have in place.

Several components of the Search Guard REST authentication feature can be composed to integrate with such a solution:

  • The trusted_origin authentication frontend together with the network.trusted_proxies configuration makes sure that the requests come from the SSO proxy.
  • Alternatively, if the proxy is capable of client certificate authentication, you can also use the clientcert authentication frontend. See Client certificate authentication for more on this.
  • The user information, i.e., user name, roles and attributes, can be extracted using the standard user_mapping functionality of Search Guard. By default, Search Guard makes the headers of the source request available to user_mapping below the attribute request.headers.


For configuring proxy based authentication, you need to know the IP addresses of the proxy which connect to Elasticsearch. Additionally, you need to know the names and the format of the additional HTTP headers the proxy injects into the REST requests.

Search Guard setup

If you identify the trusted proxies by IP address, a sg_authc.yml can look similar to this:

- type: trusted_origin
  user_mapping.user_name.from: request.headers.proxy_user
  user_mapping.roles.from_comma_separated_string: request.headers.proxy_roles
  trusted_proxies: '' 

The authentication frontend trusted_origin checks whether the IP address of the connecting host is contained in the trusted_proxies network specified in the networksettings. Authentication succeeds only if this is the case.

Important: Make sure that you configure the trusted_proxies attribute correctly. In you include untrusted IP addresses, access by unauthorized clients might be possible.

Finally, the user_mapping configuration reads user name and roles from the configured HTTP request headers.

Note: Keep in mind that the user mapping is specified using JSON paths. If the header names contain special characters, you might need to use the alternative attribute notation: $.request.headers["x-proxy-user"].

Where to go next

Not what you were looking for? Try the search.