mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-23 16:02:14 +00:00
8395d4326e
<!-- Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Don't remove any of the sections. It is important that the commit history clearly shows what is changed and why. Important: By submitting a contribution you agree to the terms from our Licensing Policy as described here: https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions. --> # Which Problems Are Solved - Operators upgrading from ZITADEL v3 to v4 lacked a clear, docs-backed upgrade path covering web keys (A-10017), Login V1 vs Login V2 expectations, and post-upgrade options. - There was no standalone guide for adopting Login V2 after already running on v4. - Related ops/docs pages did not consistently point readers to the upgrade and Login V2 adoption material. - Kubernetes/Helm operators upgrading to a chart that ships ZITADEL v4 had no ops-page section linking the advisory, upgrade guide, optional Login V2 deferral (`login.enabled: false`), and chart README upgrade notes. # How the Problems Are Solved - Adds technical advisory **A-10017** documenting OIDC web key staging requirements before upgrading to v4. - Adds an **upgrade-v3-to-v4** guide with the recommended upgrade path (Login V1 remains supported; Login V2 is optional at upgrade time). - Adds a **v4-only adopt-login-v2** guide for teams adopting Login V2 later, with steps and caveats separate from the version upgrade. - Adds an **Upgrading to ZITADEL v4** subsection under `self-hosting/deploy/kubernetes/operations.mdx` that links to A-10017, the upgrade guide, Adopt Login V2, notes `login.enabled: false` when not adopting Login V2 yet, and points to the [Helm chart README](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/README.md) for chart-specific breaking changes. # Additional Changes - Registers new docs in the sidebar and wires Related / cross-links from upgrade and ops pages so the advisory and guides are discoverable together. - Aligns language so upgrade vs. Login V2 adoption are clearly separated concerns. - Light cross-link updates on troubleshooting / updating-scaling / login-client pages where related. # Additional Context - Related: A-10017 (web keys advisory) - Docs paths introduced/updated: - `apps/docs/content/support/advisory/a10017.mdx` - `apps/docs/content/self-hosting/manage/upgrade-v3-to-v4.mdx` - `apps/docs/content/self-hosting/manage/adopt-login-v2.mdx` - `apps/docs/content/self-hosting/deploy/kubernetes/operations.mdx` (new "Upgrading to ZITADEL v4" section) - Sidebar and Related / cross-links - Companion Helm chart README PR: https://github.com/zitadel/zitadel-charts/pull/608 --------- Co-authored-by: Cursor <[email protected]>
45 lines
1.9 KiB
Plaintext
45 lines
1.9 KiB
Plaintext
---
|
|
title: Technical Advisory 10017
|
|
description: "A-10017: Upgrading to ZITADEL v4 without previously enabling OIDC web keys can invalidate existing JWTs"
|
|
---
|
|
|
|
## Date and Version
|
|
|
|
Versions: upgrades to >= v4.0.0 from installations that never activated OIDC web keys
|
|
|
|
Date: 2026-07-15
|
|
|
|
## Description
|
|
|
|
ZITADEL signs OIDC ID tokens (and JWT access tokens, when configured) with asymmetric keys exposed on the JWKS endpoint.
|
|
|
|
On v3, instances could still use **legacy signing keys** until the `web_key` feature was enabled.
|
|
Starting with v4, **web keys are mandatory** and the legacy signing path is removed.
|
|
Setup generates web keys if they are missing, but tokens that were signed with legacy keys before the upgrade are no longer verifiable.
|
|
|
|
To prepare existing deployments, v3.4 introduced web key setup support, and **v3.4.1** enables the web key feature by default so new tokens can roll onto web keys while legacy keys may remain on JWKS until they expire.
|
|
|
|
## Impact
|
|
|
|
If you upgrade to v4 without having web keys active beforehand:
|
|
|
|
- Existing JWT access tokens and ID tokens may become invalid immediately
|
|
- Users may be forced to re-authenticate
|
|
- Flows that rely on `id_token_hint` (for example Console logout / re-login) can fail until session storage is cleared
|
|
|
|
## Mitigation
|
|
|
|
1. Upgrade to the latest **v3.4.x** (at least **v3.4.1**).
|
|
2. Let tokens and sessions signed with legacy keys expire (soak), **or** accept a planned re-login window.
|
|
3. Upgrade to v4 using your normal process (`setup`, then `start`). See [Upgrade from ZITADEL v3 to v4](/self-hosting/manage/upgrade-v3-to-v4).
|
|
|
|
### No action needed if
|
|
|
|
- You already run **>= v3.4.1** and have soaked since enabling web keys, or
|
|
- You previously enabled the `web_key` feature on v3 and waited for legacy-signed tokens to expire
|
|
|
|
## Related
|
|
|
|
- [OIDC web keys](/guides/integrate/login/oidc/webkeys)
|
|
- [Upgrade from ZITADEL v3 to v4](/self-hosting/manage/upgrade-v3-to-v4)
|