@@ -0,0 +1,510 @@
1+---
2+id: oauth_provider
3+title: OAuth Provider Configuration
4+---
5+
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.
7+
8+Valid providers are :
9+
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)
24+
25+The provider can be selected using the `provider` configuration value.
26+
27+Please note that not all providers support all claims. The `preferred_username` claim is currently only supported by the OpenID Connect provider.
28+
29+### Google Auth Provider
30+
31+For Google, the registration steps are:
32+
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**
47+
48+It's recommended to refresh sessions on a short interval (1h) with `cookie-refresh` setting which validates that the account is still authorized.
49+
50+#### Restrict auth to specific Google groups on your domain. (optional)
51+
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:
57+
58+```
59+https://www.googleapis.com/auth/admin.directory.group.readonly
60+https://www.googleapis.com/auth/admin.directory.user.readonly
61+```
62+
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.
69+
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 ).
71+
72+### Azure Auth Provider
73+
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
81+
82+```
83+ --provider=azure
84+ --client-id=<application ID from step 3>
85+ --client-secret=<value from step 6>
86+```
87+
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.
89+
90+### Facebook Auth Provider
91+
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`
94+
95+### GitHub Auth Provider
96+
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`
99+
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=*`
101+
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.
103+
104+To restrict by organization only, include the following flag:
105+
106+ -github-org="": restrict logins to members of this organisation
107+
108+To restrict within an organization to specific teams, include the following flag in addition to `-github-org`:
109+
110+ -github-team="": restrict logins to members of any of these teams (slug), separated by a comma
111+
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:
113+
114+ -github-repo="": restrict logins to collaborators of this repository formatted as orgname/repo
115+
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:
117+
118+ -github-token="": the token to use when verifying repository collaborators
119+
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
121+
122+ -github-user="": allow logins by username, separated by a comma
123+
124+If you are using GitHub enterprise, make sure you set the following to the appropriate url:
125+
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"
129+
130+### Keycloak Auth Provider
131+
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'.
135+
136+Make sure you set the following to the appropriate url:
137+
138+ --provider=keycloak
139+ --client-id=<client you have created>
140+ --client-secret=<your client's secret>
141+ --login-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/auth"
142+ --redeem-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/token"
143+ --profile-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/userinfo"
144+ --validate-url="http(s)://<keycloak host>/auth/realms/<your realm>/protocol/openid-connect/userinfo"
145+ --keycloak-group=<first_allowed_user_group>
146+ --keycloak-group=<second_allowed_user_group>
147+
148+For group based authorization, the optional `--keycloak-group` (legacy) or `--allowed-group` (global standard)
149+flags can be used to specify which groups to limit access to.
150+
151+If these are unset but a `groups` mapper is set up above in step (3), the provider will still
152+populate the `X-Forwarded-Groups` header to your upstream server with the `groups` data in the
153+Keycloak userinfo endpoint response.
154+
155+The group management in keycloak is using a tree. If you create a group named admin in keycloak
156+you should define the 'keycloak-group' value to /admin.
157+
158+### GitLab Auth Provider
159+
160+This auth provider has been tested against Gitlab version 12.X. Due to Gitlab API changes, it may not work for version prior to 12.X (see [994](https://github.com/oauth2-proxy/oauth2-proxy/issues/994)).
161+
162+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.
163+
164+If you need projects filtering, add the extra `read_api` scope to your application.
165+
166+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)
167+
168+```
169+ --provider="gitlab"
170+ --redirect-url="https://myapp.com/oauth2/callback" // Should be the same as the redirect url for the application in gitlab
171+ --client-id=GITLAB_CLIENT_ID
172+ --client-secret=GITLAB_CLIENT_SECRET
173+ --cookie-secret=COOKIE_SECRET
174+```
175+
176+Restricting by group membership is possible with the following option:
177+
178+ --gitlab-group="mygroup,myothergroup": restrict logins to members of any of these groups (slug), separated by a comma
179+
180+If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:
181+
182+ --oidc-issuer-url="<your gitlab url>"
183+
184+### LinkedIn Auth Provider
185+
186+For LinkedIn, the registration steps are:
187+
188+1. Create a new project: https://www.linkedin.com/secure/developer
189+2. In the OAuth User Agreement section:
190+ - In default scope, select r_basicprofile and r_emailaddress.
191+ - In "OAuth 2.0 Redirect URLs", enter `https://internal.yourcompany.com/oauth2/callback`
192+3. Fill in the remaining required fields and Save.
193+4. Take note of the **Consumer Key / API Key** and **Consumer Secret / Secret Key**
194+
195+### Microsoft Azure AD Provider
196+
197+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).
198+
199+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.
200+
201+### OpenID Connect Provider
202+
203+OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects.
204+
205+This provider was originally built against CoreOS Dex and we will use it as an example.
206+The OpenID Connect Provider (OIDC) can also be used to connect to other Identity Providers such as Okta, an example can be found below.
207+
208+#### Dex
209+
210+To configure the OIDC provider for Dex, perform the following steps:
211+
212+1. Download Dex:
213+
214+ ```
215+ go get github.com/dexidp/dex
216+ ```
217+
218+ See the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md) for more details.
219+
220+2. Setup oauth2-proxy with the correct provider and using the default ports and callbacks. Add a configuration block to the `staticClients` section of `examples/config-dev.yaml`:
221+
222+ ```
223+ - id: oauth2-proxy
224+ redirectURIs:
225+ - 'http://127.0.0.1:4180/oauth2/callback'
226+ name: 'oauth2-proxy'
227+ secret: proxy
228+ ```
229+
230+3. Launch Dex: from `$GOPATH/github.com/dexidp/dex`, run:
231+
232+ ```
233+ bin/dex serve examples/config-dev.yaml
234+ ```
235+
236+4. In a second terminal, run the oauth2-proxy with the following args:
237+
238+ ```
239+ -provider oidc
240+ -provider-display-name "My OIDC Provider"
241+ -client-id oauth2-proxy
242+ -client-secret proxy
243+ -redirect-url http://127.0.0.1:4180/oauth2/callback
244+ -oidc-issuer-url http://127.0.0.1:5556/dex
245+ -cookie-secure=false
246+ -cookie-secret=secret
247+ -email-domain kilgore.trout
248+ ```
249+
250+ To serve the current working directory as a web site under the `/static` endpoint, add:
251+
252+ ```
253+ -upstream file://$PWD/#/static/
254+ ```
255+
256+5. Test the setup by visiting http://127.0.0.1:4180 or http://127.0.0.1:4180/static .
257+
258+See also [our local testing environment](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/local-environment) for a self-contained example using Docker and etcd as storage for Dex.
259+
260+#### Okta
261+
262+To configure the OIDC provider for Okta, perform the following steps:
263+
264+1. Log in to Okta using an administrative account. It is suggested you try this in preview first, `example.oktapreview.com`
265+2. (OPTIONAL) If you want to configure authorization scopes and claims to be passed on to multiple applications,
266+you may wish to configure an authorization server for each application. Otherwise, the provided `default` will work.
267+* Navigate to **Security** then select **API**
268+* Click **Add Authorization Server**, if this option is not available you may require an additional license for a custom authorization server.
269+* Fill out the **Name** with something to describe the application you are protecting. e.g. 'Example App'.
270+* For **Audience**, pick the URL of the application you wish to protect: https://example.corp.com
271+* Fill out a **Description**
272+* Add any **Access Policies** you wish to configure to limit application access.
273+* The default settings will work for other options.
274+[See Okta documentation for more information on Authorization Servers](https://developer.okta.com/docs/guides/customize-authz-server/overview/)
275+3. Navigate to **Applications** then select **Add Application**.
276+* Select **Web** for the **Platform** setting.
277+* Select **OpenID Connect** and click **Create**
278+* Pick an **Application Name** such as `Example App`.
279+* Set the **Login redirect URI** to `https://example.corp.com`.
280+* Under **General** set the **Allowed grant types** to `Authorization Code` and `Refresh Token`.
281+* Leave the rest as default, taking note of the `Client ID` and `Client Secret`.
282+* Under **Assignments** select the users or groups you wish to access your application.
283+4. Create a configuration file like the following:
284+
285+ ```
286+ provider = "oidc"
287+ redirect_url = "https://example.corp.com/oauth2/callback"
288+ oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"
289+ upstreams = [
290+ "https://example.corp.com"
291+ ]
292+ email_domains = [
293+ "corp.com"
294+ ]
295+ client_id = "XXXXX"
296+ client_secret = "YYYYY"
297+ pass_access_token = true
298+ cookie_secret = "ZZZZZ"
299+ skip_provider_button = true
300+ ```
301+
302+The `oidc_issuer_url` is based on URL from your **Authorization Server**'s **Issuer** field in step 2, or simply https://corp.okta.com .
303+The `client_id` and `client_secret` are configured in the application settings.
304+Generate a unique `client_secret` to encrypt the cookie.
305+
306+Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.cfg`
307+
308+#### Okta - localhost
309+
310+1. Signup for developer account: https://developer.okta.com/signup/
311+2. Create New `Web` Application: https://${your-okta-domain}/dev/console/apps/new
312+3. Example Application Settings for localhost:
313+ * **Name:** My Web App
314+ * **Base URIs:** http://localhost:4180/
315+ * **Login redirect URIs:** http://localhost:4180/oauth2/callback
316+ * **Logout redirect URIs:** http://localhost:4180/
317+ * **Group assignments:** `Everyone`
318+ * **Grant type allowed:** `Authorization Code` and `Refresh Token`
319+4. Make note of the `Client ID` and `Client secret`, they are needed in a future step
320+5. Make note of the **default** Authorization Server Issuer URI from: https://${your-okta-domain}/admin/oauth2/as
321+6. Example config file `/etc/localhost.cfg`
322+ ```
323+ provider = "oidc"
324+ redirect_url = "http://localhost:4180/oauth2/callback"
325+ oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"
326+ upstreams = [
327+ "http://0.0.0.0:8080"
328+ ]
329+ email_domains = [
330+ "*"
331+ ]
332+ client_id = "XXX"
333+ client_secret = "YYY"
334+ pass_access_token = true
335+ cookie_secret = "ZZZ"
336+ cookie_secure = false
337+ skip_provider_button = true
338+ # Note: use the following for testing within a container
339+ # http_address = "0.0.0.0:4180"
340+ ```
341+7. Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/localhost.cfg`
342+
343+### login.gov Provider
344+
345+login.gov is an OIDC provider for the US Government.
346+If you are a US Government agency, you can contact the login.gov team through the contact information
347+that you can find on https://login.gov/developers/ and work with them to understand how to get login.gov
348+accounts for integration/test and production access.
349+
350+A developer guide is available here: https://developers.login.gov/, though this proxy handles everything
351+but the data you need to create to register your application in the login.gov dashboard.
352+
353+As a demo, we will assume that you are running your application that you want to secure locally on
354+http://localhost:3000/, that you will be starting your proxy up on http://localhost:4180/, and that
355+you have an agency integration account for testing.
356+
357+First, register your application in the dashboard. The important bits are:
358+ * Identity protocol: make this `Openid connect`
359+ * Issuer: do what they say for OpenID Connect. We will refer to this string as `${LOGINGOV_ISSUER}`.
360+ * Public key: This is a self-signed certificate in .pem format generated from a 2048 bit RSA private key.
361+ 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'`,
362+ The contents of the `key.pem` shall be referred to as `${OAUTH2_PROXY_JWT_KEY}`.
363+ * Return to App URL: Make this be `http://localhost:4180/`
364+ * Redirect URIs: Make this be `http://localhost:4180/oauth2/callback`.
365+ * Attribute Bundle: Make sure that email is selected.
366+
367+Now start the proxy up with the following options:
368+```
369+./oauth2-proxy -provider login.gov \
370+ -client-id=${LOGINGOV_ISSUER} \
371+ -redirect-url=http://localhost:4180/oauth2/callback \
372+ -oidc-issuer-url=https://idp.int.identitysandbox.gov/ \
373+ -cookie-secure=false \
374+ -email-domain=gsa.gov \
375+ -upstream=http://localhost:3000/ \
376+ -cookie-secret=somerandomstring12341234567890AB \
377+ -cookie-domain=localhost \
378+ -skip-provider-button=true \
379+ -pubjwk-url=https://idp.int.identitysandbox.gov/api/openid_connect/certs \
380+ -profile-url=https://idp.int.identitysandbox.gov/api/openid_connect/userinfo \
381+ -jwt-key="${OAUTH2_PROXY_JWT_KEY}"
382+```
383+You can also set all these options with environment variables, for use in cloud/docker environments.
384+One tricky thing that you may encounter is that some cloud environments will pass in environment
385+variables in a docker env-file, which does not allow multiline variables like a PEM file.
386+If you encounter this, then you can create a `jwt_signing_key.pem` file in the top level
387+directory of the repo which contains the key in PEM format and then do your docker build.
388+The docker build process will copy that file into your image which you can then access by
389+setting the `OAUTH2_PROXY_JWT_KEY_FILE=/etc/ssl/private/jwt_signing_key.pem`
390+environment variable, or by setting `--jwt-key-file=/etc/ssl/private/jwt_signing_key.pem` on the commandline.
391+
392+Once it is running, you should be able to go to `http://localhost:4180/` in your browser,
393+get authenticated by the login.gov integration server, and then get proxied on to your
394+application running on `http://localhost:3000/`. In a real deployment, you would secure
395+your application with a firewall or something so that it was only accessible from the
396+proxy, and you would use real hostnames everywhere.
397+
398+#### Skip OIDC discovery
399+
400+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.
401+
402+In this case, you can set the `--skip-oidc-discovery` option, and supply those required endpoints manually:
403+
404+```
405+ -provider oidc
406+ -client-id oauth2-proxy
407+ -client-secret proxy
408+ -redirect-url http://127.0.0.1:4180/oauth2/callback
409+ -oidc-issuer-url http://127.0.0.1:5556
410+ -skip-oidc-discovery
411+ -login-url http://127.0.0.1:5556/authorize
412+ -redeem-url http://127.0.0.1:5556/token
413+ -oidc-jwks-url http://127.0.0.1:5556/keys
414+ -cookie-secure=false
415+ -email-domain example.com
416+```
417+
418+### Nextcloud Provider
419+
420+The Nextcloud provider allows you to authenticate against users in your
421+Nextcloud instance.
422+
423+When you are using the Nextcloud provider, you must specify the urls via
424+configuration, environment variable, or command line argument. Depending
425+on whether your Nextcloud instance is using pretty urls your urls may be of the
426+form `/index.php/apps/oauth2/*` or `/apps/oauth2/*`.
427+
428+Refer to the [OAuth2
429+documentation](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/oauth2.html)
430+to setup the client id and client secret. Your "Redirection URI" will be
431+`https://internalapp.yourcompany.com/oauth2/callback`.
432+
433+```
434+ -provider nextcloud
435+ -client-id <from nextcloud admin>
436+ -client-secret <from nextcloud admin>
437+ -login-url="<your nextcloud url>/index.php/apps/oauth2/authorize"
438+ -redeem-url="<your nextcloud url>/index.php/apps/oauth2/api/v1/token"
439+ -validate-url="<your nextcloud url>/ocs/v2.php/cloud/user?format=json"
440+```
441+
442+Note: in *all* cases the validate-url will *not* have the `index.php`.
443+
444+### DigitalOcean Auth Provider
445+
446+1. [Create a new OAuth application](https://cloud.digitalocean.com/account/api/applications)
447+ * You can fill in the name, homepage, and description however you wish.
448+ * 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.
449+2. Note the Client ID and Client Secret.
450+
451+To use the provider, pass the following options:
452+
453+```
454+ --provider=digitalocean
455+ --client-id=<Client ID>
456+ --client-secret=<Client Secret>
457+```
458+
459+ 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.
460+
461+### Bitbucket Auth Provider
462+
463+1. [Add a new OAuth consumer](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html)
464+ * In "Callback URL" use `https://<oauth2-proxy>/oauth2/callback`, substituting `<oauth2-proxy>` with the actual hostname that oauth2-proxy is running on.
465+ * In Permissions section select:
466+ * Account -> Email
467+ * Team membership -> Read
468+ * Repositories -> Read
469+2. Note the Client ID and Client Secret.
470+
471+To use the provider, pass the following options:
472+
473+```
474+ --provider=bitbucket
475+ --client-id=<Client ID>
476+ --client-secret=<Client Secret>
477+```
478+
479+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>`.
480+
481+
482+### Gitea Auth Provider
483+
484+1. Create a new application: `https://< your gitea host >/user/settings/applications`
485+2. Under `Redirect URI` enter the correct URL i.e. `https://<proxied host>/oauth2/callback`
486+3. Note the Client ID and Client Secret.
487+4. Pass the following options to the proxy:
488+
489+```
490+ --provider="github"
491+ --redirect-url="https://<proxied host>/oauth2/callback"
492+ --provider-display-name="Gitea"
493+ --client-id="< client_id as generated by Gitea >"
494+ --client-secret="< client_secret as generated by Gitea >"
495+ --login-url="https://< your gitea host >/login/oauth/authorize"
496+ --redeem-url="https://< your gitea host >/login/oauth/access_token"
497+ --validate-url="https://< your gitea host >/api/v1"
498+```
499+
500+
501+## Email Authentication
502+
503+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=*`.
504+
505+## Adding a new Provider
506+
507+Follow the examples in the [`providers` package](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/) to define a new
508+`Provider` instance. Add a new `case` to
509+[`providers.New()`](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/providers/providers.go) to allow `oauth2-proxy` to use the
510+new `Provider`.