Authenticating Proxy

NOTE: This connector is experimental and may change in the future.

Overview

The authproxy connector returns identities based on authentication which your front-end web server performs. Dex consumes the X-Remote-User header set by the proxy, which is then used as the user’s email address.

It also consumes the X-Remote-Group header to use as the user’s group.

Header’s names can be configured via the userHeader and groupHeader config.

Additional static groups can also be defined in the connector’s configuration.

The proxy MUST remove any X-Remote-* headers set by the client, for any URL path, before the request is forwarded to dex.

The connector does not support refresh tokens.

Configuration

The authproxy connector is used by proxies to implement login strategies not supported by dex. For example, a proxy could handle a different OAuth2 strategy such as Slack:

  1. connectors:
  2. # Slack login implemented by an authenticating proxy, not by dex.
  3. - type: authproxy
  4.   id: slack
  5.   name: Slack

The proxy only needs to authenticate the user when they attempt to visit the callback URL path:

  1. ( dex issuer URL )/callback/( connector id )?( url query )

For example, if dex is running at https://auth.example.com/dex and the connector ID is slack, the callback URL would look like:

  1. https://auth.example.com/dex/callback/slack?state=xdg3z6quhrhwaueo5iysvliqf

The proxy should login the user then return them to the exact URL (including the query), setting X-Remote-User to the user’s email before proxying the request to dex.

Configuration example - Apache 2

The following is an example config file that can be used by the external connector to authenticate a user.

  1. connectors:
  2. - type: authproxy
  3.   id: myBasicAuth
  4.   name: HTTP Basic Auth
  5.   config:
  6.     userHeader: X-Forwarded-User # default is X-Remote-User
  7.     groupHeader: X-Forwarded-Group # default is X-Remote-Group
  8.     staticGroups:
  9.     - default

The authproxy connector assumes that you configured your front-end web server such that it performs authentication for the /dex/callback/myBasicAuth location and provides the result in the HTTP headers.

In this example, the configured headers are X-Forwarded-User for the user’s mail and X-Forwarded-Group for the user’s group. Dex authproxy connector will return a list of groups containing both configured staticGroups and return the group header.

The following configuration will work for Apache 2.4.10+:

  1. <Location /dex/>
  2.     ProxyPass "http://localhost:5556/dex/"
  3.     ProxyPassReverse "http://localhost:5556/dex/"
  5.     # Strip the X-Remote-User header from all requests except for the ones
  6.     # where we override it.
  7.     RequestHeader unset X-Remote-User
  8. </Location>
  10. <Location /dex/callback/myBasicAuth>
  11.     AuthType Basic
  12.     AuthName "db.debian.org webPassword"
  13.     AuthBasicProvider file
  14.     AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
  15.     Require valid-user
  17.     # Defense in depth: clear the Authorization header so that
  18.     # Debian Web Passwords never even reach dex.
  19.     RequestHeader unset Authorization
  21.     # Requires Apache 2.4.10+
  22.     RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org
  24.     ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
  25.     ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
  26. </Location>

Full Apache2 setup

After installing your Linux distribution’s Apache2 package, place the following virtual host configuration in e.g. /etc/apache2/sites-available/sso.conf:

  1. <VirtualHost sso.example.net>
  2.     ServerName sso.example.net
  4.     ServerAdmin webmaster@localhost
  5.     DocumentRoot /var/www/html
  7.     ErrorLog ${APACHE_LOG_DIR}/error.log
  8.     CustomLog ${APACHE_LOG_DIR}/access.log combined
  10.     <Location /dex/>
  11.         ProxyPass "http://localhost:5556/dex/"
  12.         ProxyPassReverse "http://localhost:5556/dex/"
  14.         # Strip the X-Remote-User header from all requests except for the ones
  15.         # where we override it.
  16.         RequestHeader unset X-Remote-User
  17.     </Location>
  19.     <Location /dex/callback/myBasicAuth>
  20.         AuthType Basic
  21.         AuthName "db.debian.org webPassword"
  22.         AuthBasicProvider file
  23.         AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
  24.         Require valid-user
  26.         # Defense in depth: clear the Authorization header so that
  27.         # Debian Web Passwords never even reach dex.
  28.         RequestHeader unset Authorization
  30.         # Requires Apache 2.4.10+
  31.         RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org
  33.         ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
  34.         ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
  35.     </Location>
  36. </VirtualHost>

Then, enable it using a2ensite sso.conf, followed by a restart of Apache2.