mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-31 19:42:15 +00:00
8dac4e2b54
# Which Problems Are Solved - Operators lack a single guide for separating instance-level principals (break-glass, login client) from tenant organizations. - Login policy and IdP behavior for platform accounts is easy to conflate with customer org settings when admins share one organization. - There is no documented procedure to inventory instance administrators or detect unexpected grants over time. # How the Problems Are Solved - Add Hardening instance administrators covering: - Dedicated platform organization layout and why login, password, and lockout policies matter for operator accounts. - Login client (`IAM_LOGIN_CLIENT`) and break-glass (`IAM_OWNER`) hygiene. - Periodic review with Internal Permission Service v2 `ListAdministrators` (instance and platform org filters). - Actions v2 webhooks for `instance.member.*` and `org.member.*` events (with payload interpretation and alert hints). - Event API polling alternative for SIEM/batch pipelines (`instance.member.*` and platform-org `org.member.*`). - Register the page in the docs sidebar under Roles & Permissions. - Cross-link from administrators, production checklists, login-client setup, and service account authentication guides. # Additional Changes - Clarify instance vs org IdP availability depends on effective login policy and linked providers (not automatic for all orgs). - Note deprecated Admin API `POST /admin/v1/members/_search` vs v2 `ListAdministrators`. # Additional Context - Operational hardening guide only (no product authz changes). --------- Co-authored-by: Cursor <[email protected]>
53 lines
3.1 KiB
Plaintext
53 lines
3.1 KiB
Plaintext
---
|
|
title: Connect your Self-Hosted Login UI to Zitadel
|
|
description: "Create a Personal Access Token for login client user with IAM_LOGIN_CLIENT role to connect self-hosted Login UI to ZITADEL API"
|
|
sidebar_label: Create a Login Client
|
|
---
|
|
|
|
To enable your self-hosted Login UI to connect to the Zitadel API, it needs a token for a user with the IAM_LOGIN_CLIENT role.
|
|
Place that service account in a dedicated organization for instance administrators and follow [Hardening instance administrators](/guides/manage/console/administrator-hardening) for least-privilege and login settings alignment.
|
|
|
|
On new installations, the Zitadel setup job can be configured to automatically write a Personal Access Token (PAT) for the login client.
|
|
Check out [one of the deployment examples](https://zitadel.com/docs/self-hosting/deploy/overview) to learn how to do this.
|
|
|
|
However, if you want to replace the v1 login of an existing installation by a self-hosted v2 login, the setup job won't execute these steps.
|
|
In that case, you can create a new PAT for the login client manually.
|
|
|
|
For the full cutover on an existing **v4** installation (routing, auth options, gradual vs instance-wide enablement), see [Adopt Login V2 on an existing installation](/self-hosting/manage/adopt-login-v2).
|
|
|
|
## Create a Login Client User
|
|
|
|
In the following URLs, replace the base URL and the user ID according to your environment.
|
|
|
|
1. Create a new service account, for example at http://localhost:8080/ui/console/users/create-machine
|
|
2. Create a PAT, for example at http://localhost:8080/ui/console/users/332169800719532035?new=true&id=pat
|
|
3. Save the PAT to a file, for example `/path/on/your/host/login-client.pat`
|
|
4. Make sure the user has the `Instance Login Client` role (internally called `IAM_LOGIN_CLIENT`), for example at http://localhost:8080/ui/console/instance/members
|
|
|
|
## Configure the Login UI
|
|
|
|
Make sure your Login UI has the environment variable `ZITADEL_SERVICE_USER_TOKEN` set with your PAT.
|
|
If you run the Login UI with Docker, you can also mount the file into the container and reference it by passing the environment variable `ZITADEL_SERVICE_USER_TOKEN_FILE`.
|
|
For example:
|
|
|
|
```bash
|
|
docker run -p 3000:3000 -v /path/on/your/host/login-client.pat:/path/in/container/login-client.pat:ro -e ZITADEL_SERVICE_USER_TOKEN_FILE=/path/in/container/login-client.pat ghcr.io/zitadel/zitadel-login:latest
|
|
```
|
|
|
|
## Enable the Login UI for all users
|
|
|
|
<Callout type="warn">
|
|
Before doing this, make sure you have a working PAT for an instance Owner user.
|
|
In case something goes wrong and you lock yourself out from the login screen, you can revert the changes.
|
|
Create a service account PAT like you created the [login client PAT above](#create-login-client), but give the user the instance Owner role (internally called `IAM_OWNER`).
|
|
</Callout>
|
|
|
|
Enable the `Login V2` feature flag, for example at the bottom of http://localhost:8080/ui/console/instance?id=features.
|
|
Enter the base URI of your Login UI, for example `http://localhost:3000/ui/v2/login`.
|
|
|
|
## Test
|
|
|
|
That's it!
|
|
Click your users avatar in the top right corner of the management console and select `Log in With Another Account`.
|
|
You should see the new Login UI.
|