From 6bcdb27e17e7f39dc17b797ccf4bbddfecbf0a9b Mon Sep 17 00:00:00 2001 From: Rajat Singh <17253992+rajatcing@users.noreply.github.com> Date: Mon, 13 Jul 2026 13:37:43 +0200 Subject: [PATCH] docs: document TOTP issuer name configuration for self-hosted and cloud instances (#12335) # 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 Co-authored-by: Rajat Singh --- .../content/guides/manage/console/default-settings.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/apps/docs/content/guides/manage/console/default-settings.mdx b/apps/docs/content/guides/manage/console/default-settings.mdx index 10de697e9..6e5261520 100644 --- a/apps/docs/content/guides/manage/console/default-settings.mdx +++ b/apps/docs/content/guides/manage/console/default-settings.mdx @@ -197,6 +197,13 @@ Force a user to register and use a multifactor authentication, by checking the o Ensure that you have added the MFA methods you want to allow. Or you can enable the "Force MFA for local authenticated users", which will enforce this rule only on local authentication, but not on users authenticated through an Identity Provider. + +The issuer name shown in authenticator apps (e.g. Google Authenticator, Authy) when users register TOTP defaults to **ZITADEL**. It is not derived from your domain or instance name. + +- **Self-hosted:** Set the environment variable `ZITADEL_SYSTEMDEFAULTS_MULTIFACTORS_OTP_ISSUER=YourName`. Note that setting this via Helm values (`SystemDefaults.Multifactors.Issuer`) does **not** work — the raw environment variable must be used directly. +- **ZITADEL Cloud:** The TOTP issuer name is not currently configurable. You can follow and upvote [this discussion](https://github.com/zitadel/zitadel/discussions/5453) to track progress. + + ### Login Lifetimes Configure the different lifetimes checks for the login process: