A reverse proxy that provides authentication using OAuth2 via Google, GitHub, etc

go get



A reverse proxy that provides authentication using Google OAuth2 to validate individual accounts, or a whole google apps domain.

Build Status


    _______       ___________________       __________
    |Nginx| ----> |google_auth_proxy| ----> |upstream| 
    -------       -------------------       ----------
                  [google oauth2 api]


  1. Install Go
  2. $ go get This should put the binary in $GOROOT/bin

OAuth Configuration

You will need to register an OAuth application with google, and configure it with Redirect URI(s) for the domain you intend to run google_auth_proxy on.

  1. Create a new project:
  2. Under "APIs & Auth", choose "Credentials"
  3. Now, choose "Create new Client ID"
    • The Application Type should be Web application
    • Enter your domain in the Authorized Javascript Origins
    • Enter the correct Authorized Redirect URL
      • NOTE: google_auth_proxy will only callback on the path /oauth2/callback
  4. Under "APIs & Auth" choose "Consent Screen"
    • Fill in the necessary fields and Save (this is required)
  5. Take note of the Client ID and Client Secret

Command Line Options

Usage of ./google_auth_proxy:
  -authenticated-emails-file="": authenticate against emails via file (one per line)
  -client-id="": the Google OAuth Client ID: ie: ""
  -client-secret="": the OAuth Client Secret
  -cookie-domain="": an optional cookie domain to force cookies to
  -cookie-secret="": the seed string for secure cookies
  -google-apps-domain="": authenticate against the given google apps domain
  -htpasswd-file="": additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption
  -http-address="": <addr>:<port> to listen on for HTTP clients
  -pass-basic-auth=true: pass HTTP Basic Auth information to upstream
  -redirect-url="": the OAuth Redirect URL. ie: ""
  -upstream=[]: the http url(s) of the upstream endpoint. If multiple, routing is based on path
  -version=false: print version string

Example Configuration

This example has a Nginx SSL endpoint proxying to google_auth_proxy on port 4180. google_auth_proxy then authenticates requests for an upstream application running on port 8080. The external endpoint for this example would be

An example Nginx config follows. Note the use of Strict-Transport-Security header to pin requests to SSL via HSTS:

server {
    listen 443 default ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/cert.key;
    add_header Strict-Transport-Security max-age=1209600;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_connect_timeout 1;
        proxy_send_timeout 30;
        proxy_read_timeout 30;

The command line to run google_auth_proxy would look like this:

./google_auth_proxy \
   --redirect-url=""  \
   --google-apps-domain=""  \
   --upstream= \
   --cookie-secret=... \
   --client-id=... \

Environment variables

The environment variables google_auth_client_id, google_auth_secret and google_auth_cookie_secret can be used in place of the corresponding command-line arguments.

Endpoint Documentation

Google auth proxy responds directly to the following endpoints. All other endpoints will be authenticated.

  • /oauth2/sign_in - the login page, which also doubles as a sign out page (it clears cookies)
  • /oauth2/start - a URL that will redirect to start the oauth cycle
  • /oauth2/callback - the URL used at the end of the oauth cycle