--- 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 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. ## 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:///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)