From e573c14f27d370c2f3a94a806d2043fcb1d2f5b1 Mon Sep 17 00:00:00 2001 From: Jan Larwig Date: Thu, 19 Mar 2026 00:49:09 +0800 Subject: [PATCH] doc: changelog for v7.15.0 and extended docs for additional claims Signed-off-by: Jan Larwig --- CHANGELOG.md | 13 +++++ docs/docs/configuration/alpha_config.md | 52 +++++++++++++++++++ docs/docs/configuration/alpha_config.md.tmpl | 52 +++++++++++++++++++ .../configuration/alpha_config.md | 52 +++++++++++++++++++ .../configuration/alpha_config.md.tmpl | 52 +++++++++++++++++++ 5 files changed, 221 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34a25e9d..8da01f83 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,21 @@ ## Release Highlights +- ๐Ÿ”’ OIDC JWT signing algorithms can now be configured +- ๐Ÿช CSRF cookie improvements (SameSite option, proper expiration validation) +- ๐Ÿงช Configuration validation flag: --config-test +- ๐Ÿ”Œ Unix socket file mode support +- ๐Ÿ‘ค Session state can now be extend with arbitrary claims from ID Token and upstream IDP user profiles endpoint + - This opens the door for multiple features like: + - Additional arbitrary header values for any claims your IDP provides + - Extended OAuth2 Proxy UserInfo endpoint with all additional claims + - Read the docs [here](https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config#how-to-utilize-arbitrary-claims-provided-by-your-identity-provider) + ## Important Notes +CSRF cookie validation now correctly uses `CSRFExpire` instead of `Expire`. If you relied on the previous behavior, review your session timeout configuration. +Check the [documentation(https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#cookie-options) for `cookie-csrf-expire`. + ## Breaking Changes ## Changes since v7.14.3 diff --git a/docs/docs/configuration/alpha_config.md b/docs/docs/configuration/alpha_config.md index ee1883bb..680741ba 100644 --- a/docs/docs/configuration/alpha_config.md +++ b/docs/docs/configuration/alpha_config.md @@ -171,6 +171,58 @@ injectResponseHeaders: **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 diff --git a/docs/docs/configuration/alpha_config.md.tmpl b/docs/docs/configuration/alpha_config.md.tmpl index 2a9684da..e7982055 100644 --- a/docs/docs/configuration/alpha_config.md.tmpl +++ b/docs/docs/configuration/alpha_config.md.tmpl @@ -171,6 +171,58 @@ injectResponseHeaders: **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 diff --git a/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md b/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md index ee1883bb..680741ba 100644 --- a/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md +++ b/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md @@ -171,6 +171,58 @@ injectResponseHeaders: **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 diff --git a/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md.tmpl b/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md.tmpl index 2a9684da..e7982055 100644 --- a/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md.tmpl +++ b/docs/versioned_docs/version-7.15.x/configuration/alpha_config.md.tmpl @@ -171,6 +171,58 @@ injectResponseHeaders: **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