---
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
```

### 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`

## 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