4.0 KiB
4.0 KiB
ZITADEL Login App Guide for AI Agents
Context
The Login App (apps/login) provides the user interface for authentication flows (Login, Register, MFA, etc.). It is built with Next.js and React.
Key Technology
- Framework: Next.js (React).
- Styling: TailwindCSS, configured via
apps/login/tailwind.config.mjs. - Data Fetching: Primarily server-side interaction with ZITADEL APIs via
@zitadel/clientor direct gRPC calls where applicable. - Language: TypeScript.
Architecture & Conventions
- Routing: Uses the Next.js App Router (routes are defined under
src/app/). - Composability: Components should be small and reusable.
- State: Critical authentication state is often managed via URL parameters (Auth Requests) and cookies/sessions.
- Scope Rule: For shared API typings and client behavior, also read
packages/AGENTS.mdandproto/AGENTS.md.
Server Actions & Server-Only Code (critical — read before adding or changing a server function)
src/lib/actions/: only Server Actions. Every file starts with"use server", and every export is a public, unauthenticated POST endpoint, whether or not a component calls it. Treat every argument as attacker-controlled: derive the user, session and policy (lifetimes, link hosts, IdP identities) on the server from the caller's signed cookie and ZITADEL, never from the arguments.src/lib/server/: server-only code. Every file imports"server-only". Helpers that take identity, links or lifetimes as parameters belong here.src/lib/(top level): code shared with client components only."use server"is not allowed anywhere else, inline directives included. Thelogin/module-boundariesESLint rule (checks/eslint-module-boundaries.mjs) enforces the layout.- The build fails when the published actions differ from
checks/server-actions.allowlist.json(checks/server-actions.mjs). Adding an action means reviewing it and adding it there.
Base Path & Redirects (critical — read before touching any redirect logic)
- The login app is served under a non-root base path in production. ZITADEL Cloud and the official container image are built with
NEXT_PUBLIC_BASE_PATH=/ui/v2/login(seeapps/login/.env; the value is inlined at build time by Next.js). Never assume the app lives at the domain root. constructUrl()(src/lib/server/service-url.ts) prepends the base path and must ONLY ever receive root-relative paths (/loginname,/password?...). Passing an absolute URL glues the base path onto it and produces a broken redirect likehttps://<host>/ui/v2/loginhttps://login.microsoftonline.com/....- Some redirect targets ARE absolute URLs: IdP authorize URLs returned by
startIdentityProviderFlow, OIDC callback URLs fromcreateCallback, and SAML endpoints fromcreateResponse. When handling a redirect value that could be absolute, branch onisExternalUrl()first, validate absolute URLs withisSafeRedirectUri(), and pass them toNextResponse.redirect(server) /window.location.href(client) untouched. Canonical pattern:resolveLoginHintinsrc/lib/server/flow-initiation.tsandhandleServerActionResponseinsrc/lib/client-utils.ts. - An empty base path masks this whole bug class: with
NEXT_PUBLIC_BASE_PATHunset,new URL("" + absoluteUrl, origin)still parses the absolute URL correctly, so local setups without the base path won't reproduce base-path bugs. Always test redirect changes withNEXT_PUBLIC_BASE_PATH=/ui/v2/loginset, and verify the rawLocationheader (e.g.curl -I), not just browser behavior.
Verified Nx Targets
- Dev Server:
pnpm nx run @zitadel/login:dev - Build:
pnpm nx run @zitadel/login:build - Lint:
pnpm nx run @zitadel/login:lint - Test (all):
pnpm nx run @zitadel/login:test - Test (unit):
pnpm nx run @zitadel/login:test-unit - Test (integration):
pnpm nx run @zitadel/login:test-integration - Pack (Docker):
pnpm nx run @zitadel/login:pack— builds a local Docker imagezitadel/zitadel-login:local. Requires Docker daemon.