@@ -0,0 +1,456 @@
3+title: OAuth Provider Configuration
6+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.
10+- [Google](#google-auth-provider) _default_
11+- [Azure](#azure-auth-provider)
12+- [Facebook](#facebook-auth-provider)
13+- [GitHub](#github-auth-provider)
14+- [Keycloak](#keycloak-auth-provider)
15+- [GitLab](#gitlab-auth-provider)
16+- [LinkedIn](#linkedin-auth-provider)
17+- [Microsoft Azure AD](#microsoft-azure-ad-provider)
18+- [OpenID Connect](#openid-connect-provider)
19+- [login.gov](#logingov-provider)
20+- [Nextcloud](#nextcloud-provider)
21+- [DigitalOcean](#digitalocean-auth-provider)
22+- [Bitbucket](#bitbucket-auth-provider)
23+- [Gitea](#gitea-auth-provider)
25+The provider can be selected using the `provider` configuration value.
27+Please note that not all providers support all claims. The `preferred_username` claim is currently only supported by the OpenID Connect provider.
29+### Google Auth Provider
31+For Google, the registration steps are:
33+1. Create a new project: https://console.developers.google.com/project
34+2. Choose the new project from the top right project dropdown (only if another project is selected)
35+3. In the project Dashboard center pane, choose **"API Manager"**
36+4. In the left Nav pane, choose **"Credentials"**
37+5. In the center pane, choose **"OAuth consent screen"** tab. Fill in **"Product name shown to users"** and hit save.
38+6. In the center pane, choose **"Credentials"** tab.
39+ - Open the **"New credentials"** drop down
40+ - Choose **"OAuth client ID"**
41+ - Choose **"Web application"**
42+ - Application name is freeform, choose something appropriate
43+ - Authorized JavaScript origins is your domain ex: `https://internal.yourcompany.com`
44+ - Authorized redirect URIs is the location of oauth2/callback ex: `https://internal.yourcompany.com/oauth2/callback`
45+ - Choose **"Create"**
46+7. Take note of the **Client ID** and **Client Secret**
48+It's recommended to refresh sessions on a short interval (1h) with `cookie-refresh` setting which validates that the account is still authorized.
50+#### Restrict auth to specific Google groups on your domain. (optional)
52+1. Create a service account: https://developers.google.com/identity/protocols/OAuth2ServiceAccount and make sure to download the json file.
53+2. Make note of the Client ID for a future step.
54+3. Under "APIs & Auth", choose APIs.
55+4. Click on Admin SDK and then Enable API.
56+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:
59+https://www.googleapis.com/auth/admin.directory.group.readonly
60+https://www.googleapis.com/auth/admin.directory.user.readonly
63+6. Follow the steps on https://support.google.com/a/answer/60757 to enable Admin API access.
64+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.
65+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
66+ and the user will be checked against all the provided groups.
67+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.
68+10. Restart oauth2-proxy.
70+Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).
72+### Azure Auth Provider
74+1. Add an application: go to [https://portal.azure.com](https://portal.azure.com), choose **"Azure Active Directory"** in the left menu, select **"App registrations"** and then click on **"New app registration"**.
75+2. Pick a name and choose **"Webapp / API"** as application type. Use `https://internal.yourcompany.com` as Sign-on URL. Click **"Create"**.
76+3. On the **"Settings"** / **"Properties"** page of the app, pick a logo and select **"Multi-tenanted"** if you want to allow users from multiple organizations to access your app. Note down the application ID. Click **"Save"**.
77+4. On the **"Settings"** / **"Required Permissions"** page of the app, click on **"Windows Azure Active Directory"** and then on **"Access the directory as the signed in user"**. Hit **"Save"** and then then on **"Grant permissions"** (you might need another admin to do this).
78+5. On the **"Settings"** / **"Reply URLs"** page of the app, add `https://internal.yourcompanycom/oauth2/callback` for each host that you want to protect by the oauth2 proxy. Click **"Save"**.
79+6. On the **"Settings"** / **"Keys"** page of the app, add a new key and note down the value after hitting **"Save"**.
80+7. Configure the proxy with
84+ --client-id=<application ID from step 3>
85+ --client-secret=<value from step 6>
88+Note: When using the Azure Auth provider with nginx and the cookie session store you may find the cookie is too large and doesn't get passed through correctly. Increasing the proxy_buffer_size in nginx or implementing the [redis session storage](sessions.md#redis-storage) should resolve this.
90+### Facebook Auth Provider
92+1. Create a new FB App from <https://developers.facebook.com/>
93+2. Under FB Login, set your Valid OAuth redirect URIs to `https://internal.yourcompany.com/oauth2/callback`
95+### GitHub Auth Provider
97+1. Create a new project: https://github.com/settings/developers
98+2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback`
100+The GitHub auth provider supports two additional ways to restrict authentication to either organization and optional team level access, or to collaborators of a repository. Restricting by these options is normally accompanied with `--email-domain=*`
102+NOTE: When `--github-user` is set, the specified users are allowed to login even if they do not belong to the specified org and team or collaborators.
104+To restrict by organization only, include the following flag:
106+ -github-org="": restrict logins to members of this organisation
108+To restrict within an organization to specific teams, include the following flag in addition to `-github-org`:
110+ -github-team="": restrict logins to members of any of these teams (slug), separated by a comma
112+If you would rather restrict access to collaborators of a repository, those users must either have push access to a public repository or any access to a private repository:
114+ -github-repo="": restrict logins to collaborators of this repository formatted as orgname/repo
116+If you'd like to allow access to users with **read only** access to a **public** repository you will need to provide a [token](https://github.com/settings/tokens) for a user that has write access to the repository. The token must be created with at least the `public_repo` scope:
118+ -github-token="": the token to use when verifying repository collaborators
120+To allow a user to login with their username even if they do not belong to the specified org and team or collaborators, separated by a comma
122+ -github-user="": allow logins by username, separated by a comma
124+If you are using GitHub enterprise, make sure you set the following to the appropriate url:
126+ -login-url="http(s)://<enterprise github host>/login/oauth/authorize"
127+ -redeem-url="http(s)://<enterprise github host>/login/oauth/access_token"
128+ -validate-url="http(s)://<enterprise github host>/api/v3"
130+### Keycloak Auth Provider
132+1. Create new client in your Keycloak with **Access Type** 'confidental' and **Valid Redirect URIs** 'https://internal.yourcompany.com/oauth2/callback'
133+2. Take note of the Secret in the credential tab of the client
134+3. Create a mapper with **Mapper Type** 'Group Membership' and **Token Claim Name** 'groups'.
136+Make sure you set the following to the appropriate url:
139+ -client-id=<client you have created>
140+ -client-secret=<your client's secret>
141+ -login-url="http(s)://<keycloak host>/realms/<your realm>/protocol/openid-connect/auth"
142+ -redeem-url="http(s)://<keycloak host>/realms/<your realm>/protocol/openid-connect/token"
143+ -validate-url="http(s)://<keycloak host>/realms/<your realm>/protocol/openid-connect/userinfo"
144+ -keycloak-group=<user_group>
146+The group management in keycloak is using a tree. If you create a group named admin in keycloak you should define the 'keycloak-group' value to /admin.
148+### GitLab Auth Provider
150+Whether you are using GitLab.com or self-hosting GitLab, follow [these steps to add an application](https://docs.gitlab.com/ce/integration/oauth_provider.html). Make sure to enable at least the `openid`, `profile` and `email` scopes, and set the redirect url to your application url e.g. https://myapp.com/oauth2/callback.
152+The following config should be set to ensure that the oauth will work properly. To get a cookie secret follow [these steps](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/docs/configuration/configuration.md#configuration)
156+ --redirect-url="https://myapp.com/oauth2/callback" // Should be the same as the redirect url for the application in gitlab
157+ --client-id=GITLAB_CLIENT_ID
158+ --client-secret=GITLAB_CLIENT_SECRET
159+ --cookie-secret=COOKIE_SECRET
162+Restricting by group membership is possible with the following option:
164+ --gitlab-group="mygroup,myothergroup": restrict logins to members of any of these groups (slug), separated by a comma
166+If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:
168+ --oidc-issuer-url="<your gitlab url>"
170+### LinkedIn Auth Provider
172+For LinkedIn, the registration steps are:
174+1. Create a new project: https://www.linkedin.com/secure/developer
175+2. In the OAuth User Agreement section:
176+ - In default scope, select r_basicprofile and r_emailaddress.
177+ - In "OAuth 2.0 Redirect URLs", enter `https://internal.yourcompany.com/oauth2/callback`
178+3. Fill in the remaining required fields and Save.
179+4. Take note of the **Consumer Key / API Key** and **Consumer Secret / Secret Key**
181+### Microsoft Azure AD Provider
183+For adding an application to the Microsoft Azure AD follow [these steps to add an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).
185+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.
187+### OpenID Connect Provider
189+OpenID 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.
191+1. Launch a Dex instance using the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md).
192+2. Setup oauth2-proxy with the correct provider and using the default ports and callbacks.
193+3. Login with the fixture use in the dex guide and run the oauth2-proxy with the following args:
197+ -provider-display-name "My OIDC Provider"
198+ -client-id oauth2-proxy
199+ -client-secret proxy
200+ -redirect-url http://127.0.0.1:4180/oauth2/callback
201+ -oidc-issuer-url http://127.0.0.1:5556
202+ -cookie-secure=false
203+ -email-domain example.com
206+The OpenID Connect Provider (OIDC) can also be used to connect to other Identity Providers such as Okta. To configure the OIDC provider for Okta, perform
209+#### Configuring the OIDC Provider with Okta
211+1. Log in to Okta using an administrative account. It is suggested you try this in preview first, `example.oktapreview.com`
212+2. (OPTIONAL) If you want to configure authorization scopes and claims to be passed on to multiple applications,
213+you may wish to configure an authorization server for each application. Otherwise, the provided `default` will work.
214+* Navigate to **Security** then select **API**
215+* Click **Add Authorization Server**, if this option is not available you may require an additional license for a custom authorization server.
216+* Fill out the **Name** with something to describe the application you are protecting. e.g. 'Example App'.
217+* For **Audience**, pick the URL of the application you wish to protect: https://example.corp.com
218+* Fill out a **Description**
219+* Add any **Access Policies** you wish to configure to limit application access.
220+* The default settings will work for other options.
221+[See Okta documentation for more information on Authorization Servers](https://developer.okta.com/docs/guides/customize-authz-server/overview/)
222+3. Navigate to **Applications** then select **Add Application**.
223+* Select **Web** for the **Platform** setting.
224+* Select **OpenID Connect** and click **Create**
225+* Pick an **Application Name** such as `Example App`.
226+* Set the **Login redirect URI** to `https://example.corp.com`.
227+* Under **General** set the **Allowed grant types** to `Authorization Code` and `Refresh Token`.
228+* Leave the rest as default, taking note of the `Client ID` and `Client Secret`.
229+* Under **Assignments** select the users or groups you wish to access your application.
230+4. Create a configuration file like the following:
234+redirect_url = "https://example.corp.com/oauth2/callback"
235+oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"
237+ "https://example.corp.com"
243+client_secret = "YYYYY"
244+pass_access_token = true
245+cookie_secret = "ZZZZZ"
246+skip_provider_button = true
249+The `oidc_issuer_url` is based on URL from your **Authorization Server**'s **Issuer** field in step 2, or simply https://corp.okta.com
250+The `client_id` and `client_secret` are configured in the application settings.
251+Generate a unique `client_secret` to encrypt the cookie.
253+Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.cfg`
255+#### Configuring the OIDC Provider with Okta - localhost
256+1. Signup for developer account: https://developer.okta.com/signup/
257+2. Create New `Web` Application: https://${your-okta-domain}/dev/console/apps/new
258+3. Example Application Settings for localhost:
259+ * **Name:** My Web App
260+ * **Base URIs:** http://localhost:4180/
261+ * **Login redirect URIs:** http://localhost:4180/oauth2/callback
262+ * **Logout redirect URIs:** http://localhost:4180/
263+ * **Group assignments:** `Everyone`
264+ * **Grant type allowed:** `Authorization Code` and `Refresh Token`
265+4. Make note of the `Client ID` and `Client secret`, they are needed in a future step
266+5. Make note of the **default** Authorization Server Issuer URI from: https://${your-okta-domain}/admin/oauth2/as
267+6. Example config file `/etc/localhost.cfg`
270+ redirect_url = "http://localhost:4180/oauth2/callback"
271+ oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"
273+ "http://0.0.0.0:8080"
279+ client_secret = "YYY"
280+ pass_access_token = true
281+ cookie_secret = "ZZZ"
282+ cookie_secure = false
283+ skip_provider_button = true
284+ # Note: use the following for testing within a container
285+ # http_address = "0.0.0.0:4180"
287+7. Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/localhost.cfg`
289+### login.gov Provider
291+login.gov is an OIDC provider for the US Government.
292+If you are a US Government agency, you can contact the login.gov team through the contact information
293+that you can find on https://login.gov/developers/ and work with them to understand how to get login.gov
294+accounts for integration/test and production access.
296+A developer guide is available here: https://developers.login.gov/, though this proxy handles everything
297+but the data you need to create to register your application in the login.gov dashboard.
299+As a demo, we will assume that you are running your application that you want to secure locally on
300+http://localhost:3000/, that you will be starting your proxy up on http://localhost:4180/, and that
301+you have an agency integration account for testing.
303+First, register your application in the dashboard. The important bits are:
304+ * Identity protocol: make this `Openid connect`
305+ * Issuer: do what they say for OpenID Connect. We will refer to this string as `${LOGINGOV_ISSUER}`.
306+ * Public key: This is a self-signed certificate in .pem format generated from a 2048 bit RSA private key.
307+ A quick way to do this is `openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -nodes -subj '/C=US/ST=Washington/L=DC/O=GSA/OU=18F/CN=localhost'`,
308+ The contents of the `key.pem` shall be referred to as `${OAUTH2_PROXY_JWT_KEY}`.
309+ * Return to App URL: Make this be `http://localhost:4180/`
310+ * Redirect URIs: Make this be `http://localhost:4180/oauth2/callback`.
311+ * Attribute Bundle: Make sure that email is selected.
313+Now start the proxy up with the following options:
315+./oauth2-proxy -provider login.gov \
316+ -client-id=${LOGINGOV_ISSUER} \
317+ -redirect-url=http://localhost:4180/oauth2/callback \
318+ -oidc-issuer-url=https://idp.int.identitysandbox.gov/ \
319+ -cookie-secure=false \
320+ -email-domain=gsa.gov \
321+ -upstream=http://localhost:3000/ \
322+ -cookie-secret=somerandomstring12341234567890AB \
323+ -cookie-domain=localhost \
324+ -skip-provider-button=true \
325+ -pubjwk-url=https://idp.int.identitysandbox.gov/api/openid_connect/certs \
326+ -profile-url=https://idp.int.identitysandbox.gov/api/openid_connect/userinfo \
327+ -jwt-key="${OAUTH2_PROXY_JWT_KEY}"
329+You can also set all these options with environment variables, for use in cloud/docker environments.
330+One tricky thing that you may encounter is that some cloud environments will pass in environment
331+variables in a docker env-file, which does not allow multiline variables like a PEM file.
332+If you encounter this, then you can create a `jwt_signing_key.pem` file in the top level
333+directory of the repo which contains the key in PEM format and then do your docker build.
334+The docker build process will copy that file into your image which you can then access by
335+setting the `OAUTH2_PROXY_JWT_KEY_FILE=/etc/ssl/private/jwt_signing_key.pem`
336+environment variable, or by setting `--jwt-key-file=/etc/ssl/private/jwt_signing_key.pem` on the commandline.
338+Once it is running, you should be able to go to `http://localhost:4180/` in your browser,
339+get authenticated by the login.gov integration server, and then get proxied on to your
340+application running on `http://localhost:3000/`. In a real deployment, you would secure
341+your application with a firewall or something so that it was only accessible from the
342+proxy, and you would use real hostnames everywhere.
344+#### Skip OIDC discovery
346+Some providers do not support OIDC discovery via their issuer URL, so oauth2-proxy cannot simply grab the authorization, token and jwks URI endpoints from the provider's metadata.
348+In this case, you can set the `--skip-oidc-discovery` option, and supply those required endpoints manually:
352+ -client-id oauth2-proxy
353+ -client-secret proxy
354+ -redirect-url http://127.0.0.1:4180/oauth2/callback
355+ -oidc-issuer-url http://127.0.0.1:5556
356+ -skip-oidc-discovery
357+ -login-url http://127.0.0.1:5556/authorize
358+ -redeem-url http://127.0.0.1:5556/token
359+ -oidc-jwks-url http://127.0.0.1:5556/keys
360+ -cookie-secure=false
361+ -email-domain example.com
364+### Nextcloud Provider
366+The Nextcloud provider allows you to authenticate against users in your
369+When you are using the Nextcloud provider, you must specify the urls via
370+configuration, environment variable, or command line argument. Depending
371+on whether your Nextcloud instance is using pretty urls your urls may be of the
372+form `/index.php/apps/oauth2/*` or `/apps/oauth2/*`.
375+documentation](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/oauth2.html)
376+to setup the client id and client secret. Your "Redirection URI" will be
377+`https://internalapp.yourcompany.com/oauth2/callback`.
381+ -client-id <from nextcloud admin>
382+ -client-secret <from nextcloud admin>
383+ -login-url="<your nextcloud url>/index.php/apps/oauth2/authorize"
384+ -redeem-url="<your nextcloud url>/index.php/apps/oauth2/api/v1/token"
385+ -validate-url="<your nextcloud url>/ocs/v2.php/cloud/user?format=json"
388+Note: in *all* cases the validate-url will *not* have the `index.php`.
390+### DigitalOcean Auth Provider
392+1. [Create a new OAuth application](https://cloud.digitalocean.com/account/api/applications)
393+ * You can fill in the name, homepage, and description however you wish.
394+ * In the "Application callback URL" field, enter: `https://oauth-proxy/oauth2/callback`, substituting `oauth2-proxy` with the actual hostname that oauth2-proxy is running on. The URL must match oauth2-proxy's configured redirect URL.
395+2. Note the Client ID and Client Secret.
397+To use the provider, pass the following options:
400+ --provider=digitalocean
401+ --client-id=<Client ID>
402+ --client-secret=<Client Secret>
405+ Alternatively, set the equivalent options in the config file. The redirect URL defaults to `https://<requested host header>/oauth2/callback`. If you need to change it, you can use the `--redirect-url` command-line option.
407+### Bitbucket Auth Provider
409+1. [Add a new OAuth consumer](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html)
410+ * In "Callback URL" use `https://<oauth2-proxy>/oauth2/callback`, substituting `<oauth2-proxy>` with the actual hostname that oauth2-proxy is running on.
411+ * In Permissions section select:
413+ * Team membership -> Read
414+ * Repositories -> Read
415+2. Note the Client ID and Client Secret.
417+To use the provider, pass the following options:
420+ --provider=bitbucket
421+ --client-id=<Client ID>
422+ --client-secret=<Client Secret>
425+The default configuration allows everyone with Bitbucket account to authenticate. To restrict the access to the team members use additional configuration option: `--bitbucket-team=<Team name>`. To restrict the access to only these users who has access to one selected repository use `--bitbucket-repository=<Repository name>`.
428+### Gitea Auth Provider
430+1. Create a new application: `https://< your gitea host >/user/settings/applications`
431+2. Under `Redirect URI` enter the correct URL i.e. `https://<proxied host>/oauth2/callback`
432+3. Note the Client ID and Client Secret.
433+4. Pass the following options to the proxy:
437+ --redirect-url="https://<proxied host>/oauth2/callback"
438+ --provider-display-name="Gitea"
439+ --client-id="< client_id as generated by Gitea >"
440+ --client-secret="< client_secret as generated by Gitea >"
441+ --login-url="https://< your gitea host >/login/oauth/authorize"
442+ --redeem-url="https://< your gitea host >/login/oauth/access_token"
443+ --validate-url="https://< your gitea host >/api/v1"
447+## Email Authentication
449+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=*`.
451+## Adding a new Provider
453+Follow the examples in the [`providers` package](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/) to define a new
454+`Provider` instance. Add a new `case` to
455+[`providers.New()`](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/providers.go) to allow `oauth2-proxy` to use the