Name: oauth2_proxy
Owner: BuzzFeed
Description: A reverse proxy that provides authentication with Google, Github or other provider
Forked from: bitly/oauth2_proxy
Created: 2017-07-13 08:34:42.0
Updated: 2017-07-13 08:34:44.0
Pushed: 2017-07-06 15:18:59.0
Size: 407
Language: Go
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group.
v2.2
) or build with $ go get github.com/bitly/oauth2_proxy
which will put the binary in $GOROOT/bin
You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run oauth2_proxy
on.
Valid providers are :
The provider can be selected using the provider
configuration value.
For Google, the registration steps are:
https://internal.yourcompany.com
https://internal.yourcompany.com/oauth2/callback
It's recommended to refresh sessions on a short interval (1h) with cookie-refresh
setting which validates that the account is still authorized.
s://www.googleapis.com/auth/admin.directory.group.readonly
s://www.googleapis.com/auth/admin.directory.user.readonly
`google-admin-email
` flag. This email will be impersonated by this client to make calls to the Admin SDK. See the note on the link from step 5 for the reason why.`google-group
` flag. You can pass multiple instances of this flag with different groups
and the user will be checked against all the provided groups.`google-service-account-json
` flag.Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).
https://internal.yourcompany.com/oauth2/callback
TenantID
and provide it via the --azure-tenant=<YOUR TENANT ID>
commandline option. Default the common
tenant is used.The Azure AD auth provider uses openid
as it default scope. It uses https://graph.windows.net
as a default protected resource. It call to https://graph.windows.net/me
to get the email address of the user that logs in.
https://internal.yourcompany.com/oauth2/callback
Authorization callback URL
enter the correct url ie https://internal.yourcompany.com/oauth2/callback
The GitHub auth provider supports two additional parameters to restrict authentication to Organization or Team level access. Restricting by org and team is normally accompanied with --email-domain=*
-github-org="": restrict logins to members of this organisation
-github-team="": restrict logins to members of any of these teams, separated by a comma
If you are using GitHub enterprise, make sure you set the following to the appropriate url:
-login-url="http(s)://<enterprise github host>/login/oauth/authorize"
-redeem-url="http(s)://<enterprise github host>/login/oauth/access_token"
-validate-url="http(s)://<enterprise github host>/api/v3"
Whether you are using GitLab.com or self-hosting GitLab, follow these steps to add an application
If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:
-login-url="<your gitlab url>/oauth/authorize"
-redeem-url="<your gitlab url>/oauth/token"
-validate-url="<your gitlab url>/api/v3/user"
For LinkedIn, the registration steps are:
https://internal.yourcompany.com/oauth2/callback
The MyUSA authentication service (GitHub)
For adding an application to the Microsoft Azure AD follow these steps to add an application.
Take note of your TenantId
if applicable for your situation. The TenantId
can be used to override the default common
authorization server with a tenant specific server.
To authorize by email domain use --email-domain=yourcompany.com
. To authorize individual email addresses use --authenticated-emails-file=/path/to/file
with one email per line. To authorize all email addresses use --email-domain=*
.
oauth2_proxy
can be configured via config file, command line options or environment variables.
To generate a strong cookie secret use python -c 'import os,base64; print base64.b64encode(os.urandom(16))'
An example oauth2_proxy.cfg config file is in the contrib directory. It can be used by specifying -config=/etc/oauth2_proxy.cfg
e of oauth2_proxy:
pproval-prompt string: OAuth approval_prompt (default "force")
uthenticated-emails-file string: authenticate against emails via file (one per line)
zure-tenant string: go to a tenant-specific or common (tenant-independent) endpoint. (default "common")
asic-auth-password string: the password to set when passing the HTTP Basic Auth header
lient-id string: the OAuth Client ID: ie: "123456.apps.googleusercontent.com"
lient-secret string: the OAuth Client Secret
onfig string: path to config file
ookie-domain string: an optional cookie domain to force cookies to (ie: .yourcompany.com)*
ookie-expire duration: expire timeframe for cookie (default 168h0m0s)
ookie-httponly: set HttpOnly cookie flag (default true)
ookie-name string: the name of the cookie that the oauth_proxy creates (default "_oauth2_proxy")
ookie-refresh duration: refresh the cookie after this duration; 0 to disable
ookie-secret string: the seed string for secure cookies (optionally base64 encoded)
ookie-secure: set secure (HTTPS) cookie flag (default true)
ustom-templates-dir string: path to custom html templates
isplay-htpasswd-form: display username / password login form if an htpasswd file is provided (default true)
mail-domain value: authenticate emails with the specified domain (may be given multiple times). Use * to authenticate any email
ooter string: custom footer string. Use "-" to disable default footer.
ithub-org string: restrict logins to members of this organisation
ithub-team string: restrict logins to members of this team
oogle-admin-email string: the google admin to impersonate for api calls
oogle-group value: restrict logins to members of this google group (may be given multiple times).
oogle-service-account-json string: the path to the service account json credentials
tpasswd-file string: additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption
ttp-address string: [http://]<addr>:<port> or unix://<path> to listen on for HTTP clients (default "127.0.0.1:4180")
ttps-address string: <addr>:<port> to listen on for HTTPS clients (default ":443")
ogin-url string: Authentication endpoint
ass-access-token: pass OAuth access_token to upstream via X-Forwarded-Access-Token header
ass-basic-auth: pass HTTP Basic Auth, X-Forwarded-User and X-Forwarded-Email information to upstream (default true)
ass-host-header: pass the request Host Header to upstream (default true)
ass-user-headers: pass X-Forwarded-User and X-Forwarded-Email information to upstream (default true)
rofile-url string: Profile access endpoint
rovider string: OAuth provider (default "google")
roxy-prefix string: the url root path that this proxy should be nested under (e.g. /<oauth2>/sign_in) (default "/oauth2")
edeem-url string: Token redemption endpoint
edirect-url string: the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
equest-logging: Log requests to stdout (default true)
esource string: The resource that is protected (Azure AD only)
cope string: OAuth scope specification
et-xauthrequest: set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode)
ignature-key string: GAP-Signature request signature key (algorithm:secretkey)
kip-auth-preflight: will skip authentication for OPTIONS requests
kip-auth-regex value: bypass authentication for requests path's that match (may be given multiple times)
kip-provider-button: will skip sign-in-page to directly reach the next step: oauth/start
sl-insecure-skip-verify: skip validation of certificates presented when using HTTPS
ls-cert string: path to certificate file
ls-key string: path to private key file
pstream value: the http url(s) of the upstream endpoint or file:// paths for static files. Routing is based on the path
alidate-url string: Access token validation endpoint
ersion: print version string
See below for provider specific options
oauth2_proxy
supports having multiple upstreams, and has the option to pass requests on to HTTP(S) servers or serve static files from the file system. HTTP and HTTPS upstreams are configured by providing a URL such as http://127.0.0.1:8080/
for the upstream parameter, that will forward all authenticated requests to be forwarded to the upstream server. If you instead provide http://127.0.0.1:8080/some/path/
then it will only be requests that start with /some/path/
which are forwarded to the upstream.
Static file paths are configured as a file:// URL. file:///var/www/static/
will serve the files from that directory at http://[oauth2_proxy url]/var/www/static/
, which may not be what you want. You can provide the path to where the files should be available by adding a fragment to the configured URL. The value of the fragment will then be used to specify which path the files are available at. file:///var/www/static/#/static/
will ie. make /var/www/static/
available at http://[oauth2_proxy url]/static/
.
Multiple upstreams can either be configured by supplying a comma separated list to the -upstream
parameter, supplying the parameter multiple times or provinding a list in the config file. When multiple upstreams are used routing to them will be based on the path they are set up with.
The following environment variables can be used in place of the corresponding command-line arguments:
OAUTH2_PROXY_CLIENT_ID
OAUTH2_PROXY_CLIENT_SECRET
OAUTH2_PROXY_COOKIE_NAME
OAUTH2_PROXY_COOKIE_SECRET
OAUTH2_PROXY_COOKIE_DOMAIN
OAUTH2_PROXY_COOKIE_EXPIRE
OAUTH2_PROXY_COOKIE_REFRESH
OAUTH2_PROXY_SIGNATURE_KEY
There are two recommended configurations.
1) Configure SSL Terminiation with OAuth2 Proxy by providing a --tls-cert=/path/to/cert.pem
and --tls-key=/path/to/cert.key
.
The command line to run oauth2_proxy
in this configuration would look like this:
uth2_proxy \
-email-domain="yourcompany.com" \
-upstream=http://127.0.0.1:8080/ \
-tls-cert=/path/to/cert.pem \
-tls-key=/path/to/cert.key \
-cookie-secret=... \
-cookie-secure=true \
-provider=... \
-client-id=... \
-client-secret=...
2) Configure SSL Termination with Nginx (example config below), Amazon ELB, Google Cloud Platform Load Balancing, or ….
Because oauth2_proxy
listens on 127.0.0.1:4180
by default, to listen on all interfaces (needed when using an
external load balancer like Amazon ELB or Google Platform Load Balancing) use --http-address="0.0.0.0:4180"
or
--http-address="http://:4180"
.
Nginx will listen on port 443
and handle SSL connections while proxying to oauth2_proxy
on port 4180
.
oauth2_proxy
will then authenticate requests for an upstream application. 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:
er {
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=2592000;
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 oauth2_proxy
in this configuration would look like this:
uth2_proxy \
-email-domain="yourcompany.com" \
-upstream=http://127.0.0.1:8080/ \
-cookie-secret=... \
-cookie-secure=true \
-provider=... \
-client-id=... \
-client-secret=...
OAuth2 Proxy responds directly to the following endpoints. All other endpoints will be proxied upstream when authenticated. The /oauth2
prefix can be changed with the --proxy-prefix
config variable.
auth_request
directiveIf signature_key
is defined, proxied requests will be signed with the
GAP-Signature
header, which is a Hash-based Message Authentication Code (HMAC)
of selected request information and the request body see SIGNATURE_HEADERS
in oauthproxy.go
.
signature_key
must be of the form algorithm:secretkey
, (ie: signature_key = "sha1:secret0"
)
For more information about HMAC request signature validation, read the following:
OAuth2 Proxy logs requests to stdout in a format similar to Apache Combined Log.
OTE_ADDRESS> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] <HOST_HEADER> GET <UPSTREAM_HOST> "/path/" HTTP/1.1 "<USER_AGENT>" <RESPONSE_CODE> <RESPONSE_BYTES> <REQUEST_DURATION>
Follow the examples in the providers
package to define a new
Provider
instance. Add a new case
to
providers.New()
to allow oauth2_proxy
to use the
new Provider
.
auth_request
directiveThe Nginx auth_request
directive allows Nginx to authenticate requests via the oauth2_proxy's /auth
endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
er {
sten 443 ssl;
rver_name ...;
clude ssl/ssl.conf;
cation /oauth2/ {
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_set_header X-Auth-Request-Redirect $request_uri;
cation / {
auth_request /oauth2/auth;
error_page 401 = /oauth2/sign_in;
# pass information via X-User and X-Email headers to backend,
# requires running with --set-xauthrequest flag
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
# if you enabled --cookie-refresh, this is needed for it to work with auth_request
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://backend/;
# or "root /path/to/site;" or "fastcgi_pass ..." etc