mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-05 05:42:16 +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]>
125 lines
5.0 KiB
Plaintext
125 lines
5.0 KiB
Plaintext
---
|
|
title: Adopt Login V2 on an existing installation
|
|
description: "Deploy and enable Hosted Login V2 for self-hosted ZITADEL v4 instances that currently use Login V1"
|
|
sidebar_label: Adopt Login V2
|
|
---
|
|
|
|
## Who this is for
|
|
|
|
Self-hosted **ZITADEL v4** deployments with existing instances that still use **Login V1**.
|
|
|
|
Login V2 was not the default on v3 and is not a supported cutover target there. If you are still on v3, [upgrade to v4](/self-hosting/manage/upgrade-v3-to-v4) first, then return here.
|
|
|
|
New v4 installations may enable Login V2 by default. That does **not** rewrite existing instances.
|
|
|
|
## Do you need to switch?
|
|
|
|
**No — not for normal v4 operation.** Remaining on Login V1 is supported and is the right default unless you have a concrete reason to move.
|
|
|
|
Consider Login V2 when you need capabilities that depend on it (including many **Actions V2** flows). Plan extra time if you rely on **Actions V1** or deep Login V1 customizations: those usually must be migrated, and some setups need careful validation because not every V1 pattern has an identical V2 equivalent yet.
|
|
See [Migrate from Actions V1 to V2](/guides/integrate/actions/migrate-from-v1).
|
|
|
|
If you do not urgently need Login V2, stay on Login V1 and revisit later.
|
|
|
|
## Overview
|
|
|
|
1. Deploy and route the Login UI (no production traffic yet)
|
|
2. Authenticate login → API (PAT **or** system-user JWT / X.509)
|
|
3. Smoke-test Login V2
|
|
4. Cut over gradually (per app) or instance-wide
|
|
5. Update IdP callbacks and related config
|
|
|
|
<Callout type="warn">
|
|
Before enabling Login V2 for production traffic, create a break-glass machine user with `IAM_OWNER` and a PAT.
|
|
If login misconfiguration locks interactive access, use the PAT to revert the feature or fix routing.
|
|
</Callout>
|
|
|
|
## 1. Deploy and route
|
|
|
|
1. Deploy `zitadel-login` (compose, Helm, or your own packaging).
|
|
2. On your reverse proxy / ingress:
|
|
- `/ui/v2/login` → login service
|
|
- everything else → ZITADEL API
|
|
|
|
See [Login UI routing](/self-hosting/manage/reverseproxy/reverse_proxy#login-ui-routing).
|
|
|
|
## 2. Authenticate login to the API
|
|
|
|
Pick **one** method. Login resolves credentials roughly as:
|
|
|
|
1. System-user JWT (`AUDIENCE`, `SYSTEM_USER_ID`, `SYSTEM_USER_PRIVATE_KEY` / `_FILE`)
|
|
2. `ZITADEL_LOGINCLIENT_KEYFILE` (subject `login-client`)
|
|
3. Service-user PAT (`ZITADEL_SERVICE_USER_TOKEN` / `_FILE`)
|
|
|
|
### Option A — PAT (classic)
|
|
|
|
For **existing** instances the setup job does **not** auto-create the login client.
|
|
|
|
1. Create a machine user
|
|
2. Grant **Instance Login Client** (`IAM_LOGIN_CLIENT`)
|
|
3. Create a PAT and provide it to the login UI
|
|
|
|
Step-by-step: [Create a Login Client](/self-hosting/manage/login-client).
|
|
|
|
### Option B — RSA / X.509 system user (recommended on recent Helm)
|
|
|
|
On **Helm chart ≥ v10** with **ZITADEL ≥ v4.14**:
|
|
|
|
- The chart generates an RSA keypair (or uses `login.loginServiceKeySecretName`)
|
|
- Registers the public cert under `SystemAPIUsers` (login client)
|
|
- Mounts the private key into the login container
|
|
|
|
No login PAT is required for login↔API auth.
|
|
Older `login-client` PAT secrets from chart v9 are unused after that switch and can be deleted.
|
|
|
|
See the [Helm chart README](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/README.md) (Upgrade From V9 to V10) for chart-specific details.
|
|
|
|
Manual equivalent: register a [System API user](/guides/integrate/zitadel-apis/access-zitadel-system-api) with `IAM_LOGIN_CLIENT` membership and configure the login env vars above.
|
|
|
|
## 3. Smoke-test (feature still off)
|
|
|
|
Open `https://<your-domain>/ui/v2/login` and verify health while production apps still use Login V1.
|
|
|
|
Also prepare:
|
|
|
|
- External IdP redirect / callback URLs for Login V2 paths
|
|
- Trusted domains if login is hosted on a separate hostname
|
|
|
|
## 4. Cut over
|
|
|
|
### Gradual (recommended)
|
|
|
|
With the instance Login V2 feature **disabled**:
|
|
|
|
1. Open the application in Console
|
|
2. Enable **Use new login UI**
|
|
3. Optionally set a custom base URL for a separately hosted login UI
|
|
|
|
Only that application uses Login V2. See [Application settings](/guides/manage/console/applications-overview#use-new-login-ui).
|
|
|
|
### Instance-wide
|
|
|
|
1. Enable the **loginV2** feature (Console → instance Features, or Feature API)
|
|
2. Set the base URI, or leave empty to use `/ui/v2/login`
|
|
|
|
When the instance feature is on, it takes precedence over per-app checkboxes and applies to every application.
|
|
|
|
### Roll back
|
|
|
|
Disable the per-app setting or the instance feature while Login V1 is still available.
|
|
Use the break-glass `IAM_OWNER` PAT if interactive login is broken.
|
|
|
|
## 5. After cutover checklist
|
|
|
|
- IdP callbacks updated and tested
|
|
- SAML / attribute mapping: review Actions V2 needs for Login V2 where applicable
|
|
- Login V2 texts: customize via Settings API (not the old Console login text editor)
|
|
- OIDC apps that already use your ZITADEL issuer usually need **no** code changes
|
|
|
|
## Related
|
|
|
|
- [Hosted Login](/guides/integrate/login/hosted-login)
|
|
- [Create a Login Client](/self-hosting/manage/login-client)
|
|
- [Access System API](/guides/integrate/zitadel-apis/access-zitadel-system-api)
|
|
- [Upgrade from ZITADEL v3 to v4](/self-hosting/manage/upgrade-v3-to-v4)
|