@@ -1,702 +0,0 @@
1−---
2−id: alpha-config
3−title: Alpha Configuration
4−---
5−
6−:::warning
7−This page contains documentation for alpha features.
8−We reserve the right to make breaking changes to the features detailed within this page with no notice.
9−
10−Options described in this page may be changed, removed, renamed or moved without prior warning.
11−Please beware of this before you use alpha configuration options.
12−:::
13−
14−This page details a set of **alpha** configuration options in a new format.
15−Going forward we are intending to add structured configuration in YAML format to
16−replace the existing TOML based configuration file and flags.
17−
18−Below is a reference for the structure of the configuration, with
19−[AlphaOptions](#alphaoptions) as the root of the configuration.
20−
21−When using alpha configuration, your config file will look something like below:
22−
23−```yaml
24−upstreams:
25− - id: ...
26− ...: ...
27−providers:
28− - id: ...
29− ...: ...
30−cookie:
31− secret: ...
32− ...: ...
33−injectRequestHeaders:
34− - secretSource:
35− ...: ...
36−injectResponseHeaders:
37− - claimSource:
38− ...: ...
39−```
40−
41−Please browse the [reference](#configuration-reference) below for the structure
42−of the new configuration format.
43−
44−# Migration Guide
45−
46−This section details breaking changes and migration steps for moving to the new
47−alpha configuration format.
48−
49−## Migrating header injections in v7.14.0
50−
51−From v7.14.0 onward, header injection sources must be explicitly nested. If you
52−previously relied on squashed fields, update to the new structure before
53−upgrading:
54−
55−```yaml
56−# before v7.14.0
57−injectRequestHeaders:
58−- name: X-Forwarded-User
59− values:
60− - claim: user
61−- name: X-Custom-Secret-header
62− values:
63− - value: my-super-secret
64−
65−# v7.14.0 and later
66−injectRequestHeaders:
67−- name: X-Forwarded-User
68− values:
69− - claimSource:
70− claim: user
71−- name: X-Custom-Secret-header
72− values:
73− - secretSource:
74− value: my-super-secret
75−```
76−
77−## Using Alpha Configuration
78−
79−To use the new **alpha** configuration, generate a YAML file based on the format
80−described in the [reference](#configuration-reference) below.
81−
82−Provide the path to this file using the `--alpha-config` flag.
83−
84−:::note
85−When using the `--alpha-config` flag, some options are no longer available.
86−See [removed options](#removed-options) below for more information.
87−:::
88−
89−### Converting configuration to the new structure
90−
91−Before adding the new `--alpha-config` option, start OAuth2 Proxy using the
92−`convert-config-to-alpha` flag to convert existing configuration to the new format.
93−
94−```bash
95−oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg
96−```
97−
98−This will convert any options supported by the new format to YAML and print the
99−new configuration to `STDOUT`.
100−
101−Copy this to a new file, remove any options from your existing configuration
102−noted in [removed options](#removed-options) and then start OAuth2 Proxy using
103−the new config.
104−
105−```bash
106−oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
107−```
108−
109−### Validating Alpha Configuration
110−
111−Use `--config-test` to validate your alpha configuration without starting the proxy:
112−
113−```bash
114−oauth2-proxy --config core.cfg --alpha-config alpha.yaml --config-test
115−```
116−
117−This is useful for CI/CD pipelines to catch configuration errors before deployment.
118−See the [Configuration Validation](./overview.md#configuration-validation) section for more details.
119−
120−### How to use environment variables
121−
122−The alpha package supports the use of environment variables in place of yaml values, allowing sensitive data to be pulled from somewhere other than the yaml file.
123−When using environment variables, your yaml will look like this:
124−
125−```yaml
126− providers:
127− - provider: azure
128− clientSecret: ${CLIENT_SECRET}
129− ...
130−```
131−Where CLIENT_SECRET is an environment variable.
132−More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs)
133−
134−### How to inject custom headers
135−
136−Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML.
137−
138−```yaml
139−injectRequestHeaders:
140− - name: "X-User-Email"
141− values:
142− - claimSource:
143− claim: "email" # extract the email claim contents from the id token
144− - name: "X-Static-Secret"
145− values:
146− # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded
147− - secretSource:
148− value: "c3VwZXItc2VjcmV0"
149− - name: "X-Static-File-Secret"
150− - secretSource:
151− fromFile: "/path/to/my/secret"
152− - name: "X-Static-Env-Secret"
153− - secretSource:
154− value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded
155−injectResponseHeaders:
156− # Following will result in a header "Authorization: Basic <user:password> (encoded)"
157− - name: "Authorization"
158− values:
159− - claimSource:
160− claim: user
161− prefix: "Basic "
162− basicAuthPassword:
163− value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password
164−```
165−
166−**Value sources:**
167−* `claimSource` - `claim` (session claims either from id token or from profile URL)
168−* `secretSource` - `value` (base64), `fromFile` (file path)
169−
170−**Request option:** `preserveRequestValue: true` retains existing header values
171−
172−**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest`
173−
174−### How to utilize arbitrary claims provided by your Identity Provider
175−
176−With the additionalClaims attribute you can specify which claims you want to extract
177−from the ID Token or userinfo (ProfileURL) endpoint.
178−
179−Configure these on the relevant provider entry:
180−
181−```yaml
182−providers:
183− - id: my-oidc-provider
184− provider: oidc
185− clientID: ${OAUTH_CLIENT_ID}
186− clientSecret: ${OAUTH_CLIENT_SECRET}
187− oidcConfig:
188− issuerURL: https://issuer.example.com
189− profileURL: https://issuer.example.com/oauth2/userinfo
190− additionalClaims:
191− - department
192− - employee_id
193− - organization.name
194−```
195−
196−OAuth2 Proxy resolves each configured claim using the following order:
197−
198−1. The raw ID token is checked first.
199−2. If the claim is not present there and `profileURL` is configured, the userinfo endpoint is queried.
200−3. If `skipClaimsFromProfileURL: true` is set, only the ID token is used.
201−
202−Claims that are not found are ignored rather than causing authentication to fail.
203−
204−You can use dot-separated paths for nested JSON objects, for example `organization.name`.
205−Array indexes are not supported.
206−
207−Once loaded, these claims are stored in the session as `additionalClaims`. They can then be
208−used anywhere session claims are accepted, including header injection:
209−
210−```yaml
211−injectRequestHeaders:
212− - name: X-Department
213− values:
214− - claimSource:
215− claim: department
216− - name: X-Organization
217− values:
218− - claimSource:
219− claim: organization.name
220−```
221−
222−This is useful when your IdP exposes application-specific attributes such as department,
223−tenant, employee ID, entitlement, or other custom claims that are not part of the default
224−OAuth2 Proxy session fields.
225−
226−## Removed options
227−
228−The following flags/options and their respective environment variables are no
229−longer available when using alpha configuration:
230−
231−<!-- Legacy Upstream FlagSet -->
232−- `flush-interval`/`flush_interval`
233−- `pass-host-header`/`pass_host_header`
234−- `proxy-websockets`/`proxy_websockets`
235−- `ssl-upstream-insecure-skip-verify`/`ssl_upstream_insecure_skip_verify`
236−- `upstream`/`upstreams`
237−
238−<!-- Legacy Headers FlagSet -->
239−- `pass-basic-auth`/`pass_basic_auth`
240−- `pass-access-token`/`pass_access_token`
241−- `pass-user-headers`/`pass_user_headers`
242−- `pass-authorization-header`/`pass_authorization_header`
243−- `set-basic-auth`/`set_basic_auth`
244−- `set-xauthrequest`/`set_xauthrequest`
245−- `set-authorization-header`/`set_authorization_header`
246−- `prefer-email-to-user`/`prefer_email_to_user`
247−- `basic-auth-password`/`basic_auth_password`
248−- `skip-auth-strip-headers`/`skip_auth_strip_headers`
249−
250−<!-- Legacy provider FlagSet -->
251−- `client-id`/`client_id`
252−- `client-secret`/`client_secret`, and `client-secret-file`/`client_secret_file`
253−- `provider`
254−- `provider-display-name`/`provider_display_name`
255−- `provider-ca-file`/`provider_ca_files`
256−- `login-url`/`login_url`
257−- `redeem-url`/`redeem_url`
258−- `profile-url`/`profile_url`
259−- `resource`
260−- `validate-url`/`validate_url`
261−- `scope`
262−- `prompt`
263−- `approval-prompt`/`approval_prompt`
264−- `acr-values`/`acr_values`
265−- `user-id-claim`/`user_id_claim`
266−- `allowed-group`/`allowed_groups`
267−- `allowed-role`/`allowed_roles`
268−- `jwt-key`/`jwt_key`
269−- `jwt-key-file`/`jwt_key_file`
270−- `pubjwk-url`/`pubjwk_url`
271−
272−and all provider-specific options, i.e. any option whose name includes `oidc`,
273−`azure`, `bitbucket`, `github`, `gitlab`, `google` or `keycloak`. Attempting to
274−use any of these options via flags or via config when `--alpha-config` is
275−set will result in an error.
276−
277−:::important
278−You must remove these options before starting OAuth2 Proxy with `--alpha-config`
279−:::
280−
281−## Configuration Reference
282−
283−<!--- THIS FILE IS AUTOGENERATED!!! DO NOT EDIT!!! -->
284−
285−### ADFSOptions
286−
287−(**Appears on:** [Provider](#provider))
288−
289−
290−
291−| Field | Type | Description |
292−| ----- | ---- | ----------- |
293−| `skipScope` | _bool_ | Skip adding the scope parameter in login request<br/>Default value is 'false' |
294−
295−### AlphaOptions
296−
297−AlphaOptions contains alpha structured configuration options.
298−Usage of these options allows users to access alpha features that are not
299−available as part of the primary configuration structure for OAuth2 Proxy.
300−
301−:::warning
302−The options within this structure are considered alpha.
303−They may change between releases without notice.
304−:::
305−
306−| Field | Type | Description |
307−| ----- | ---- | ----------- |
308−| `upstreamConfig` | _[UpstreamConfig](#upstreamconfig)_ | UpstreamConfig is used to configure upstream servers.<br/>Once a user is authenticated, requests to the server will be proxied to<br/>these upstream servers based on the path mappings defined in this list. |
309−| `injectRequestHeaders` | _[[]Header](#header)_ | InjectRequestHeaders is used to configure headers that should be added<br/>to requests to upstream servers.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
310−| `injectResponseHeaders` | _[[]Header](#header)_ | InjectResponseHeaders is used to configure headers that should be added<br/>to responses from the proxy.<br/>This is typically used when using the proxy as an external authentication<br/>provider in conjunction with another proxy such as NGINX and its<br/>auth_request module.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
311−| `server` | _[Server](#server)_ | Server is used to configure the HTTP(S) server for the proxy application.<br/>You may choose to run both HTTP and HTTPS servers simultaneously.<br/>This can be done by setting the BindAddress and the SecureBindAddress simultaneously.<br/>To use the secure server you must configure a TLS certificate and key. |
312−| `metricsServer` | _[Server](#server)_ | MetricsServer is used to configure the HTTP(S) server for metrics.<br/>You may choose to run both HTTP and HTTPS servers simultaneously.<br/>This can be done by setting the BindAddress and the SecureBindAddress simultaneously.<br/>To use the secure server you must configure a TLS certificate and key. |
313−| `providers` | _[Providers](#providers)_ | Providers is used to configure your provider. **Multiple-providers is not<br/>yet working.** [This feature is tracked in<br/>#925](https://github.com/oauth2-proxy/oauth2-proxy/issues/926) |
314−
315−### AzureOptions
316−
317−(**Appears on:** [Provider](#provider))
318−
319−
320−
321−| Field | Type | Description |
322−| ----- | ---- | ----------- |
323−| `tenant` | _string_ | Tenant directs to a tenant-specific or common (tenant-independent) endpoint<br/>Default value is 'common' |
324−| `graphGroupField` | _string_ | GraphGroupField configures the group field to be used when building the groups list from Microsoft Graph<br/>Default value is 'id' |
325−
326−### BitbucketOptions
327−
328−(**Appears on:** [Provider](#provider))
329−
330−
331−
332−| Field | Type | Description |
333−| ----- | ---- | ----------- |
334−| `team` | _string_ | Team sets restrict logins to members of this team |
335−| `repository` | _string_ | Repository sets restrict logins to user with access to this repository |
336−
337−### ClaimSource
338−
339−(**Appears on:** [HeaderValue](#headervalue))
340−
341−ClaimSource allows loading a header value from a claim within the session
342−
343−| Field | Type | Description |
344−| ----- | ---- | ----------- |
345−| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. Available claims: `access_token` `id_token` `created_at`<br/>`expires_on` `refresh_token` `email` `user` `groups` `preferred_username`. |
346−| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
347−| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
348−
349−### GitHubOptions
350−
351−(**Appears on:** [Provider](#provider))
352−
353−
354−
355−| Field | Type | Description |
356−| ----- | ---- | ----------- |
357−| `org` | _string_ | Org sets restrict logins to members of this organisation |
358−| `team` | _string_ | Team sets restrict logins to members of this team |
359−| `repo` | _string_ | Repo sets restrict logins to collaborators of this repository |
360−| `token` | _string_ | Token is the token to use when verifying repository collaborators<br/>it must have push access to the repository |
361−| `users` | _[]string_ | Users allows users with these usernames to login<br/>even if they do not belong to the specified org and team or collaborators |
362−
363−### GitLabOptions
364−
365−(**Appears on:** [Provider](#provider))
366−
367−
368−
369−| Field | Type | Description |
370−| ----- | ---- | ----------- |
371−| `group` | _[]string_ | Group sets restrict logins to members of this group |
372−| `projects` | _[]string_ | Projects restricts logins to members of these projects |
373−
374−### GoogleOptions
375−
376−(**Appears on:** [Provider](#provider))
377−
378−
379−
380−| Field | Type | Description |
381−| ----- | ---- | ----------- |
382−| `group` | _[]string_ | Groups sets restrict logins to members of this Google group |
383−| `adminEmail` | _string_ | AdminEmail is the Google admin to impersonate for api calls |
384−| `serviceAccountJson` | _string_ | ServiceAccountJSON is the path to the service account json credentials |
385−| `useApplicationDefaultCredentials` | _bool_ | UseApplicationDefaultCredentials is a boolean whether to use Application Default Credentials instead of a ServiceAccountJSON |
386−| `targetPrincipal` | _string_ | TargetPrincipal is the Google Service Account used for Application Default Credentials |
387−| `useOrganizationID` | _bool_ | UseOrganizationId indicates whether to use the organization ID as the UserName claim |
388−| `adminAPIUserScope` | _string_ | admin scope needed for fetching user organization information from admin api, can be one of cloud, user or defaults to readonly |
389−
390−### Header
391−
392−(**Appears on:** [AlphaOptions](#alphaoptions))
393−
394−Header represents an individual header that will be added to a request or
395−response header.
396−
397−| Field | Type | Description |
398−| ----- | ---- | ----------- |
399−| `name` | _string_ | Name is the header name to be used for this set of values.<br/>Names should be unique within a list of Headers. |
400−| `preserveRequestValue` | _bool_ | PreserveRequestValue determines whether any values for this header<br/>should be preserved for the request to the upstream server.<br/>This option only applies to injected request headers.<br/>Defaults to false (headers that match this header will be stripped). |
401−| `InsecureSkipHeaderNormalization` | _bool_ | InsecureSkipHeaderNormalization disables normalizing the header name<br/>According to RFC 7230 Section 3.2 there aren't any rules about<br/>capitalization of header names, but the standard practice is to use<br/>Title-Case (e.g. X-Forwarded-For). By default, header names will be<br/>normalized to Title-Case and any incoming headers that match will be<br/>treated as the same header. Additionally underscores (_) in header names<br/>will be converted to dashes (-) when normalizing.<br/>Defaults to false (header names will be normalized). |
402−| `values` | _[[]HeaderValue](#headervalue)_ | Values contains the desired values for this header |
403−
404−### HeaderValue
405−
406−(**Appears on:** [Header](#header))
407−
408−HeaderValue represents a single header value and the sources that can
409−make up the header value
410−
411−| Field | Type | Description |
412−| ----- | ---- | ----------- |
413−| `value` | _[]byte_ | Value expects a base64 encoded string value. |
414−| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
415−| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
416−| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. Available claims: `access_token` `id_token` `created_at`<br/>`expires_on` `refresh_token` `email` `user` `groups` `preferred_username`. |
417−| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
418−| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
419−
420−### KeycloakOptions
421−
422−(**Appears on:** [Provider](#provider))
423−
424−
425−
426−| Field | Type | Description |
427−| ----- | ---- | ----------- |
428−| `groups` | _[]string_ | Group enables to restrict login to members of indicated group |
429−| `roles` | _[]string_ | Role enables to restrict login to users with role (only available when using the keycloak-oidc provider) |
430−
431−### LoginGovOptions
432−
433−(**Appears on:** [Provider](#provider))
434−
435−
436−
437−| Field | Type | Description |
438−| ----- | ---- | ----------- |
439−| `jwtKey` | _string_ | JWTKey is a private key in PEM format used to sign JWT, |
440−| `jwtKeyFile` | _string_ | JWTKeyFile is a path to the private key file in PEM format used to sign the JWT |
441−| `pubjwkURL` | _string_ | PubJWKURL is the JWK pubkey access endpoint |
442−
443−### LoginURLParameter
444−
445−(**Appears on:** [Provider](#provider))
446−
447−LoginURLParameter is the configuration for a single query parameter that
448−can be passed through from the `/oauth2/start` endpoint to the IdP login
449−URL. The "default" option specifies the default value or values (if any)
450−that will be passed to the IdP for this parameter, and "allow" is a list
451−of options for ways in which this parameter can be set or overridden via
452−the query string to `/oauth2/start`.
453−If _only_ a default is specified and no "allow" then the parameter is
454−effectively fixed - the default value will always be used and anything
455−passed to the start URL will be ignored. If _only_ "allow" is specified
456−but no default then the parameter will only be passed on to the IdP if
457−the caller provides it, and no value will be sent otherwise.
458−
459−Examples:
460−
461−# A parameter whose value is fixed
462−
463−```
464−name: organization
465−default:
466−- myorg
467−```
468−
469−A parameter that is not passed by default, but may be set to one of a
470−fixed set of values
471−
472−```
473−name: prompt
474−allow:
475−- value: login
476−- value: consent
477−- value: select_account
478−```
479−
480−A parameter that is passed by default but may be overridden by one of
481−a fixed set of values
482−
483−```
484−name: prompt
485−default: ["login"]
486−allow:
487−- value: consent
488−- value: select_account
489−```
490−
491−A parameter that may be overridden, but only by values that match a
492−regular expression. For example to restrict `login_hint` to email
493−addresses in your organization's domain:
494−
495−```
496−name: login_hint
497−allow:
498−- pattern: '^[^@]*@example\.com$'
499−# this allows at most one "@" sign, and requires "example.com" domain.
500−```
501−
502−Note that the YAML rules around exactly which characters are allowed
503−and/or require escaping in different types of string literals are
504−convoluted. For regular expressions the single quoted form is simplest
505−as backslash is not considered to be an escape character. Alternatively
506−use the "chomped block" format `|-`:
507−
508−```
509− - pattern: |-
510− ^[^@]*@example\.com$
511−
512−```
513−
514−The hyphen is important, a `|` block would have a trailing newline
515−character.
516−
517−| Field | Type | Description |
518−| ----- | ---- | ----------- |
519−| `name` | _string_ | Name specifies the name of the query parameter. |
520−| `default` | _[]string_ | _(Optional)_ Default specifies a default value or values that will be<br/>passed to the IdP if not overridden. |
521−| `allow` | _[[]URLParameterRule](#urlparameterrule)_ | _(Optional)_ Allow specifies rules about how the default (if any) may be<br/>overridden via the query string to `/oauth2/start`. Only<br/>values that match one or more of the allow rules will be<br/>forwarded to the IdP. |
522−
523−### MicrosoftEntraIDOptions
524−
525−(**Appears on:** [Provider](#provider))
526−
527−
528−
529−| Field | Type | Description |
530−| ----- | ---- | ----------- |
531−| `allowedTenants` | _[]string_ | AllowedTenants is a list of allowed tenants. In case of multi-tenant apps, incoming tokens are<br/>issued by different issuers and OIDC issuer verification needs to be disabled.<br/>When not specified, all tenants are allowed. Redundant for single-tenant apps<br/>(regular ID token validation matches the issuer). |
532−| `federatedTokenAuth` | _bool_ | FederatedTokenAuth enable oAuth2 client authentication with federated token projected<br/>by Entra Workload Identity plugin, instead of client secret. |
533−
534−### OIDCOptions
535−
536−(**Appears on:** [Provider](#provider))
537−
538−
539−
540−| Field | Type | Description |
541−| ----- | ---- | ----------- |
542−| `issuerURL` | _string_ | IssuerURL is the OpenID Connect issuer URL<br/>eg: https://accounts.google.com |
543−| `insecureAllowUnverifiedEmail` | _bool_ | InsecureAllowUnverifiedEmail prevents failures if an email address in an id_token is not verified<br/>default set to 'false' |
544−| `insecureSkipIssuerVerification` | _bool_ | InsecureSkipIssuerVerification skips verification of ID token issuers. When false, ID Token Issuers must match the OIDC discovery URL<br/>default set to 'false' |
545−| `insecureSkipNonce` | _bool_ | InsecureSkipNonce skips verifying the ID Token's nonce claim that must match<br/>the random nonce sent in the initial OAuth flow. Otherwise, the nonce is checked<br/>after the initial OAuth redeem & subsequent token refreshes.<br/>default set to 'true'<br/>Warning: In a future release, this will change to 'false' by default for enhanced security. |
546−| `skipDiscovery` | _bool_ | SkipDiscovery allows to skip OIDC discovery and use manually supplied Endpoints<br/>default set to 'false' |
547−| `jwksURL` | _string_ | JwksURL is the OpenID Connect JWKS URL<br/>eg: https://www.googleapis.com/oauth2/v3/certs |
548−| `publicKeyFiles` | _[]string_ | PublicKeyFiles is a list of paths pointing to public key files in PEM format to use<br/>for verifying JWT tokens |
549−| `emailClaim` | _string_ | EmailClaim indicates which claim contains the user email,<br/>default set to 'email' |
550−| `groupsClaim` | _string_ | GroupsClaim indicates which claim contains the user groups<br/>default set to 'groups' |
551−| `userIDClaim` | _string_ | UserIDClaim indicates which claim contains the user ID<br/>default set to 'email' |
552−| `audienceClaims` | _[]string_ | AudienceClaim allows to define any claim that is verified against the client id<br/>By default `aud` claim is used for verification. |
553−| `extraAudiences` | _[]string_ | ExtraAudiences is a list of additional audiences that are allowed<br/>to pass verification in addition to the client id. |
554−| `enabledSigningAlgs` | _[]string_ | EnabledSigningAlgs is a list of allowed JWT signing algorithms.<br/>When discovery is enabled, the effective set is the intersection<br/>between this list and the provider's discovered supported algorithms.<br/>By default `RS256` is used if nothing has been discovered or specified. |
555−
556−### Provider
557−
558−(**Appears on:** [Providers](#providers))
559−
560−Provider holds all configuration for a single provider
561−
562−| Field | Type | Description |
563−| ----- | ---- | ----------- |
564−| `clientID` | _string_ | ClientID is the OAuth Client ID that is defined in the provider<br/>This value is required for all providers. |
565−| `clientSecret` | _string_ | ClientSecret is the OAuth Client Secret that is defined in the provider<br/>This value is required for all providers. |
566−| `clientSecretFile` | _string_ | ClientSecretFile is the name of the file<br/>containing the OAuth Client Secret, it will be used if ClientSecret is not set. |
567−| `keycloakConfig` | _[KeycloakOptions](#keycloakoptions)_ | KeycloakConfig holds all configurations for Keycloak provider. |
568−| `azureConfig` | _[AzureOptions](#azureoptions)_ | AzureConfig holds all configurations for Azure provider. |
569−| `microsoftEntraIDConfig` | _[MicrosoftEntraIDOptions](#microsoftentraidoptions)_ | MicrosoftEntraIDConfig holds all configurations for Entra ID provider. |
570−| `ADFSConfig` | _[ADFSOptions](#adfsoptions)_ | ADFSConfig holds all configurations for ADFS provider. |
571−| `bitbucketConfig` | _[BitbucketOptions](#bitbucketoptions)_ | BitbucketConfig holds all configurations for Bitbucket provider. |
572−| `githubConfig` | _[GitHubOptions](#githuboptions)_ | GitHubConfig holds all configurations for GitHubC provider. |
573−| `gitlabConfig` | _[GitLabOptions](#gitlaboptions)_ | GitLabConfig holds all configurations for GitLab provider. |
574−| `googleConfig` | _[GoogleOptions](#googleoptions)_ | GoogleConfig holds all configurations for Google provider. |
575−| `oidcConfig` | _[OIDCOptions](#oidcoptions)_ | OIDCConfig holds all configurations for OIDC provider<br/>or providers utilize OIDC configurations. |
576−| `loginGovConfig` | _[LoginGovOptions](#logingovoptions)_ | LoginGovConfig holds all configurations for LoginGov provider. |
577−| `id` | _string_ | ID should be a unique identifier for the provider.<br/>This value is required for all providers. |
578−| `provider` | _[ProviderType](#providertype)_ | Type is the OAuth provider<br/>must be set from the supported providers group,<br/>otherwise 'Google' is set as default |
579−| `name` | _string_ | Name is the providers display name<br/>if set, it will be shown to the users in the login page. |
580−| `caFiles` | _[]string_ | CAFiles is a list of paths to CA certificates that should be used when connecting to the provider.<br/>If not specified, the default Go trust sources are used instead |
581−| `useSystemTrustStore` | _bool_ | UseSystemTrustStore determines if your custom CA files and the system trust store are used<br/>If set to true, your custom CA files and the system trust store are used otherwise only your custom CA files. |
582−| `loginURL` | _string_ | LoginURL is the authentication endpoint |
583−| `loginURLParameters` | _[[]LoginURLParameter](#loginurlparameter)_ | LoginURLParameters defines the parameters that can be passed from the start URL to the IdP login URL |
584−| `authRequestResponseMode` | _string_ | AuthRequestResponseMode defines the response mode to request during authorization request |
585−| `redeemURL` | _string_ | RedeemURL is the token redemption endpoint |
586−| `profileURL` | _string_ | ProfileURL is the profile access endpoint |
587−| `skipClaimsFromProfileURL` | _bool_ | SkipClaimsFromProfileURL allows to skip request to Profile URL for resolving claims not present in id_token<br/>default set to 'false' |
588−| `resource` | _string_ | ProtectedResource is the resource that is protected (Azure AD and ADFS only) |
589−| `validateURL` | _string_ | ValidateURL is the access token validation endpoint |
590−| `scope` | _string_ | Scope is the OAuth scope specification |
591−| `allowedGroups` | _[]string_ | AllowedGroups is a list of restrict logins to members of this group |
592−| `code_challenge_method` | _string_ | The code challenge method |
593−| `additionalClaims` | _[]string_ | Additional claims to be obtained from the upstream IDP, either from the id_token or from the userinfo endpoint if configured. |
594−| `backendLogoutURL` | _string_ | URL to call to perform backend logout, `{id_token}` would be replaced by the actual `id_token` if available in the session |
595−
596−### ProviderType
597−#### (`string` alias)
598−
599−(**Appears on:** [Provider](#provider))
600−
601−ProviderType is used to enumerate the different provider type options
602−Valid options are: adfs, azure, bitbucket, digitalocean facebook, github,
603−gitlab, google, keycloak, keycloak-oidc, linkedin, login.gov, nextcloud
604−and oidc.
605−
606−### Providers
607−
608−#### ([[]Provider](#provider) alias)
609−
610−(**Appears on:** [AlphaOptions](#alphaoptions))
611−
612−The provider can be selected using the `provider` configuration value, or
613−set in the [`providers` array using
614−AlphaConfig](https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config#providers).
615−However, [**the feature to implement multiple providers is not
616−complete**](https://github.com/oauth2-proxy/oauth2-proxy/issues/926).
617−
618−### SecretSource
619−
620−(**Appears on:** [ClaimSource](#claimsource), [HeaderValue](#headervalue), [TLS](#tls))
621−
622−SecretSource references an individual secret value.
623−Only one source within the struct should be defined at any time.
624−
625−| Field | Type | Description |
626−| ----- | ---- | ----------- |
627−| `value` | _[]byte_ | Value expects a base64 encoded string value. |
628−| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
629−| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
630−
631−### Server
632−
633−(**Appears on:** [AlphaOptions](#alphaoptions))
634−
635−Server represents the configuration for an HTTP(S) server
636−
637−| Field | Type | Description |
638−| ----- | ---- | ----------- |
639−| `bindAddress` | _string_ | BindAddress is the address on which to serve traffic.<br/>Different types of bind addresses are supported:<br/>* `[http://]<addr>:<port>`<br/>* `fd:<int>` (case insensitive)<br/>* `unix://<path>`<br/>Unix sockets are created with default system umask mode, which can be overridden, e.g.: `unix://my-socket,mode=0777`<br/>Square brackets are required for ipv6 address, e.g. `http://[::1]:4180`<br/>Leave blank or set to "-" to disable. |
640−| `secureBindAddress` | _string_ | SecureBindAddress is the address on which to serve secure traffic.<br/>Secure bind addresses need to respond with valid SSL and use the following format:<br/>* `[https://]<addr>:<port>`<br/>Square brackets are required for ipv6 address, e.g. `https://[::1]:4180`<br/>Leave blank or set to "-" to disable. |
641−| `tls` | _[TLS](#tls)_ | TLS contains the information for loading the certificate and key for the<br/>secure traffic and further configuration for the TLS server. |
642−
643−### TLS
644−
645−(**Appears on:** [Server](#server))
646−
647−TLS contains the information for loading a TLS certificate and key
648−as well as an optional minimal TLS version that is acceptable.
649−
650−| Field | Type | Description |
651−| ----- | ---- | ----------- |
652−| `key` | _[SecretSource](#secretsource)_ | Key is the TLS key data to use.<br/>Typically this will come from a file. |
653−| `cert` | _[SecretSource](#secretsource)_ | Cert is the TLS certificate data to use.<br/>Typically this will come from a file. |
654−| `minVersion` | _string_ | MinVersion is the minimal TLS version that is acceptable.<br/>E.g. Set to "TLS1.3" to select TLS version 1.3 |
655−| `cipherSuites` | _[]string_ | CipherSuites is a list of TLS cipher suites that are allowed.<br/>E.g.:<br/>- TLS_RSA_WITH_RC4_128_SHA<br/>- TLS_RSA_WITH_AES_256_GCM_SHA384<br/>If not specified, the default Go safe cipher list is used.<br/>List of valid cipher suites can be found in the [crypto/tls documentation](https://pkg.go.dev/crypto/tls#pkg-constants). |
656−
657−### URLParameterRule
658−
659−(**Appears on:** [LoginURLParameter](#loginurlparameter))
660−
661−URLParameterRule represents a rule by which query parameters
662−passed to the `/oauth2/start` endpoint are checked to determine whether
663−they are valid overrides for the given parameter passed to the IdP's
664−login URL. Either Value or Pattern should be supplied, not both.
665−
666−| Field | Type | Description |
667−| ----- | ---- | ----------- |
668−| `value` | _string_ | A Value rule matches just this specific value |
669−| `pattern` | _string_ | A Pattern rule gives a regular expression that must be matched by<br/>some substring of the value. The expression is _not_ automatically<br/>anchored to the start and end of the value, if you _want_ to restrict<br/>the whole parameter value you must anchor it yourself with `^` and `$`. |
670−
671−### Upstream
672−
673−(**Appears on:** [UpstreamConfig](#upstreamconfig))
674−
675−Upstream represents the configuration for an upstream server.
676−Requests will be proxied to this upstream if the path matches the request path.
677−
678−| Field | Type | Description |
679−| ----- | ---- | ----------- |
680−| `id` | _string_ | ID should be a unique identifier for the upstream.<br/>This value is required for all upstreams. |
681−| `path` | _string_ | Path is used to map requests to the upstream server.<br/>The closest match will take precedence and all Paths must be unique.<br/>Path can also take a pattern when used with RewriteTarget.<br/>Path segments can be captured and matched using regular experessions.<br/>Eg:<br/>- `^/foo$`: Match only the explicit path `/foo`<br/>- `^/bar/$`: Match any path prefixed with `/bar/`<br/>- `^/baz/(.*)$`: Match any path prefixed with `/baz` and capture the remaining path for use with RewriteTarget |
682−| `rewriteTarget` | _string_ | RewriteTarget allows users to rewrite the request path before it is sent to<br/>the upstream server (for an HTTP/HTTPS upstream) or mapped to the filesystem<br/>(for a `file:` upstream).<br/>Use the Path to capture segments for reuse within the rewrite target.<br/>Eg: With a Path of `^/baz/(.*)`, a RewriteTarget of `/foo/$1` would rewrite<br/>the request `/baz/abc/123` to `/foo/abc/123` before proxying to the<br/>upstream server. Or if the upstream were `file:///app`, a request for<br/>`/baz/info.html` would return the contents of the file `/app/foo/info.html`. |
683−| `uri` | _string_ | The URI of the upstream server. This may be an HTTP(S) server of a File<br/>based URL. It may include a path, in which case all requests will be served<br/>under that path.<br/>Eg:<br/>- http://localhost:8080<br/>- https://service.localhost<br/>- https://service.localhost/path<br/>- file://host/path<br/>If the URI's path is "/base" and the incoming request was for "/dir",<br/>the upstream request will be for "/base/dir". |
684−| `insecureSkipTLSVerify` | _bool_ | InsecureSkipTLSVerify will skip TLS verification of upstream HTTPS hosts.<br/>This option is insecure and will allow potential Man-In-The-Middle attacks<br/>between OAuth2 Proxy and the upstream server.<br/>Defaults to false. |
685−| `static` | _bool_ | Static will make all requests to this upstream have a static response.<br/>The response will have a body of "Authenticated" and a response code<br/>matching StaticCode.<br/>If StaticCode is not set, the response will return a 200 response. |
686−| `staticCode` | _int_ | StaticCode determines the response code for the Static response.<br/>This option can only be used with Static enabled. |
687−| `flushInterval` | _duration_ | FlushInterval is the period between flushing the response buffer when<br/>streaming response from the upstream.<br/>Defaults to 1 second. |
688−| `passHostHeader` | _bool_ | PassHostHeader determines whether the request host header should be proxied<br/>to the upstream server.<br/>Defaults to true. |
689−| `proxyWebSockets` | _bool_ | ProxyWebSockets enables proxying of websockets to upstream servers<br/>Defaults to true. |
690−| `timeout` | _duration_ | Timeout is the maximum duration the server will wait for a response from the upstream server.<br/>Defaults to 30 seconds. |
691−| `disableKeepAlives` | _bool_ | DisableKeepAlives disables HTTP keep-alive connections to the upstream server.<br/>Defaults to false. |
692−
693−### UpstreamConfig
694−
695−(**Appears on:** [AlphaOptions](#alphaoptions))
696−
697−UpstreamConfig is a collection of definitions for upstream servers.
698−
699−| Field | Type | Description |
700−| ----- | ---- | ----------- |
701−| `proxyRawPath` | _bool_ | ProxyRawPath will pass the raw url path to upstream allowing for urls<br/>like: "/%2F/" which would otherwise be redirected to "/" |
702−| `upstreams` | _[[]Upstream](#upstream)_ | Upstreams represents the configuration for the upstream servers.<br/>Requests will be proxied to this upstream if the path matches the request path. |