---
id: alpha-config
title: Alpha Configuration
---

:::warning
This page contains documentation for alpha features.
We reserve the right to make breaking changes to the features detailed within this page with no notice.

Options described in this page may be changed, removed, renamed or moved without prior warning.
Please beware of this before you use alpha configuration options.
:::

This page details a set of **alpha** configuration options in a new format.
Going forward we are intending to add structured configuration in YAML format to
replace the existing TOML based configuration file and flags.

Below is a reference for the structure of the configuration, with
[AlphaOptions](#alphaoptions) as the root of the configuration.

When using alpha configuration, your config file will look something like below:

```yaml
upstreams:
  - id: ...
    ...: ...
providers:
  - id: ...
    ...: ...
cookie:
  secret: ...
  ...: ...
injectRequestHeaders:
  - secretSource:
      ...: ...
injectResponseHeaders:
  - claimSource:
      ...: ...
```

Please browse the [reference](#configuration-reference) below for the structure
of the new configuration format.

# Migration Guide

This section details breaking changes and migration steps for moving to the new
alpha configuration format.

## Migrating header injections in v7.14.0

From v7.14.0 onward, header injection sources must be explicitly nested. If you
previously relied on squashed fields, update to the new structure before
upgrading:

```yaml
# before v7.14.0
injectRequestHeaders:
- name: X-Forwarded-User
  values:
  - claim: user
- name: X-Custom-Secret-header
  values:
  - value: my-super-secret

# v7.14.0 and later
injectRequestHeaders:
- name: X-Forwarded-User
  values:
  - claimSource:
      claim: user
- name: X-Custom-Secret-header
  values:
  - secretSource:
      value: my-super-secret
```

## Using Alpha Configuration

To use the new **alpha** configuration, generate a YAML file based on the format
described in the [reference](#configuration-reference) below.

Provide the path to this file using the `--alpha-config` flag.

:::note
When using the `--alpha-config` flag, some options are no longer available.
See [removed options](#removed-options) below for more information.
:::

### Converting configuration to the new structure

Before adding the new `--alpha-config` option, start OAuth2 Proxy using the
`convert-config-to-alpha` flag to convert existing configuration to the new format.

```bash
oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg
```

This will convert any options supported by the new format to YAML and print the
new configuration to `STDOUT`.

Copy this to a new file, remove any options from your existing configuration
noted in [removed options](#removed-options) and then start OAuth2 Proxy using
the new config.

```bash
oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
```

### Validating Alpha Configuration

Use `--config-test` to validate your alpha configuration without starting the proxy:

```bash
oauth2-proxy --config core.cfg --alpha-config alpha.yaml --config-test
```

This is useful for CI/CD pipelines to catch configuration errors before deployment.
See the [Configuration Validation](./overview.md#configuration-validation) section for more details.

### How to use environment variables

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.
When using environment variables, your yaml will look like this:

```yaml
    providers:
    - provider: azure
      clientSecret: ${CLIENT_SECRET}
      ...
```
Where CLIENT_SECRET is an environment variable.
More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs)

### How to inject custom headers

Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML.

```yaml
injectRequestHeaders:
  - name: "X-User-Email"
    values:
      - claimSource:
          claim: "email" # extract the email claim contents from the id token
  - name: "X-Static-Secret"
    values:
      # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded
      - secretSource:
          value: "c3VwZXItc2VjcmV0"
  - name: "X-Static-File-Secret"
      - secretSource:
          fromFile: "/path/to/my/secret"
  - name: "X-Static-Env-Secret"
      - secretSource:
          value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded
injectResponseHeaders:
  # Following will result in a header "Authorization: Basic <user:password> (encoded)"
  - name: "Authorization"
    values:
    - claimSource:
        claim: user
        prefix: "Basic "
        basicAuthPassword:
          value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password
```

**Value sources:** 
* `claimSource` - `claim` (session claims either from id token or from profile URL)
* `secretSource` - `value` (base64), `fromFile` (file path)

**Request option:** `preserveRequestValue: true` retains existing header values

**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest`

### How to utilize arbitrary claims provided by your Identity Provider

With the additionalClaims attribute you can specify which claims you want to extract
from the ID Token or userinfo (ProfileURL) endpoint.

Configure these on the relevant provider entry:

```yaml
providers:
  - id: my-oidc-provider
    provider: oidc
    clientID: ${OAUTH_CLIENT_ID}
    clientSecret: ${OAUTH_CLIENT_SECRET}
    oidcConfig:
      issuerURL: https://issuer.example.com
    profileURL: https://issuer.example.com/oauth2/userinfo
    additionalClaims:
      - department
      - employee_id
      - organization.name
```

OAuth2 Proxy resolves each configured claim using the following order:

1. The raw ID token is checked first.
2. If the claim is not present there and `profileURL` is configured, the userinfo endpoint is queried.
3. If `skipClaimsFromProfileURL: true` is set, only the ID token is used.

Claims that are not found are ignored rather than causing authentication to fail.

You can use dot-separated paths for nested JSON objects, for example `organization.name`.
Array indexes are not supported.

Once loaded, these claims are stored in the session as `additionalClaims`. They can then be
used anywhere session claims are accepted, including header injection:

```yaml
injectRequestHeaders:
  - name: X-Department
    values:
      - claimSource:
          claim: department
  - name: X-Organization
    values:
      - claimSource:
          claim: organization.name
```

This is useful when your IdP exposes application-specific attributes such as department,
tenant, employee ID, entitlement, or other custom claims that are not part of the default
OAuth2 Proxy session fields.

## Removed options

The following flags/options and their respective environment variables are no
longer available when using alpha configuration:

<!-- Legacy Upstream FlagSet -->
- `flush-interval`/`flush_interval`
- `pass-host-header`/`pass_host_header`
- `proxy-websockets`/`proxy_websockets`
- `ssl-upstream-insecure-skip-verify`/`ssl_upstream_insecure_skip_verify`
- `upstream`/`upstreams`

<!-- Legacy Headers FlagSet -->
- `pass-basic-auth`/`pass_basic_auth`
- `pass-access-token`/`pass_access_token`
- `pass-user-headers`/`pass_user_headers`
- `pass-authorization-header`/`pass_authorization_header`
- `set-basic-auth`/`set_basic_auth`
- `set-xauthrequest`/`set_xauthrequest`
- `set-authorization-header`/`set_authorization_header`
- `prefer-email-to-user`/`prefer_email_to_user`
- `basic-auth-password`/`basic_auth_password`
- `skip-auth-strip-headers`/`skip_auth_strip_headers`

<!-- Legacy provider FlagSet -->
- `client-id`/`client_id`
- `client-secret`/`client_secret`, and `client-secret-file`/`client_secret_file`
- `provider`
- `provider-display-name`/`provider_display_name`
- `provider-ca-file`/`provider_ca_files`
- `login-url`/`login_url`
- `redeem-url`/`redeem_url`
- `profile-url`/`profile_url`
- `resource`
- `validate-url`/`validate_url`
- `scope`
- `prompt`
- `approval-prompt`/`approval_prompt`
- `acr-values`/`acr_values`
- `user-id-claim`/`user_id_claim`
- `allowed-group`/`allowed_groups`
- `allowed-role`/`allowed_roles`
- `jwt-key`/`jwt_key`
- `jwt-key-file`/`jwt_key_file`
- `pubjwk-url`/`pubjwk_url`

and all provider-specific options, i.e. any option whose name includes `oidc`,
`azure`, `bitbucket`, `github`, `gitlab`, `google` or `keycloak`.  Attempting to
use any of these options via flags or via config when `--alpha-config` is
set will result in an error.

:::important
You must remove these options before starting OAuth2 Proxy with `--alpha-config`
:::

## Configuration Reference