The Bitbucket provider --bitbucket-team flag got deprecated and we added --bitbucket-workspace flag to restrict logins to members of a specific workspace instead of a team. The --bitbucket-team flag is still supported and will act like workspace but will be removed in a future release. Please update your configuration to use the new --bitbucket-workspace flag. For more information, refer to Bitbucket teams API deprecation.
Additionally refer to OAuth client configuration for Bitbucket provider in the documentation. for changes in the scopes (Account>Read) is now required if you restrict by workspace.
Security Advisories:
Read more below
For a small subset of deployments these fixes might be breaking change for the sake of fixing trust/security boundaries.
Skip-auth path matching is now stricter: --skip-auth-route and
--skip-auth-regex no longer grant exemptions for invalid or ambiguous paths,
even when a positive or negated rule would otherwise match. This includes dot
segments, repeated slashes (including leading //), semicolons, backslashes,
fragment-like content, decoded question marks, and control characters, including
encoded forms. For example, previously public /public/file;version=1 and
/public//file now follow normal authentication and authorization. # and %23
are no longer silently stripped before matching.
Trusted X-Forwarded-Uri metadata must use origin form (/path?query), not a full
URL. Before upgrading, review public-route exemptions and external-auth header
configuration. If unusual paths must remain public, expose them separately from
the protected routing boundary rather than broadening skip-auth rules.
Flag names and configuration syntax are unchanged. Ordinary query strings,
trailing-slash distinctions, and unambiguous escaped characters retain their
matching behavior. The fix does not rewrite upstream request targets or
unconditionally reject authenticated requests; existing router behavior and
separately configured exemptions remain unchanged.
Trusted client-IP resolution now enforces trusted proxy boundaries: When
--reverse-proxy is enabled, client-IP headers configured via
--real-client-ip-header are accepted only from direct peers that match
--trusted-proxy-ip. If the direct peer is not trusted, the transport peer
address is evaluated instead.
For X-Forwarded-For, the chain is traversed from right to left, skipping
intermediate proxies in --trusted-proxy-ip and treating the first untrusted
address as the client. Leftmost entries cannot be spoofed past the trusted proxy
boundary. If --trusted-proxy-ip is left unset, OAuth2 Proxy preserves backwards
compatibility by trusting all source addresses and retaining the leftmost
behavior, which does not protect against spoofed XFF headers. To secure
--trusted-ip exemptions behind a reverse proxy, configure explicit, narrowly
scoped --trusted-proxy-ip CIDR ranges and ensure the proxy sanitizes client-IP
headers. Missing or malformed client-IP headers from a trusted proxy will no
longer fall back to granting exemptions based on the proxy's own IP.
This release introduces a breaking change for Alpha Config users and moves us significantly
closer to removing legacy configuration parameters, making the codebase of OAuth2 Proxy more
future proof and extensible.
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:
# 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-secretFurthermore, Alpha Config now fully supports configuring the Server struct using YAML.
// Server represents the configuration for the Proxy HTTP(S) configuration. type Server struct { // BindAddress is the address on which to serve traffic. BindAddress string `yaml:"bindAddress,omitempty"` // SecureBindAddress is the address on which to serve secure traffic. SecureBindAddress string `yaml:"secureBindAddress,omitempty"` // TLS contains the information for loading the certificate and key for the // secure traffic and further configuration for the TLS server. TLS *TLS `yaml:"tls,omitempty"` } // TLS contains the information for loading a TLS certificate and key // as well as an optional minimal TLS version that is acceptable. type TLS struct { // Key is the TLS key data to use. Key *SecretSource `yaml:"key,omitempty"` // Cert is the TLS certificate data to use. Cert *SecretSource `yaml:"cert,omitempty"` // MinVersion is the minimal TLS version that is acceptable. MinVersion string `yaml:"minVersion,omitempty"` // CipherSuites is a list of TLS cipher suites that are allowed. CipherSuites []string `yaml:"cipherSuites,omitempty"` }More about how to use Alpha Config can be found in the documentation.
Example Alpha configuration: https://github.com/oauth2-proxy/oauth2-proxy/blob/955ab6b/contrib/local-environment/oauth2-proxy-alpha-config.yaml
We are committed to Semantic Versioning and usually avoid breaking changes without a major version release.
Advancing Alpha Config toward its Beta stage required this exception, and even for the Alpha Config we try
to keep breaking changes in v7 to a minium. Thank you for understanding the need for this step to prepare
the project for future maintainability and future improvements like structured logging.
By default all specified headers will now be normalized, meaning that both capitalization and the use of underscores (_) versus dashes (-) will be ignored when matching headers to be stripped. For example, both X-Forwarded-For and X_Forwarded-for will now be treated as equivalent and stripped away.
Please read our security advisory for CVE-2025-64484: GHSA-vjrc-mh2v-45x6
Furthermore, we now use the access_token for validating refreshed sessions in OIDC providers instead of the id_token. This is to align with the OIDC specification which states that id_tokens are not guaranteed to be issued when using refresh tokens. In future releases we might remove the id_token validation for sessions completely.
N/A
This release introduces a breaking change for Alpha Config users and moves us significantly
closer to removing legacy configuration parameters, making the codebase of OAuth2 Proxy more
future proof and extensible.
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:
# 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-secretFurthermore, Alpha Config now fully supports configuring the Server struct using YAML.
// Server represents the configuration for the Proxy HTTP(S) configuration. type Server struct { // BindAddress is the address on which to serve traffic. BindAddress string `yaml:"bindAddress,omitempty"` // SecureBindAddress is the address on which to serve secure traffic. SecureBindAddress string `yaml:"secureBindAddress,omitempty"` // TLS contains the information for loading the certificate and key for the // secure traffic and further configuration for the TLS server. TLS *TLS `yaml:"tls,omitempty"` } // TLS contains the information for loading a TLS certificate and key // as well as an optional minimal TLS version that is acceptable. type TLS struct { // Key is the TLS key data to use. Key *SecretSource `yaml:"key,omitempty"` // Cert is the TLS certificate data to use. Cert *SecretSource `yaml:"cert,omitempty"` // MinVersion is the minimal TLS version that is acceptable. MinVersion string `yaml:"minVersion,omitempty"` // CipherSuites is a list of TLS cipher suites that are allowed. CipherSuites []string `yaml:"cipherSuites,omitempty"` }More about how to use Alpha Config can be found in the documentation.
Example Alpha configuration: https://github.com/oauth2-proxy/oauth2-proxy/blob/955ab6b/contrib/local-environment/oauth2-proxy-alpha-config.yaml
We are committed to Semantic Versioning and usually avoid breaking changes without a major version release.
Advancing Alpha Config toward its Beta stage required this exception, and even for the Alpha Config we try
to keep breaking changes in v7 to a minium. Thank you for understanding the need for this step to prepare
the project for future maintainability and future improvements like structured logging.