# Which Problems Are Solved
- No documentation explained that the TOTP issuer name defaults to
"ZITADEL" and is not derived from the domain
- No documentation clarified how to change it on self-hosted (env var
only, Helm values don't work)
- No documentation communicated that it is not configurable on ZITADEL
Cloud
# How the Problems Are Solved
- Adds a callout in the MFA section of the default settings page
covering both self-hosted
(ZITADEL_SYSTEMDEFAULTS_MULTIFACTORS_OTP_ISSUER) and cloud (not
configurable, discussion link)
# Additional Changes
None
# Additional Context
- https://github.com/zitadel/zitadel/discussions/5453
Signed-off-by: Rajat Singh <rajat@zitadel.com>
Co-authored-by: Rajat Singh <rajat@zitadel.com>
## Summary
- Update the description frontmatter and reword "next generation" to
"next iteration" throughout
- Add a "What this means for existing customers" subsection after the
disclaimer, before the Strategic Roadmap section
- Convert `### **Strategic Investments**` / `### **Customer Outcomes**`
subheadings to bold text so they no longer appear in the TOC
- Rename the closing section to "Migration and Adoption" with updated
content
## Test plan
- [x] Diffed against source content to confirm all requested sections
match
- [x] Verified no remaining "next generation" occurrences
---------
Co-authored-by: Elina Sokolovska <elinasokolovska@Elinas-MacBook-Air.local>
Co-authored-by: Florian Forster <florian@zitadel.com>
Automatically generated PR resolving Knowledge Gap ID 34.
**Thread ID:** manual-1783339162398
**Action:** CREATE
**New File:** `content/docs/drafts/gap-manual-1783339162398.mdx`
### AI Summary
> Add a user migration guide for firebase to Zitadel
### Human Reviewer Instructions
> Firebase to Zitadel Migration Summary
> The Blocker: Incompatible Password Hashes
>
> Firebase uses a proprietary, modified scrypt algorithm requiring
project-specific keys.
>
> Zitadel supports standard algorithms but lacks a verifier for
Firebase's custom format.
>
> Result: Passwords cannot be directly imported. Firebase hashes must be
discarded.
>
> Strategy 1: Bulk Import & Password Reset (Standard)
> Requires users to set a new password on their first login.
>
> Export: Run firebase auth:export users.json --format=json.
>
> Map: Convert Firebase fields (e.g., localId) to Zitadel's schema.
>
> Import to Zitadel: Call the Zitadel import API.
>
> Action: Omit the hashedPassword object entirely.
>
> Action: Include "passwordChangeRequired": true in the JSON payload to
trigger a reset flow via email or login prompt.
>
> Strategy 2: Just-In-Time (JIT) Migration (Seamless)
> Migrates users transparently behind the scenes during an active grace
period.
>
> Intercept Login: Your backend captures the plain-text password during
login.
>
> Verify: Backend POSTs credentials to Firebase Auth REST API:
>
>
https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[WEB_API_KEY]
>
> Migrate to Zitadel:
>
> If Valid (200 OK): Create the user in Zitadel immediately using the
plain-text password (Zitadel will natively hash it).
>
> If Invalid (400): Reject login or check if the user is already in
Zitadel.
>
> Sunset: After the grace period ends, migrate remaining inactive users
using Strategy 1.
> (Note: Do not log plain-text passwords and strictly enforce HTTPS
during this phase).
---
🤖 **Need adjustments?**
Leave a comment below and tag **@zitadel-knowledge-bot** with your
requested changes, and I will automatically update the files and push a
new commit!
---------
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
- npm dependencies across the monorepo are behind current patch/minor
releases.
- Transitive dependencies are pinned to older versions by parent
packages (karma, nx, @changesets/cli, etc.).
- Console build fails after the Angular toolchain update because
`angular.json` references assets outside the workspace root.
# How the Problems Are Solved
- Bumps `@angular/*` to `^21.2.17` in console.
- Bumps `js-yaml` to `^4.2.0` in docs.
- Bumps `concurrently` to `^10.0.3` in login.
- Adds pnpm overrides for transitive deps that cannot be bumped directly
(ws, undici, minimatch, esbuild, dompurify, qs, and others).
# Additional Changes
- Removes 10 overrides that are no longer needed after parent packages
resolve to newer versions.
- Updates 4 existing overrides (`tar`, `js-yaml`, `dompurify`,
`brace-expansion`) to match current upstream ranges.
- 2 low-severity findings remain via the abandoned `raw-loader` package
in docs (peer dep resolution; no upstream fix without replacing
`raw-loader`).
- Fixes console build: replaced the `angular.json` asset glob
`../apps/docs/public/img/tech` with a `prebuild` script that copies tech
images into `src/assets/docs/img/tech`. **Verify at runtime that tech
images on project grant / integration pages still load.**
# Additional Context
- Overrides remain where parent packages still pin older transitive
versions.
- The `angular.json` asset path issue predates this PR (not introduced
by the Angular bump).
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Closes#12024
# Which Problems Are Solved
When the login flow is started with an
`urn:zitadel:iam:org:domain:primary:{domain}` scope, the resolved domain
suffix is lost if the user navigates through the account chooser (e.g.
clicking "Use another account"). This causes the login to fail with
"User not found" because the organization can no longer be resolved.
Additionally, the `hideLoginNameSuffix` branding setting was never
respected by the login app.
# How the Problems Are Solved
- Forward the `orgDomain` parameter through `gotoAccounts()` and the
`/accounts` page, so it survives navigation to `/loginname` — the same
way `organization` and `requestId` are already forwarded.
- Respect `BrandingSettings.hideLoginNameSuffix`: when enabled, the
`@domain.com` suffix is hidden from the input UI but still used
internally for user search.
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Removes the release cycle page and sidebar entry. Replaces the roadmap
page with updated strategic roadmap content and renames its sidebar
label to Roadmap.
---------
Co-authored-by: Elina Sokolovska <elinasokolovska@Elinas-MacBook-Air.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
# Which Problems Are Solved
1. **Secondary button hover effect** was rendering a solid white/gray
background instead of a subtle transparent overlay. The legacy
`bg-opacity-*` utility (e.g. `hover:bg-gray-500 hover:bg-opacity-20`)
doesn't compose with `bg-*` in Tailwind v4 — the opacity is ignored,
leaving a solid color. The same issue affected `ring-opacity-*` and
`border-opacity-*` across other components.
2. **Checkbox checkmark color** was hardcoded to white (`fill='white'`
in the SVG), ignoring the theme's primary contrast color. On themes with
a light primary color, the white checkmark was invisible.
# How the Problems Are Solved
1. Migrated all legacy opacity utilities to the Tailwind v4 slash
syntax:
- `hover:bg-gray-500 hover:bg-opacity-20` → `hover:bg-gray-500/20`
- `ring-primary-light-500 ring-opacity-60` → `ring-primary-light-500/60`
- `focus:ring-opacity-50` + `focus:ring-indigo-200` →
`focus:ring-indigo-200/50`
- Removed redundant `border-opacity-20` where `border-black/10` was
already applied
2. Replaced the static `background-image` checkbox SVG with a
`mask-image` + `::after` pseudo-element approach. The checkmark color
now uses `var(--theme-light-primary-contrast-500)` /
`var(--theme-dark-primary-contrast-500)`, so it dynamically follows the
theme's contrast color.
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Closes#11946
# Which Problems Are Solved
- OIDC redirect is broken when `Prompt.LOGIN` + `loginHint` is used —
the user lands on `/signedin` instead of being redirected to the OIDC
client's callback URL (fixes#11946)
# How the Problems Are Solved
- In `handleOIDCFlowInitiation`, the `Prompt.LOGIN` + `loginHint` code
path was passing `authRequest.id` (raw ID without `oidc_` prefix) to
`sendLoginname`. Without the prefix, `completeFlowOrGetUrl` does not
recognize the flow as OIDC and falls through to the "Regular flow" path,
redirecting to `/signedin` instead of calling `createCallback`. Fixed by
using the `requestId` parameter which already carries the `oidc_`
prefix.
# Additional Changes
- Standardized all request ID references in `handleOIDCFlowInitiation`
to consistently use the `requestId` parameter instead of reconstructing
it with `` `oidc_${authRequest.id}` ``. This eliminates the
inconsistency that caused the bug and prevents similar issues in the
future.
- Removed a redundant `if (authRequest.id)` guard in the LDAP redirect
path, since `requestId` is always present as a required parameter.
- Added regression tests verifying that `sendLoginname` receives the
`requestId` with the `oidc_` prefix in the `Prompt.LOGIN` + `loginHint`
code path.
Closes#11914
# Which Problems Are Solved
When an OIDC auth request includes an organization scope
(`urn:zitadel:iam:org:id:{id}` or
`urn:zitadel:iam:org:domain:primary:{domain}`), users with existing
browser sessions from *other* organizations were shown an empty Account
Selection page with no selectable accounts. The only option was to click
"Add another account", adding a confusing and unnecessary extra step.
This happened because the `/login` route checked `sessions.length` (all
browser sessions, unfiltered) to decide whether to enter the "reuse
existing session" branch. Inside that branch, `findValidSession`
correctly filtered by organization and returned no match — but the
fallback redirected to `/accounts`, which also filters by org and
rendered empty.
# How the Problems Are Solved
Before deciding to redirect to `/accounts`, pre-filter sessions by the
requested organization using the same logic already used by the accounts
page and `findValidSession`. If no sessions are eligible for the target
organization, redirect directly to `/loginname` instead.
This applies to both the **default prompt** and
**`prompt=select_account`** branches. For `select_account`, this matches
the behavior of major OIDC providers like Google and Microsoft, which
skip the account chooser and go straight to the login input when there
are no sessions to select from. The OIDC spec describes `select_account`
as enabling selection "amongst multiple accounts that they might have
current sessions for" — showing an empty picker serves no purpose.
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
- The documentation had no guidance for debugging auto-user-creation
failures caused by unexpected or missing claims from an external IdP,
leaving users without a path forward when they see a
`SetHumanProfile.GivenName` validation error during OIDC login.
# How the Problems Are Solved
- Adds a troubleshooting section to the Actions V2 response manipulation
guide explaining how to use the `RetrieveIdentityProviderIntent` webhook
to inspect `rawInformation` and identify claim key mismatches from the
external IdP.
# Additional Changes
- None
Signed-off-by: Rajat Singh <rajat@zitadel.com>
Co-authored-by: Rajat Singh <rajat@zitadel.com>
# Which Problems Are Solved
Zitadel exposes the secrets generator configuration through its admin
api. This allows instance admins to manage them on their own and they
can create overwrite the system / runtime defaults (incl. expiration).
This very much needed in multi-instance scenarios such as zitadel.cloud.
Currently the invite code configuration was not manageable through the
API, but only runtime config.
# How the Problems Are Solved
- added the `invite_code` type to the API allowing it to be set and
retrieved.
- added the type to console's management list
- added the type to be stored on instance setup
- change the `GetSecretGenerator` endpoint to fall back to the runtime
config if no config is stored on the instance itself
- ensure the `length` and at least one charset is enabled, return an
error otherwise
- expiry is not enforced, so 0 allows codes with no expiry (current
state)
# Additional Changes
None
# Additional Context
- closes https://github.com/zitadel/zitadel/issues/10474
# Which Problems Are Solved
When the registerUser server action failed during registration, all
errors from addHumanUser, createSessionWithRetry, and getUserByID
propagated as uncaught exceptions to the client component's generic
catch block, which always showed the same "Could not register user"
message. This made it impossible to distinguish between user creation
failures, session creation failures, and user lookup failures — both for
end users and in server logs.
# How the Problems Are Solved
Added .catch() handlers on the three gRPC calls in registerUser that log
the actual error and return null, allowing the existing null-check guard
clauses to return step-specific error messages (couldNotCreateUser,
couldNotCreateSession, userNotFound) through handleServerActionResponse.
This gives users more specific feedback and provides server-side logging
to narrow down the root cause of flaky signup failures.
# Which Problems Are Solved
- Native apps (mobile/desktop) use custom protocol schemes (e.g.
`myapp://callback`, `io.zitadel.app://auth`) as OAuth/OIDC redirect
URIs. The previous redirect-safety check in the login UI only allowed
`http:`/`https:` absolute URLs, so these custom-scheme callbacks were
wrongly rejected and native app login flows were broken.
- Even for valid external redirects, `router.push()` triggers an RSC
prefetch `fetch()` that is blocked by the CSP `connect-src 'self'`
directive for non-same-origin URLs, so navigation to
external/custom-protocol targets failed.
- SAML and OIDC callback URLs returned from the backend were not
consistently validated before being used for redirects/POSTs across the
various flow entry points.
# How the Problems Are Solved
- Reworked `isSafeRedirectUri` to use `@braintree/sanitize-url` instead
of a strict `http/https`-only allowlist. Custom protocol schemes are now
permitted, while dangerous schemes (`javascript:`, `data:`, plus an
explicit block of `file:`, `blob:`, `about:`) are still rejected.
- Added `isExternalUrl` helper to distinguish internal relative paths
(`/...`) from external/custom-protocol targets.
- In `handleServerActionResponse`, external/custom-protocol redirects
now navigate via `window.location.href` (full navigation) instead of
`router.push()`, avoiding the CSP-blocked RSC prefetch. Internal paths
continue to use `router.push()`.
- Added consistent redirect-URI validation for SAML and OIDC callbacks
across all relevant entry points (`oidc.ts`, `saml.ts`,
`server/flow-initiation.ts` including the `prompt=none` path, and the
SAML `samlData` POST case), blocking unsafe URLs with a clear warning
and error response.
# Additional Changes
- Added `@braintree/sanitize-url` (`^7.1.2`) dependency to `apps/login`
(`package.json` / `pnpm-lock.yaml`).
- Added unit tests for `isExternalUrl` covering relative paths, absolute
HTTP/HTTPS URLs, custom protocol schemes, and protocol-relative URLs.
- Annotated the intentional `window.location.href` navigation with a
CodeQL suppression comment, documenting that the URL is validated by
`isSafeRedirectUri` beforehand.
- Minor formatting cleanup in `console` JWT provider component.
# Additional Context
- This restores behavior that previously worked for native apps but
regressed when redirect validation was tightened to `http`/`https` only.
---------
Co-authored-by: Max Peintner <peintnerm@gmail.com>
# Which Problems Are Solved
Login v2 uses the `users.v2.ListUsers`-endpoint to get a user by login
name. This query had an inefficient `WHERE`-clause.
# How the Problems Are Solved
Update the view and use a specific clause for this query.
# Additional information
Added in https://github.com/zitadel/zitadel/pull/10475
---------
Co-authored-by: Marco A. <kwbmm1990@gmail.com>
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Automatically generated PR targeting 1 files.
**Thread ID:** 1517531035175354430
**Action:** UPDATE
**AI Summary:**
> Documentation does not explain what happens when users bookmark the
login page or access ZITADEL without an OIDC flow, particularly
regarding redirect behavior and the purpose of organization Default
Redirect URI settings.
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
# Which Problems Are Solved
This fixes a critical bug where initial verification emails (or invite
codes) were occasionally sent twice, invalidating the first code and
confusing users.
Previously, the initial verification email was triggered via a
`send=true` URL parameter executing inside a frontend useEffect exactly
when the `/verify` page mounted. This was fragile and prone to race
conditions caused by component remounts or partial hydration.
# How the Problems Are Solved
- Removed `send=true` from URL state and ripped out the doSend effect in
`VerifyForm.tsx`.
- Shifted execution strictly to the Next.js server. The email is now
automatically dispatched via await `initialSendVerification(...)` during
the POST requests (acting over `sendLoginname`, `register`, `password`,
`passkeys`, and `idp`).
- The login flow is now idempotent and robust against unintended
frontend re-renders.
- Refactored `checkEmailVerification()` to be async and updated the
associated unit-test coverage (all tests passing).
# Which Problems Are Solved
When using IDP auto-creation, the addHuman() call would fail if the IDP
didn't provide required profile fields (givenName or familyName),
resulting in a poor user experience.
# How the Problems Are Solved
Added validation before auto-creation to check if required profile
fields are present. If givenName or familyName is missing, users are now
redirected to the complete-registration page where they can manually
provide the missing information.
- Added profile field validation in CASE 4 (auto-creation) of
processIDPCallback
- Redirect to /idp/{provider}/complete-registration when required fields
are missing
- Pre-fill any available user data in the registration form
---------
Co-authored-by: David Skewis <david@zitadel.com>
Co-authored-by: Florian Forster <florian@zitadel.com>
Automatically generated PR targeting 1 files.
**Thread ID:** 1512031509387673610
**Action:** UPDATE
**AI Summary:**
> The documentation lacks clear explanation of how the 'Use new login
UI' checkbox and 'Custom base URL for the new Login UI' field work
together, including step-by-step configuration and troubleshooting
guidance.
---------
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Co-authored-by: fcoppede <fcoppede@gmail.com>
# Which Problems Are Solved
This improves the contrast of the “Processing authentication...” message
shown while Login V2 processes the IDP authentication flow.
The previous style used text-gray-600 without a dark-mode variant. This
color is hard-coded in the component and is not affected by the branding
colors, so users may see low contrast depending on the active
theme/background.
This PR updates the message text to use a higher-contrast light/dark
color pair.
---------
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Max Peintner <peintnerm@gmail.com>
Automatically generated PR targeting 1 files.
**Thread ID:** manual-1782237446658
**Action:** UPDATE
**AI Summary:**
> Need to add a note on this page to encourage users with active
subscriptions to link their github and Discord account because that will
help github issues get higher priority and discord threads as well
Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Closes#12182
# Which Problems Are Solved
Generic IDP buttons (OIDC, SAML, LDAP, JWT) used pl-20 to approximate
icon offset alignment, but since they have no icon, the text appeared
misaligned compared to branded IDPs (Google, Microsoft, Apple).
# How the Problems Are Solved
Replaced the left-padding hack with centered text so generic IDP names
display cleanly within the button.
before:
<img width="392" height="290" alt="Screenshot 2026-05-28 at 12 03 21"
src="https://github.com/user-attachments/assets/64c4e8eb-caec-4742-b61c-e3b0c5093dd7"
/>
after:
<img width="392" height="289" alt="Screenshot 2026-05-28 at 12 07 27"
src="https://github.com/user-attachments/assets/d1faf1f4-0aab-475f-8801-15b461e15da4"
/>
# Which Problems Are Solved
Enable FIPS 140-3 compliant build.
# How the Problems Are Solved
- Add runtime config validation, if the FIPS flag is enabled fail the
application when a non-compliant hasher is used, or throw a warning when
a legacy verifier is used
- Add a build matrix for FIPS certified build:
- Go binary is built with `GOFIPS140=certified`
- Login container uses a separate base:
[ubi9](https://catalog.redhat.com/en/software/containers/ubi9/ubi/615bcf606feffc5384e8452e)
from redhat which provides a FIPS certified OpenSSL (used by NodeJS TLS
stack)
- Non-FIPS images where already pushed to both Github Container Registry
and Google Artifact Repository (GAR). Fips images are only pushed to the
GAR.
- Tag versions are suffixed `-fips`. So on release the following images
will be additionally available:
```
europe-docker.pkg.dev/zitadel-common/zitadel-repo/zitadel-login:vX.Y.Z-fips
europe-docker.pkg.dev/zitadel-common/zitadel-repo/zitadel:vX.Y.Z-fips-debug
europe-docker.pkg.dev/zitadel-common/zitadel-repo/zitadel:vX.Y.Z-fips
```
# Other changes
- Bumb Go toolchain. At least v1.25.10 is required for a
GOFIPS140=certified setting.
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/4335
- Build [test
run](https://github.com/zitadel/zitadel/actions/runs/27253916052)
pushing FIPS and non-FIPS images
Closes#11200
# Which Problems Are Solved
Custom fonts uploaded via the branding/label policy were not supported.
# How the Problems Are Solved
- The login now correctly applies the branding settings, based on the
organization context
- Use the absolute `fontUrl` from the branding API directly in the
`@font-face` `src`, matching how logo and icon assets are already loaded
via absolute URLs.
- Add the Zitadel service URL to the `font-src` CSP directive so the
browser permits loading the cross-origin font.
# Additional Changes
- Updated CSP tests to reflect the new `font-src` behavior.
# Which Problems Are Solved
The local `isSessionValid` in `passkeys.ts` only checked `password` and
`webAuthN` factors, so sessions authenticated via an external IDP
(`intent` factor) were treated as invalid. This caused a "You have to
authenticate" error when redirecting to `/passkey/set` after IDP login.
# How the Problems Are Solved
Added `session.factors.intent.verifiedAt` to the validity check,
consistent with the canonical `isSessionValid` in `session.ts`.
<!--
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
The projects setting texts and sceenshot where outdated.
# How the Problems Are Solved
Update the text and screenshot.
# Additional Changes
* Rewording
* Lockout warning component
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
`backed/v3` tests are flaky, but the code is not productive. Development
is paused for the moment. Disabling flaky tests helps us to maintain the
product easier.
# How the Problems Are Solved
- Removed 'events_testing' from the integration test command in both
`CONTRIBUTING.md` and `apps/api/project.json` to streamline the testing
process.
- Adjusted the command to ensure it only includes relevant integration
tests, improving clarity and focus for contributors.
After user registration, the backend projections may not be up to date
yet when the Login UI immediately tries to create a session. This
results in a `QUERY-Dfbg2` ("User could not be found") error even though
the user was created successfully.
This adds retry logic with backoff (500ms/1s/2s, up to 3 attempts)
around `createSessionAndUpdateCookie` in the registration flow. Only
`NotFound` errors are retried — other errors are thrown immediately.
Closes#12173
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
# Which Problems Are Solved
Pages in `apps/docs` that embed source from GitHub via the Docusaurus
convention
````
```js reference
https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js
```
````
stopped working after the migration from Docusaurus to fumadocs. The old
`docusaurus-theme-github-codeblock` plugin used to fetch the file and
render it; fumadocs has no support for that meta, so the page rendered
the raw URL as plain code-block text. Visible at
`/docs/apis/actions/code-examples` and 16 other pages.
# How the Problems Are Solved
- Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46
total across 17 `.mdx` files) to the native fumadocs JSX form:
`<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>`
collapsibles around blocks are kept — they're an authoring choice, not
part of the rendering bug.
- Updated `apps/docs/components/github-code-block.tsx` to render via
`DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock`
(proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which
produced unhighlighted output). Also fixed language detection so a URL
hash like `#L10-L20` no longer pollutes the language token.
- Registered `GithubCodeBlock` globally in
`apps/docs/mdx-components.tsx`, matching how every other shared
component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`,
`TerminologyUpdate`) is exposed. MDX files no longer need a local
`import`.
# Additional Changes
- Normalized the two MDX files that were already using the JSX form
(`examples/secure-api/python-django.mdx`,
`examples/secure-api/java-spring.mdx`): removed their now-redundant
local `import { GithubCodeBlock }` and rewrote 9 long-form
`<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for
consistency.
# Additional Context
Verified locally with `pnpm --filter @zitadel/docs dev`:
- `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks
rendered inside the `<details>` collapsibles (was 0).
- `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`)
honored.
- `/docs/examples/login/flutter` — mixed languages (xml/dart/html)
detected and highlighted.
- `/docs/guides/integrate/external-audit-log` — edge case of fenced
reference indented inside a numbered list also converted and rendered.
Greps:
- `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx`
→ 0 matches.
- `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches.
- `from '@/components/github-code-block'` in
`apps/docs/content/**/*.mdx` → 0 matches.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
# Which Problems Are Solved
When MFA is enforced with only Email OTP as a second factor, new users
hit a dead end on the MFA setup screen. The `ChooseSecondFactorToSetup`
component hides Email OTP when `emailVerified` is `false`, and if email
verification was skipped earlier in the flow (e.g. `EMAIL_VERIFICATION`
env not set to `"true"`), no MFA options are visible and the user cannot
proceed.
# How the Problems Are Solved
In the MFA setup server component (`mfa/set/page.tsx`), before
rendering, detect when forced MFA has no visible second factors because
all configured factors require verification the user hasn't completed.
When Email OTP is configured but the user's email is unverified,
redirect to `/verify` with `send=true` so a verification code is sent
immediately.
After the user verifies their email, the existing flow in `verify.ts`
calls `checkMFAFactors` which redirects back to `/mfa/set` — where Email
OTP is now visible since `emailVerified` is `true`.
The redirect pattern follows the existing precedent in
`authenticator/set/page.tsx`.
# Additional Changes
None
# Additional Context
- Closes#11536
---------
Co-authored-by: Max Peintner <max@caos.ch>
## Description
This PR updates the Kubernetes deployment documentation to address user
feedback regarding our routing instructions. A user noted that standard
`Ingress` is becoming outdated and requested configuration examples for
the modern Gateway API.
To support both existing and modern clusters, I have updated the guide
to provide two clear pathways for exposing ZITADEL.
## Changes Included
* **Prerequisites updated:** Mentioned Gateway API controllers alongside
standard Ingress controllers.
* **Refactored Stage 2 (Production):** Split the routing configuration
into "Option A: Standard Ingress" and "Option B: Gateway API".
* **Added YAML example:** Provided a sample `HTTPRoute` resource to
route traffic to the `zitadel` and `zitadel-login` backend services.
* **Terminology updates:** Broadened terms like "Ingress" to "Routing"
or "Routing controller" where applicable.
Closes#12125
# Which Problems Are Solved
The proxy middleware (proxy.ts) did not apply `CUSTOM_REQUEST_HEADERS`
to rewritten requests (/.well-known/*, /oauth/*, /oidc/*, etc.). When
`ZITADEL_API_URL` points to an internal service name, the Host header on
proxied requests remained the internal name instead of the configured
public domain, causing Errors.Instance.NotFound.
# How the Problems Are Solved
The other two outgoing request paths — the connectRPC transport and the
security-settings fetch — already applied these headers. This adds the
same applyCustomHeaders() call to the proxy path.
Co-authored-by: Ramon <mail@conblem.me>
<!--
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
Outdated depdencies
# How the Problems Are Solved
This PR mostly just updates our NPM depdencies to the newest feature
releases.
The UUID package was update to version 14, the changelog only includes
changes to the supported node version.
# Additional Changes
Replace tsx for some scripts in the docs.
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Co-authored-by: Max Peintner <max@caos.ch>
# Which Problems Are Solved
- Login V2 signup does not resolve the `{{.Lang}}` placeholder in ToS,
Privacy Policy, and help links.
- Clicking those links on the registration page can open URL-encoded
placeholders like `%7B%7B.Lang%7D%7D` instead of the active
language-specific page.
# How the Problems Are Solved
- Adds a small login utility to resolve `{{.Lang}}` placeholders against
the active Login V2 locale.
- Updates the signup legal acceptance component to use the resolved
links before rendering them.
- Applies the same resolution to the optional help link shown alongside
the legal acceptance text.
# Additional Changes
- Adds unit tests for the link placeholder resolver.
- Adds a component test covering localized ToS, Privacy Policy, and help
links on the signup page.
# Additional Context
- Closes#11907
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Max Peintner <peintnerm@gmail.com>
# Which Problems Are Solved
- Logo and heading overlap on login pages due to a -mb-4 negative margin
on the logo container
- The /login route returns a 500 when `listSessions` fails (e.g. stale
session cookies), because loadSessions has no error handling.
- The proxy logs `"fetch() returned undefined"` because
`fetchIframeOrigins` returns undefined, which lru-cache's forceFetch
treats as a fetch failure.
# How the Problems Are Solved
- Remove `-mb-4` from the logo container in DynamicTheme.
- Wrap `loadSessions` in a try/catch — failures fall through as empty
sessions instead of crashing.
- Return `null` instead of `undefined` from `fetchIframeOrigins` so
lru-cache caches it normally.
---------
Co-authored-by: Livio Spring <9405495+livio-a@users.noreply.github.com>
Co-authored-by: conblem <mail@conblem.me>
## Summary
- Switch the docs catch-all route to full static generation and prebuild
both latest and versioned docs paths.
- Prebuild OG images for all docs pages, make sitemap and LLM export
static, and remove nondeterministic sitemap timestamps.
- Reduce build-time overhead by memoizing docs sidebar trees and
skipping processed markdown generation for versioned docs.
## Testing
- `pnpm nx run @zitadel/docs:build`
- `pnpm nx run @zitadel/docs:lint`
- `pnpm nx run @zitadel/docs:check-types`
- Verified the prerender manifest contains 8,816 prerendered routes,
3,293 versioned docs routes, 4,406 OG routes, and zero revalidating docs
routes.
This PR updates the "Private Key JWT Auth for Service Accounts"
documentation to explicitly clarify the relationship between the exp
(expiration) and iat (issued at) claims.
Previously, the documentation didn't make it clear what happens if a
developer sets an exp claim far into the future. This update clarifies
that while the exp value is strictly enforced, the iat claim takes
precedence if the exp is set to more than 1 hour in the future (i.e.,
ZITADEL will reject the JWT once the iat is older than 1 hour,
regardless of the exp time).
**Changes included:**
Updated the description of the exp claim in the JWT payload section to
highlight the 1-hour iat limit enforcement.
# Which Problems Are Solved
The Vercel `docs` project generated ~64M ISR writes over 30 days (99.5%
of ISR writes across all projects, ~\$258/month).
Root causes in the Next.js 16 docs app:
- `apps/docs/app/[[...slug]]/page.tsx` had `dynamicParams = true` +
`revalidate = 3600`. Bot traffic hitting unknown URLs (`/docs/wp-admin`,
`/docs/.env`, fuzzed paths) got rendered via \`notFound()\`, and the 404
response was cached as an ISR entry — 1 write per unique bad URL. Known
pages were also rewritten hourly for no reason since content only
changes on deploy.
- `apps/docs/app/og/docs/[...slug]/route.tsx` had `revalidate = false` +
empty `generateStaticParams()` + implicit `dynamicParams = true`. Every
unique OG URL (including bot probes) was cached forever — writes
accumulated permanently.
# How the Problems Are Solved
Switch the docs routes to pure SSG (content is static and only changes
on deploy, so ISR provides no value):
- `app/[[...slug]]/page.tsx`: `dynamicParams = false`, `revalidate =
false`, `dynamic = 'force-static'`. Unknown URLs now return a static 404
at the CDN — no function invocation, no ISR write. All 390 pages from
`source.generateParams()` are still pre-rendered.
- `app/og/docs/[...slug]/route.tsx`: `generateStaticParams()` now
returns all 390 pages via the existing `getPageImage(page).segments`
helper, so every OG image is pre-built as a static asset. `dynamicParams
= false` + `dynamic = 'force-static'` locks it down.
- `app/llms-full.txt/route.ts`: added `dynamic = 'force-static'` as a
safety net (already `revalidate = false`, single URL).
The tradeoff is longer CI builds (~40s–2min for 390 OG image
generations, paid on every preview deploy) in exchange for eliminating
~\$258/month in ISR writes plus associated function invocations and CPU
time.
# Additional Changes
None.
# Additional Context
- No changes to `next.config.mjs`, `vercel.json`, or redirects.
- Existing `apps/docs/redirects.json` (3,261 entries) covers legacy URLs
so `dynamicParams = false` won't 404 moved pages linked from elsewhere.
- Versioned routes: `content/versions.json` and `v*/` folders don't
exist yet. When versioning is activated, `generateStaticParams()` in
both files must also include `versionSource.generateParams()` —
otherwise versioned URLs will 404 under `dynamicParams = false`.
## Test plan
- [ ] CI build succeeds (expect modest build-time increase for OG
pre-generation)
- [ ] Inspect `apps/docs/.next/prerender-manifest.json` — all 390 doc
routes + 390 OG routes listed with `initialRevalidateSeconds: false`
- [ ] Local smoke: `/docs` → 200, `/docs/wp-admin` → 404 (static, no
function), `/docs/og/docs/guides/start/image.png` → PNG,
`/docs/og/docs/bogus/image.png` → 404
- [ ] Post-deploy: Vercel **ISR Writes** metric drops to near-zero
within 24h
- [ ] Post-deploy: Vercel **Function Invocations** for `/og/docs/*` drop
to zero
- [ ] Verify no legitimate docs pages 404 (cross-check logs against
`apps/docs/app/sitemap.ts`)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
# Which Problems Are Solved
1. SSL/TLS handshake failures on Cloud Run (middleware self-loopback)
PR #11903 changed the middleware (proxy.ts) to fetch security settings
via fetch(origin + "/security") on every request, including non-proxy
routes like /login. On Cloud Run, this self-loopback goes through the
Google Front End (GFE) load balancer, causing intermittent SSL
routines::record layer failure errors that were tenant-consistent.
2. The ClassifiedConnectError introduced in #11926 set this.name =
"ClassifiedConnectError", which broke ConnectError's custom
Symbol.hasInstance duck-typing check (v.name === "ConnectError"). This
caused ConnectError.from() inside the connectRPC transport's abort
handler to re-wrap classified errors as new ConnectError instances with
Code.Unknown — losing the original gRPC error code and all
classification metadata.
# How the Problems Are Solved
Middleware: eliminate self-loopback fetch:
- Replaced the fetch(origin + "/security") self-loopback with a direct
fetch to ZITADEL_API_URL using the Connect protocol (POST + JSON),
bypassing the load balancer entirely
- Security settings are cached in-memory with a 1-hour TTL per instance
host
- Extracted the fetching/caching logic into
src/lib/server/security-settings.ts
Removed the now-unused /security API route (src/app/security/route.ts)
- CSP headers with iframe origins are now applied to all routes without
any loopback
Error classification interceptor: fixed
- Keep this.name = "ConnectError" in ClassifiedConnectError so the
duck-typing Symbol.hasInstance check passes
- The branded Symbol.for check via isClassifiedError() still correctly
distinguishes the subclass
- Remove redundant Object.setPrototypeOf call (the super constructor
already handles it via new.target)
- Replace remaining instanceof ConnectError checks with
isClassifiedError() in setUserPassword and checkSessionAndSetPassword
<!--
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
When creating a new Project Grant in the Zitadel console, the UI becomes
extremely sluggish/unusable. The issue appears tied to the organization
search dropdown attempting to load a very large dataset.
# How the Problems Are Solved
The refactored `SearchOrgAutocompleteComponent` uses server side
filtering and ondemand loading using infinite scrolling. This makes sure
on a subset of organizations is ever loaded on the client.
# Additional Changes
- Added tailwindcss for easier styling
- Removed build warnings
- Removed some of the SCSS syntax warnings
# Additional Context
- Closes#11121
---------
Co-authored-by: Max Peintner <max@caos.ch>
2026-04-22 11:46:27 +02:00
Tim Möhlmanncopilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>muhlemmer
# Which Problems Are Solved
Opaque tokens now use authenticated encryption.
# How the Problems Are Solved
- Upgrade zitadel/oidc to v3.47
- Copy crypto implementation for refresh and session tokens (internal to
zitadel)
- Added config that allows validating old tokens for gradual roll-out
# Additional Changes
- Set NX cache for `integration-test-build` to `false`, working on a
seperate fix.
# Additional Context
- closes#11315
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: muhlemmer <5411563+muhlemmer@users.noreply.github.com>
Rajat SinghandRajat Singh
dependabot[bot]anddependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Max PeintnerandLivio Spring
zitadel-knowledge-bot[bot]andzitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Tim Möhlmann
Marco A.andLivio Spring
MaximilianandCopilot Autofix powered by AI
Liam NevilleandMax Peintner
