git.iko.soy/typeable/oauth2-proxy
on v0.1 help sign in
typeable/oauth2-proxy/README.md
115 lines 4.5 kB history raw
1google_auth_proxy
2=================
5A reverse proxy that provides authentication using Google OAuth2 to validate
6individual accounts, or a whole google apps domain.
8[![Build Status](https://secure.travis-ci.org/bitly/google_auth_proxy.png?branch=master)](http://travis-ci.org/bitly/google_auth_proxy)
11## Architecture
13```
14 _______ ___________________ __________
15 |Nginx| ----> |google_auth_proxy| ----> |upstream|
16 ------- ------------------- ----------
17 ||
18 \/
19 [google oauth2 api]
20```
23## Installation
251. [Install Go](http://golang.org/doc/install)
262. `$ go get github.com/bitly/google_auth_proxy`. This should put the binary in `$GOROOT/bin`
28## OAuth Configuration
30You will need to register an OAuth application with google, and configure it with Redirect URI(s) for the domain you
31intend to run `google_auth_proxy` on.
331. Create a new project: https://console.developers.google.com/project
342. Under "APIs & Auth", choose "Credentials"
353. Now, choose "Create new Client ID"
36 * The Application Type should be **Web application**
37 * Enter your domain in the Authorized Javascript Origins `https://internal.yourcompany.com`
38 * Enter the correct Authorized Redirect URL `https://internal.yourcompany.com/oauth2/callback`
39 * NOTE: `google_auth_proxy` will _only_ callback on the path `/oauth2/callback`
404. Under "APIs & Auth" choose "Consent Screen"
41 * Fill in the necessary fields and Save (this is _required_)
425. Take note of the **Client ID** and **Client Secret**
45## Command Line Options
47```
48Usage of ./google_auth_proxy:
49 -authenticated-emails-file="": authenticate against emails via file (one per line)
50 -client-id="": the Google OAuth Client ID: ie: "123456.apps.googleusercontent.com"
51 -client-secret="": the OAuth Client Secret
52 -cookie-domain="": an optional cookie domain to force cookies to
53 -cookie-secret="": the seed string for secure cookies
54 -google-apps-domain="": authenticate against the given google apps domain
55 -htpasswd-file="": additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption
56 -http-address="127.0.0.1:4180": <addr>:<port> to listen on for HTTP clients
57 -pass-basic-auth=true: pass HTTP Basic Auth information to upstream
58 -redirect-url="": the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
59 -upstream=[]: the http url(s) of the upstream endpoint. If multiple, routing is based on path
60 -version=false: print version string
61```
64## Example Configuration
66This example has a [Nginx](http://nginx.org/) SSL endpoint proxying to `google_auth_proxy` on port `4180`.
67`google_auth_proxy` then authenticates requests for an upstream application running on port `8080`. The external
68endpoint for this example would be `https://internal.yourcompany.com/`.
70An example Nginx config follows. Note the use of `Strict-Transport-Security` header to pin requests to SSL
71via [HSTS](http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security):
73```
74server {
75 listen 443 default ssl;
76 server_name internal.yourcompany.com;
77 ssl_certificate /path/to/cert.pem;
78 ssl_certificate_key /path/to/cert.key;
79 add_header Strict-Transport-Security max-age=1209600;
81 location / {
82 proxy_pass http://127.0.0.1:4180;
83 proxy_set_header Host $host;
84 proxy_set_header X-Real-IP $remote_addr;
85 proxy_set_header X-Scheme $scheme;
86 proxy_connect_timeout 1;
87 proxy_send_timeout 30;
88 proxy_read_timeout 30;
89 }
91```
93The command line to run `google_auth_proxy` would look like this:
95```bash
96./google_auth_proxy \
97 --redirect-url="https://internal.yourcompany.com/oauth2/callback" \
98 --google-apps-domain="yourcompany.com" \
99 --upstream=http://127.0.0.1:8080/ \
100 --cookie-secret=... \
101 --client-id=... \
102 --client-secret=...
103```
105## Environment variables
107The 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.
109## Endpoint Documentation
111Google auth proxy responds directly to the following endpoints. All other endpoints will be authenticated.
113* /oauth2/sign_in - the login page, which also doubles as a sign out page (it clears cookies)
114* /oauth2/start - a URL that will redirect to start the oauth cycle
115* /oauth2/callback - the URL used at the end of the oauth cycle