Version: 7.x-45.0.0
This is an older version of Search Guard. Switch to Latest version
Community

Enhanced HTTP-header/Proxy based authentication

The enhanced proxy2 authenticator enables you, just like the regular proxy authenticator does to use a single sign on (SSO) solution (you might already have) instead of the Search Guard authentication backend. But it also offers some extra features that are not part of the regular proxy authenticator. The enhanced proxy2 authenticator comes with four different authentication modes that enable you to not only use hostnames as validation but also certificates. This feature is very useful if you have a system where hostnames change. Another extra feature is the option to configure custom user attributes that can carry additional user information.

Configuration

To enable enhanced proxy2 authenticator with additional features just add the proxy2 authenticator as a new auth domain to your sg_config.yml as shown below and configure auth_mode to fit your needs (“ip”, “cert”, “both” or “either”).

sg_config:
    dynamic:
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                        auth_mode: "both"
                        user_header: "x-proxy-user"
                        roles_header: "x-proxy-roles"
                        roles_separator: ","
                authentication_backend:
                    type: "noop"
Config name Default value Description
auth_mode “both” Sets the authentication mode
user_header “x-proxy-user” Sets the name of the header containing the username
roles_header “x-proxy-roles” Sets the name of the header containing the user roles
roles_separator ”,” Sets the separator that separates roles in the roles header content
Possible auth_mode values Description
“ip” Authentication works just like in the regular proxy authenticator with a x-forwarded-for header as validation
“cert” Authenticates the request if a valid client certificate is given
“both” Authenticates the request if both a correct x-forwarded-for header and a valid client certificate is given
“either” Authenticates the request if either a correct x-forwarded-for header or a valid client certificate is given

Using ‘ip’ mode: Hostname validation

The ‘ip’ mode compares the remote address with a list of configured internal proxies. If the remote address is not in the list of trusted proxies, it is treated like a client request. Proxy authentication will not work in this case.

If you choose ‘ip’ mode make sure you enabled x-forwarded-for (xff) and configured your internalProxies inside the sg_config.yml file as shown in the example below.

sg_config:
    dynamic:
        http:
            xff:
                enabled: true
                internalProxies: '192\.168\.0\.10|192\.168\.0\.11'
                remoteIpHeader:  'x-forwarded-for'
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                        auth_mode: "ip"
                        user_header: "x-proxy-user"
                        roles_header: "x-proxy-roles"
                        roles_separator: ","
                authentication_backend:
                    type: "noop"
xff config name Default value Description
enabled true Enables or disables x-forwarded-for
internalProxies   Ip-addresses of all trusted proxies
remoteIpHeader “x-forwarded-for” Name of the header where the chain of hostnames is stored

Using ‘client’ mode: Client certificate validation

The ‘client’ mode is especially useful in systems without static hostnames. It performs a certificate validation instead of a hostname check. Besides a valid certificate the DN has to match a pre-configured DN-whitelist.

sg_config:
    dynamic:
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                        auth_mode: "cert"
                        user_header: "x-proxy-user"
                        roles_header: "x-proxy-roles"
                        roles_separator: ","
                        allowed_dn_s:
                            - "trusted DN 1"
                            - "trusted DN 2"
                authentication_backend:
                    type: "noop"
Config name Default value Description
allowed_dn_s   List of trusted DNs

Using ‘both’ mode: Client certificate and hostname validation

The ‘both’ mode basically combines the ‘ip’ mode and the ‘cert’ mode. That means that it checks not only the hostnames given by the x-forwarded-for (xff) header but also if a valid client certificate is given which DN matches one of the configured DNs.

Just as in the ip-mode you have to activate x-forwarded-for (xff) and whitelist your proxy hostnames inside the sg_config.yml file. In addition to that you need to configure valid DNs just like in ‘cert’ mode as shown in the example below.

sg_config:
    dynamic:
        http:
            xff:
                enabled: true
                internalProxies: '192\.168\.0\.10|192\.168\.0\.11'
                remoteIpHeader:  'x-forwarded-for'
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                        auth_mode: "both"
                        user_header: "x-proxy-user"
                        roles_header: "x-proxy-roles"
                        roles_separator: ","
                        allowed_dn_s:
                            - "trusted DN 1"
                            - "trusted DN 2"
                authentication_backend:
                    type: "noop"
xff config name Default value Description
enabled true Enables or disables x-forwarded-for
internalProxies   Ip-addresses of all trusted proxies
remoteIpHeader “x-forwarded-for” Name of the header where the chain of hostnames is stored
Config name Default value Description
allowed_dn_s   List of trusted DNs

Using ‘either’ mode: Client certificate or hostname validation

The ‘either’ mode checks if either the certificate or the hostname is valid.

sg_config:
    dynamic:
        http:
            xff:
                enabled: true
                internalProxies: '192\.168\.0\.10|192\.168\.0\.11'
                remoteIpHeader:  'x-forwarded-for'
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                        auth_mode: "either"
                        user_header: "x-proxy-user"
                        roles_header: "x-proxy-roles"
                        roles_separator: ","
                        allowed_dn_s:
                            - "trusted DN 1"
                            - "trusted DN 2"
                authentication_backend:
                    type: "noop"
xff config name Default value Description
enabled true Enables or disables x-forwarded-for
internalProxies   Ip-addresses of all trusted proxies
remoteIpHeader “x-forwarded-for” Name of the header where the chain of hostnames is stored
Config name Default value Description
allowed_dn_s   List of trusted DNs

Using Further Headers as Search Guard User Attributes

Search Guard allows to use further HTTP header values to construct dynamic index patterns and dynamic queries for document and field level security. In order to use these header values, you need to use the configuration attribute map_headers_to_user_attrs to provide a mapping from HTTP header values to Search Guard user attributes inside the authenticator configuration.

As the other proxy authenticator configuration, the map_headers_to_user_attrs attribute needs to be placed in the config section of the http_authenticator configuration. As value, you need to provide a map of the form search_guard_user_attribute: http_header_name.

This might look like this:

sg_config:
    dynamic:
        authc:
            proxy2_auth_domain:
                http_enabled: true
                transport_enabled: true
                order: 0
                http_authenticator:
                    type: "proxy2"
                    challenge: false
                    config:
                      map_ldap_attrs_to_user_attrs:
                        department: "x-user-dept"
                        email_address: "x-user-mail"
                authentication_backend:
                    type: "noop"

This adds the attributes department and email_address to the Search Guard user and sets them to the respective values from the HTTP headers.

In the Search Guard role configuration, the attributes can be then used like this:

my_dls_role:
  index_permissions:
  - index_patterns:
    - "dls_test"
    dls: '{"terms" : {"filter_attr": ${user.attrs.department|toList|toJson}}}'
    allowed_actions:
    - "READ"

Note: Take care that the mapped attributes are of reasonable size. As the attributes need to be internally forwarded over the network for each operation in the Elasticsearch cluster, attributes carrying a big amount of data may cause a performance penalty.

Note: This method of providing attributes supersedes the old way which provided the headers listed in the attribute_headers configuration as Search Guard user attributes with the prefix attr.proxy2. These attributes are still supported, but are now deprecated.



Not what you were looking for? Try the search.