oauth2_proxy/README.md

110 lines
4.1 KiB
Markdown
Raw Normal View History

2012-12-11 01:34:58 +00:00
google_auth_proxy
=================
2012-12-17 18:03:34 +00:00
A reverse proxy that provides authentication using Google OAuth2 to validate
2012-12-11 01:34:58 +00:00
individual accounts, or a whole google apps domain.
2012-12-26 18:18:56 +00:00
[![Build Status](https://secure.travis-ci.org/bitly/google_auth_proxy.png?branch=master)](http://travis-ci.org/bitly/google_auth_proxy)
2012-12-11 01:34:58 +00:00
2012-12-26 18:19:03 +00:00
## Architecture
2012-12-11 01:34:58 +00:00
```
_______ ___________________ __________
|Nginx| ----> |google_auth_proxy| ----> |upstream|
------- ------------------- ----------
||
\/
[google oauth2 api]
```
2012-12-26 18:19:03 +00:00
## Installation
1. [Install Go](http://golang.org/doc/install)
2012-12-26 20:02:26 +00:00
2. `$ go get github.com/bitly/google_auth_proxy`. This should put the binary in `$GOROOT/bin`
2012-12-26 18:19:03 +00:00
## 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. Visit to Google Api Console https://code.google.com/apis/console/
2012-12-17 18:04:48 +00:00
2. under "API Access", choose "Create an OAuth 2.0 Client ID"
3. Edit the application settings, and list the Redirect URI(s) where you will run your application. For example:
2012-12-11 01:34:58 +00:00
`https://internalapp.yourcompany.com/oauth2/callback`
2012-12-26 18:19:03 +00:00
4. Make a note of the Client ID, and Client Secret and specify those values as command line arguments
2012-12-11 01:34:58 +00:00
2012-12-26 18:19:03 +00:00
## Command Line Options
2012-12-11 01:34:58 +00:00
```
2012-12-11 01:59:23 +00:00
Usage of ./google_auth_proxy:
-authenticated-emails-file="": authenticate against emails via file (one per line)
2012-12-11 01:34:58 +00:00
-client-id="": the Google OAuth Client ID: ie: "123456.apps.googleusercontent.com"
2012-12-11 01:59:23 +00:00
-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
2012-12-26 21:53:02 +00:00
-http-address="127.0.0.1:4180": <addr>:<port> to listen on for HTTP clients
2012-12-11 01:59:23 +00:00
-pass-basic-auth=true: pass HTTP Basic Auth information to upstream
-redirect-url="": the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
-upstream=[]: the http url(s) of the upstream endpoint. If multiple, routing is based on path
-version=false: print version string
```
2012-12-11 02:11:24 +00:00
2012-12-26 18:19:03 +00:00
## Example Configuration
2012-12-11 02:11:24 +00:00
2012-12-26 21:53:02 +00:00
This example has a [Nginx](http://nginx.org/) 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/`.
2012-12-11 02:11:24 +00:00
2012-12-26 21:53:02 +00:00
An example Nginx config follows. Note the use of `Strict-Transport-Security` header to pin requests to SSL
via [HSTS](http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security):
2012-12-11 02:11:24 +00:00
```
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;
}
}
```
2012-12-26 15:35:02 +00:00
2012-12-26 21:53:02 +00:00
The command line to run `google_auth_proxy` would look like this:
```bash
./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=... \
--client-id=... \
--client-secret=...
```
## Environment variables
2012-12-26 21:53:02 +00:00
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.
2012-12-26 21:53:02 +00:00
2012-12-26 18:19:03 +00:00
## Endpoint Documentation
Google auth proxy responds directly to the following endpoints. All other endpoints will be authenticated.
2012-12-26 15:35:02 +00:00
* /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