@@ -1,11 +1,13 @@
1−oauth2_proxy
1+# oauth2_proxy
4A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others)
3A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others)
5to validate accounts by email, domain or group.
4to validate accounts by email, domain or group.
7−[](http://travis-ci.org/bitly/oauth2_proxy)
6+**Note:** This repository was forked from [Bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy) on 27/11/2018.
7+Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork.
8+A list of changes can be seen in the [CHANGELOG](CHANGELOG.md).
10+[](http://travis-ci.org/bitly/oauth2_proxy)
10
12
@@ -15,15 +17,17 @@ to validate accounts by email, domain or group.
16## Installation
18## Installation
18−1. Download [Prebuilt Binary](https://github.com/bitly/oauth2_proxy/releases) (current release is `v2.2`) or build with `$ go get github.com/bitly/oauth2_proxy` which will put the binary in `$GOROOT/bin`
20+1. Download [Prebuilt Binary](https://github.com/bitly/oauth2_proxy/releases) (current release is `v2.2`) or build with `$ go get github.com/bitly/oauth2_proxy` which will put the binary in `$GOROOT/bin`
19−Prebuilt binaries can be validated by extracting the file and verifying it against the `sha256sum.txt` checksum file provided for each release starting with version `v2.3`.
21+ Prebuilt binaries can be validated by extracting the file and verifying it against the `sha256sum.txt` checksum file provided for each release starting with version `v2.3`.
21sha256sum -c sha256sum.txt 2>&1 | grep OK
24sha256sum -c sha256sum.txt 2>&1 | grep OK
22oauth2_proxy-2.3.linux-amd64: OK
25oauth2_proxy-2.3.linux-amd64: OK
24−2. Select a Provider and Register an OAuth Application with a Provider
28+2. Select a Provider and Register an OAuth Application with a Provider
25−3. Configure OAuth2 Proxy using config file, command line options, or environment variables
29+3. Configure OAuth2 Proxy using config file, command line options, or environment variables
26−4. Configure SSL or Deploy behind a SSL endpoint (example provided for Nginx)
30+4. Configure SSL or Deploy behind a SSL endpoint (example provided for Nginx)
28## OAuth Provider Configuration
32## OAuth Provider Configuration
@@ -31,12 +35,12 @@ You will need to register an OAuth application with a Provider (Google, GitHub o
32Valid providers are :
36Valid providers are :
34−* [Google](#google-auth-provider) *default*
38+- [Google](#google-auth-provider) _default_
35−* [Azure](#azure-auth-provider)
39+- [Azure](#azure-auth-provider)
36−* [Facebook](#facebook-auth-provider)
40+- [Facebook](#facebook-auth-provider)
37−* [GitHub](#github-auth-provider)
41+- [GitHub](#github-auth-provider)
38−* [GitLab](#gitlab-auth-provider)
42+- [GitLab](#gitlab-auth-provider)
39−* [LinkedIn](#linkedin-auth-provider)
43+- [LinkedIn](#linkedin-auth-provider)
41The provider can be selected using the `provider` configuration value.
45The provider can be selected using the `provider` configuration value.
@@ -44,61 +48,62 @@ The provider can be selected using the `provider` configuration value.
45For Google, the registration steps are:
49For Google, the registration steps are:
47−1. Create a new project: https://console.developers.google.com/project
51+1. Create a new project: https://console.developers.google.com/project
48−2. Choose the new project from the top right project dropdown (only if another project is selected)
52+2. Choose the new project from the top right project dropdown (only if another project is selected)
49−3. In the project Dashboard center pane, choose **"API Manager"**
53+3. In the project Dashboard center pane, choose **"API Manager"**
50−4. In the left Nav pane, choose **"Credentials"**
54+4. In the left Nav pane, choose **"Credentials"**
51−5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save.
55+5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save.
52−6. In the center pane, choose **"Credentials"** tab.
56+6. In the center pane, choose **"Credentials"** tab.
53− * Open the **"New credentials"** drop down
57+ - Open the **"New credentials"** drop down
54− * Choose **"OAuth client ID"**
58+ - Choose **"OAuth client ID"**
55− * Choose **"Web application"**
59+ - Choose **"Web application"**
56− * Application name is freeform, choose something appropriate
60+ - Application name is freeform, choose something appropriate
57− * Authorized JavaScript origins is your domain ex: `https://internal.yourcompany.com`
61+ - Authorized JavaScript origins is your domain ex: `https://internal.yourcompany.com`
58− * Authorized redirect URIs is the location of oauth2/callback ex: `https://internal.yourcompany.com/oauth2/callback`
62+ - Authorized redirect URIs is the location of oauth2/callback ex: `https://internal.yourcompany.com/oauth2/callback`
59− * Choose **"Create"**
63+ - Choose **"Create"**
60−4. Take note of the **Client ID** and **Client Secret**
64+7. Take note of the **Client ID** and **Client Secret**
62It's recommended to refresh sessions on a short interval (1h) with `cookie-refresh` setting which validates that the account is still authorized.
66It's recommended to refresh sessions on a short interval (1h) with `cookie-refresh` setting which validates that the account is still authorized.
64#### Restrict auth to specific Google groups on your domain. (optional)
68#### Restrict auth to specific Google groups on your domain. (optional)
66−1. Create a service account: https://developers.google.com/identity/protocols/OAuth2ServiceAccount and make sure to download the json file.
70+1. Create a service account: https://developers.google.com/identity/protocols/OAuth2ServiceAccount and make sure to download the json file.
67−2. Make note of the Client ID for a future step.
71+2. Make note of the Client ID for a future step.
68−3. Under "APIs & Auth", choose APIs.
72+3. Under "APIs & Auth", choose APIs.
69−4. Click on Admin SDK and then Enable API.
73+4. Click on Admin SDK and then Enable API.
70−5. Follow the steps on https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account and give the client id from step 2 the following oauth scopes:
74+5. Follow the steps on https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account and give the client id from step 2 the following oauth scopes:
72https://www.googleapis.com/auth/admin.directory.group.readonly
77https://www.googleapis.com/auth/admin.directory.group.readonly
73https://www.googleapis.com/auth/admin.directory.user.readonly
78https://www.googleapis.com/auth/admin.directory.user.readonly
75−6. Follow the steps on https://support.google.com/a/answer/60757 to enable Admin API access.
81+6. Follow the steps on https://support.google.com/a/answer/60757 to enable Admin API access.
76−7. Create or choose an existing administrative email address on the Gmail domain to assign to the ```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.
82+7. Create or choose an existing administrative email address on the Gmail domain to assign to the `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.
77−8. Create or choose an existing email group and set that email to the ```google-group``` flag. You can pass multiple instances of this flag with different groups
83+8. Create or choose an existing email group and set that email to the `google-group` flag. You can pass multiple instances of this flag with different groups
78−and the user will be checked against all the provided groups.
84+ and the user will be checked against all the provided groups.
79−9. Lock down the permissions on the json file downloaded from step 1 so only oauth2_proxy is able to read the file and set the path to the file in the ```google-service-account-json``` flag.
85+9. Lock down the permissions on the json file downloaded from step 1 so only oauth2_proxy is able to read the file and set the path to the file in the `google-service-account-json` flag.
8010. Restart oauth2_proxy.
8610. Restart oauth2_proxy.
82Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).
88Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).
84### Azure Auth Provider
90### Azure Auth Provider
86−1. [Add an application](https://azure.microsoft.com/en-us/documentation/articles/active-directory-integrating-applications/) to your Azure Active Directory tenant.
92+1. [Add an application](https://azure.microsoft.com/en-us/documentation/articles/active-directory-integrating-applications/) to your Azure Active Directory tenant.
87−2. On the App properties page provide the correct Sign-On URL ie `https://internal.yourcompany.com/oauth2/callback`
93+2. On the App properties page provide the correct Sign-On URL ie `https://internal.yourcompany.com/oauth2/callback`
88−3. If applicable take note of your `TenantID` and provide it via the `--azure-tenant=<YOUR TENANT ID>` commandline option. Default the `common` tenant is used.
94+3. If applicable take note of your `TenantID` and provide it via the `--azure-tenant=<YOUR TENANT ID>` commandline option. Default the `common` tenant is used.
90The 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.
96The 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.
93### Facebook Auth Provider
98### Facebook Auth Provider
95−1. Create a new FB App from <https://developers.facebook.com/>
100+1. Create a new FB App from <https://developers.facebook.com/>
96−2. Under FB Login, set your Valid OAuth redirect URIs to `https://internal.yourcompany.com/oauth2/callback`
101+2. Under FB Login, set your Valid OAuth redirect URIs to `https://internal.yourcompany.com/oauth2/callback`
98### GitHub Auth Provider
103### GitHub Auth Provider
100−1. Create a new project: https://github.com/settings/developers
105+1. Create a new project: https://github.com/settings/developers
101−2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback`
106+2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback`
103The 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=*`
108The 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=*`
@@ -121,17 +126,16 @@ If you are using self-hosted GitLab, make sure you set the following to the appr
121 -redeem-url="<your gitlab url>/oauth/token"
126 -redeem-url="<your gitlab url>/oauth/token"
122 -validate-url="<your gitlab url>/api/v4/user"
127 -validate-url="<your gitlab url>/api/v4/user"
125### LinkedIn Auth Provider
129### LinkedIn Auth Provider
127For LinkedIn, the registration steps are:
131For LinkedIn, the registration steps are:
129−1. Create a new project: https://www.linkedin.com/secure/developer
133+1. Create a new project: https://www.linkedin.com/secure/developer
130−2. In the OAuth User Agreement section:
134+2. In the OAuth User Agreement section:
131− * In default scope, select r_basicprofile and r_emailaddress.
135+ - In default scope, select r_basicprofile and r_emailaddress.
132− * In "OAuth 2.0 Redirect URLs", enter `https://internal.yourcompany.com/oauth2/callback`
136+ - In "OAuth 2.0 Redirect URLs", enter `https://internal.yourcompany.com/oauth2/callback`
133−3. Fill in the remaining required fields and Save.
137+3. Fill in the remaining required fields and Save.
134−4. Take note of the **Consumer Key / API Key** and **Consumer Secret / Secret Key**
138+4. Take note of the **Consumer Key / API Key** and **Consumer Secret / Secret Key**
136### Microsoft Azure AD Provider
140### Microsoft Azure AD Provider
@@ -143,9 +147,9 @@ Take note of your `TenantId` if applicable for your situation. The `TenantId` ca
144OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects. This provider was originally built against CoreOS Dex and we will use it as an example.
148OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects. This provider was originally built against CoreOS Dex and we will use it as an example.
146−1. Launch a Dex instance using the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md).
150+1. Launch a Dex instance using the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md).
147−2. Setup oauth2_proxy with the correct provider and using the default ports and callbacks.
151+2. Setup oauth2_proxy with the correct provider and using the default ports and callbacks.
148−3. Login with the fixture use in the dex guide and run the oauth2_proxy with the following args:
152+3. Login with the fixture use in the dex guide and run the oauth2_proxy with the following args:
150 -provider oidc
154 -provider oidc
151 -client-id oauth2_proxy
155 -client-id oauth2_proxy
@@ -253,7 +257,7 @@ The following environment variables can be used in place of the corresponding co
254There are two recommended configurations.
258There are two recommended configurations.
256−1) Configure SSL Termination with OAuth2 Proxy by providing a `--tls-cert=/path/to/cert.pem` and `--tls-key=/path/to/cert.key`.
260+1. Configure SSL Termination with OAuth2 Proxy by providing a `--tls-cert=/path/to/cert.pem` and `--tls-key=/path/to/cert.key`.
258The command line to run `oauth2_proxy` in this configuration would look like this:
262The command line to run `oauth2_proxy` in this configuration would look like this:
@@ -270,8 +274,7 @@ The command line to run `oauth2_proxy` in this configuration would look like thi
270 --client-secret=...
274 --client-secret=...
274−2) Configure SSL Termination with [Nginx](http://nginx.org/) (example config below), Amazon ELB, Google Cloud Platform Load Balancing, or ....
277+2. Configure SSL Termination with [Nginx](http://nginx.org/) (example config below), Amazon ELB, Google Cloud Platform Load Balancing, or ....
276Because `oauth2_proxy` listens on `127.0.0.1:4180` by default, to listen on all interfaces (needed when using an
279Because `oauth2_proxy` listens on `127.0.0.1:4180` by default, to listen on all interfaces (needed when using an
277external load balancer like Amazon ELB or Google Platform Load Balancing) use `--http-address="0.0.0.0:4180"` or
280external load balancer like Amazon ELB or Google Platform Load Balancing) use `--http-address="0.0.0.0:4180"` or
@@ -321,12 +324,12 @@ The command line to run `oauth2_proxy` in this configuration would look like thi
322OAuth2 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.
325OAuth2 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.
324−* /robots.txt - returns a 200 OK response that disallows all User-agents from all paths; see [robotstxt.org](http://www.robotstxt.org/) for more info
327+- /robots.txt - returns a 200 OK response that disallows all User-agents from all paths; see [robotstxt.org](http://www.robotstxt.org/) for more info
325−* /ping - returns an 200 OK response
328+- /ping - returns an 200 OK response
326−* /oauth2/sign_in - the login page, which also doubles as a sign out page (it clears cookies)
329+- /oauth2/sign_in - the login page, which also doubles as a sign out page (it clears cookies)
327−* /oauth2/start - a URL that will redirect to start the OAuth cycle
330+- /oauth2/start - a URL that will redirect to start the OAuth cycle
328−* /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
331+- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
329−* /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](#nginx-auth-request)
332+- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](#nginx-auth-request)
331## Request signatures
334## Request signatures
@@ -341,9 +344,9 @@ in `oauthproxy.go`](./oauthproxy.go).
341For more information about HMAC request signature validation, read the
344For more information about HMAC request signature validation, read the
342following:
345following:
344−* [Amazon Web Services: Signing and Authenticating REST
347+- [Amazon Web Services: Signing and Authenticating REST
345 Requests](https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html)
348 Requests](https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html)
346−* [rc3.org: Using HMAC to authenticate Web service
349+- [rc3.org: Using HMAC to authenticate Web service
347 requests](http://rc3.org/2011/12/02/using-hmac-to-authenticate-web-service-requests/)
350 requests](http://rc3.org/2011/12/02/using-hmac-to-authenticate-web-service-requests/)
349## Logging Format
352## Logging Format