Proxy-based authentication

If you already have a single sign-on (SSO) solution in place, you might want to use it as an authentication backend.

Most solutions work as a proxy in front of Elasticsearch and the security plugin. If proxy authentication succeeds, the proxy adds the (verified) username and its (verified) roles in HTTP header fields. The names of these fields depend on the SSO solution you have in place.

The security plugin then extracts these HTTP header fields from the request and uses the values to determine the user’s permissions.

Enable proxy detection

To enable proxy detection for Elasticsearch, configure it in the xff section of config.yml:

---
_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    http:
      anonymous_auth_enabled: false
      xff:
        enabled: true
        internalProxies: '192\.168\.0\.10|192\.168\.0\.11'
        remoteIpHeader: 'x-forwarded-for'

You can configure the following settings:

To determine whether a request comes from a trusted internal proxy, the security plugin compares the remote address of the HTTP request with the list of configured internal proxies. If the remote address is not in the list, the plugin treats the request like a client request.

Enable proxy authentication

Configure the names of the HTTP header fields that carry the authenticated username and role(s) in in the proxy HTTP authenticator section:

proxy_auth_domain:
  http_enabled: true
  transport_enabled: true
  order: 0
  http_authenticator:
    type: proxy
    challenge: false
    config:
      user_header: "x-proxy-user"
      roles_header: "x-proxy-roles"
  authentication_backend:
    type: noop

Enable extended proxy authentication

The security plugin has an extended version of the proxy type that lets you pass additional user attributes for use with document-level security. Aside from type: extended-proxy and attr_header_prefix, configuration is identical:

proxy_auth_domain:
  http_enabled: true
  transport_enabled: true
  order: 0
  http_authenticator:
    type: extended-proxy
    challenge: false
    config:
      user_header: "x-proxy-user"
      roles_header: "x-proxy-roles"
      attr_header_prefix: "x-proxy-ext-"
  authentication_backend:
    type: noop

Example

The following example uses an nginx proxy in front of a three-node Elasticsearch cluster. For simplicity, we use hardcoded values for x-proxy-user and x-proxy-roles. In a real world example you would set these headers dynamically. The example also includes a commented header for use with the extended proxy.

events {
  worker_connections  1024;
}

http {

  upstream elasticsearch {
    server node1.example.com:9200;
    server node2.example.com:9200;
    server node3.example.com:9200;
    keepalive 15;
  }

  server {
    listen       8090;
    server_name  nginx.example.com;

    location / {
      proxy_pass https://elasticsearch;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header x-proxy-user test;
      proxy_set_header x-proxy-roles test;
      #proxy_set_header x-proxy-ext-namespace my-namespace;
    }
  }

}

The corresponding minimal config.yml looks like:

---
_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    http:
      xff:
        enabled: true
        internalProxies: '172.16.0.203' # the nginx proxy
    authc:
      proxy_auth_domain:
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: proxy
          #type: extended-proxy
          challenge: false
          config:
            user_header: "x-proxy-user"
            roles_header: "x-proxy-roles"
            #attr_header_prefix: "x-proxy-ext-"
        authentication_backend:
          type: noop

The important part is to enable the X-Forwarded-For (XFF) resolution and set the IP(s) of the internal proxies correctly:

enabled: true
internalProxies: '172.16.0.203' # nginx proxy

In this case, nginx.example.com runs on 172.16.0.203, so add this IP to the list of internal proxies. Be sure to set internalProxies to the minimum number of IP addresses so that the security plugin only accepts requests from trusted IPs.

Kibana proxy authentication

To use proxy authentication with Kibana, the most common configuration is to place the proxy in front of Kibana and let Kibana pass the user and role headers to the security plugin.

In this case, the remote address of the HTTP call is the IP of Kibana, because it sits directly in front of Elasticsearch. Add the IP of Kibana to the list of internal proxies:

---
_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    http:
      xff:
        enabled: true
        remoteIpHeader: "x-forwarded-for"
        internalProxies: '<kibana-ip-address>'

To pass the user and role headers that the authenticating proxy adds from Kibana to the security plugin, add them to the HTTP header whitelist in kibana.yml:

elasticsearch.requestHeadersWhitelist: ["securitytenant","Authorization","x-forwarded-for","x-proxy-user","x-proxy-roles"]

You must also enable the authentication type in kibana.yml:

opendistro_security.auth.type: "proxy"
opendistro_security.proxycache.user_header: "x-proxy-user"
opendistro_security.proxycache.roles_header: "x-proxy-roles"