Proxy-based authentication

    Most solutions work as a proxy in front of OpenSearch 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.

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

    You can configure the following settings:

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

    1. proxy_auth_domain:
    2.   http_enabled: true
    3.   transport_enabled: true
    4.   order: 0
    5.   http_authenticator:
    6.     type: proxy
    7.     challenge: false
    8.     config:
    9.       user_header: "x-proxy-user"
    10.       roles_header: "x-proxy-roles"
    11.   authentication_backend:
    12.     type: noop

    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 , configuration is identical:

    1. proxy_auth_domain:
    2.   http_enabled: true
    3.   transport_enabled: true
    4.   http_authenticator:
    5.     type: extended-proxy
    6.     challenge: false
    7.     config:
    8.       user_header: "x-proxy-user"
    9.       roles_header: "x-proxy-roles"
    10.       attr_header_prefix: "x-proxy-ext-"
    11.   authentication_backend:
    12.     type: noop

    The following example uses an nginx proxy in front of a three-node OpenSearch 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.

    The corresponding minimal config.yml looks like:

    1. ---
    2. _meta:
    3.   type: "config"
    4.   config_version: 2
    6. config:
    7.   dynamic:
    8.     http:
    10.         enabled: true
    11.         internalProxies: '172.16.0.203' # the nginx proxy
    12.       proxy_auth_domain:
    13.         http_enabled: true
    14.         transport_enabled: true
    15.         order: 0
    16.         http_authenticator:
    17.           type: proxy
    18.           #type: extended-proxy
    19.           challenge: false
    20.           config:
    21.             user_header: "x-proxy-user"
    22.             roles_header: "x-proxy-roles"
    23.             #attr_header_prefix: "x-proxy-ext-"
    24.         authentication_backend:
    25.           type: noop
    1. enabled: true
    2. 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.

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

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

    To pass the user and role headers that the authenticating proxy adds from OpenSearch Dashboards to the Security plugin, add them to the HTTP header allow list in opensearch_dashboards.yml:

    1. opensearch.requestHeadersAllowlist: ["securitytenant","Authorization","x-forwarded-for","x-proxy-user","x-proxy-roles"]
    1. opensearch_security.auth.type: "proxy"
    3. opensearch_security.proxycache.roles_header: "x-proxy-roles"