regius/google-auth-proxy

•Updated almost 11 years ago

Image

3.7K

regius/google-auth-proxy repository overview

⁠google_auth_proxy

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

sign_in_page

⁠Architecture

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

⁠Installation

Download Prebuilt Binary⁠ or build from master with $ go get github.com/bitly/google_auth_proxy which should put the binary in $GOROOT/bin
Register an OAuth Application with Google
Configure Google Auth Proxy using config file, command line options, or environment variables
Deploy behind a SSL endpoint (example provided for Nginx)

⁠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.

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

⁠Configuration

google_auth_proxy can be configured via config file⁠, command line options⁠ or environment variables⁠.

⁠Config File

An example google_auth_proxy.cfg⁠ config file is in the contrib directory. It can be used by specifying -config=/etc/google_auth_proxy.cfg

⁠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: "123456.apps.googleusercontent.com"
  -client-secret="": the OAuth Client Secret
  -config="": path to config file
  -cookie-domain="": an optional cookie domain to force cookies to (ie: .yourcompany.com)*
  -cookie-expire=168h0m0s: expire timeframe for cookie
  -cookie-httponly=true: set HttpOnly cookie
  -cookie-https-only=true: set HTTPS only cookie
  -cookie-secret="": the seed string for secure cookies
  -display-htpasswd-form=true: display username / password login form if an htpasswd file is provided
  -google-apps-domain=: authenticate against the given Google apps domain (may be given multiple times)
  -htpasswd-file="": additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption
  -http-address="127.0.0.1:4180": [http://]<addr>:<port> or unix://<path> to listen on for HTTP clients
  -pass-basic-auth=true: pass HTTP Basic Auth, X-Forwarded-User and X-Forwarded-Email information to upstream
  -pass-host-header=true: pass the request Host Header to upstream
  -redirect-url="": the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
  -skip-auth-regex=: bypass authentication for requests path's that match (may be given multiple times)
  -custom templates-dir="": path to custom html templates
  -upstream=: the http url(s) of the upstream endpoint. If multiple, routing is based on path
  -version=false: print version string

⁠Environment variables

The environment variables GOOGLE_AUTH_PROXY_CLIENT_ID, GOOGLE_AUTH_PROXY_CLIENT_SECRET, GOOGLE_AUTH_PROXY_COOKIE_SECRET, GOOGLE_AUTH_PROXY_COOKIE_DOMAIN and GOOGLE_AUTH_PROXY_COOKIE_EXPIRE can be used in place of the corresponding command-line arguments.

⁠Example Nginx 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 https://internal.yourcompany.com/.

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;
    server_name internal.yourcompany.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/cert.key;
    add_header Strict-Transport-Security max-age=1209600;

    location / {
        proxy_pass http://127.0.0.1:4180;
        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="https://internal.yourcompany.com/oauth2/callback"  \
   --google-apps-domain="yourcompany.com"  \
   --upstream=http://127.0.0.1:8080/ \
   --cookie-secret=... \
   --cookie-https-only=true \
   --client-id=... \
   --client-secret=...

⁠Endpoint Documentation

Google Auth Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated.

/ping - returns an 200 OK response
/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

Tag summary

Recent tags

Content type

Image

Digest

sha256:da10e9c31…

Size

169 MB

Last updated

almost 11 years ago

docker pull regius/google-auth-proxy