SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

ZitadelをVPSでセルフホストする手順と推奨スペック

ZitadelをDockerで構築する方法を解説します。本体のメモリ消費量は約512MBですが、PostgresやSMTP設定、マスターキー管理、バックアップ運用が必須です。アップグレード時のデータベース挙動や本番環境に必要なリソース目安を整理しました。

VPS で Zitadel をセルフホストするために必要なもの

VPS で Zitadel をセルフホストするには、Docker ホスト、VPS を指す公開 DNS 名、PostgreSQL、そして両方を動かすための十分な CPU と RAM が必要です。Zitadel の本番環境向けガイドでは、アプリケーション自体に必要なメモリを約 512 MB、CPU を 1 コア未満としています。増加しやすいのはデータベースとパスワードハッシュ計算に必要なリソースです。Zitadel は identity provider です。OIDC (OpenID Connect) と SAML (security assertion markup language) でトークンを発行するため、他のサービスで個別にユーザー一覧を管理する必要がなくなります。インストールは curl と docker compose up です。正常に運用を継続できるかどうかを左右するのは、masterkey、データベースユーザー、SMTP (simple mail transfer protocol)、バックアップ、そして最初のアップグレードです。

以下はすべて、Ubuntu 24.04、Compose plugin version 2.24.4 以上を備えた Docker Engine 24 以上、および auth.example.com のような名前がすでにサーバーを指していることを前提とします。TLS オーバーレイでは !override を使用します。この機能にはその Compose version が必要です。

Zitadel にはどの程度の VPS が必要ですか?

Zitadel のドキュメントにある Compose のクイックスタートでは、2 GB の RAM を求めています。この数値はクイックスタート向けです。Zitadel の本番運用ガイドでは、別の数値が示されています。

グラフZitadel's own published sizing guidance, October 2026
このグラフのデータ
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

これらは公開されている推奨値であり、稼働中のサーバーで測定した値ではありません。必要なリソースの構成を示す目安として読んでください。Zitadel のプロセス自体は小規模です。ガイドでは約 0.5 GB の RAM とされ、CPU コアは 1 未満でも動作すると説明されています。CPU コアが必要なのは、意図的に低速なパスワードハッシュ処理のためです。そのため、ログインが集中すると CPU 使用率が急増します。ガイドでは、Zitadel 用に 4 CPU コアを確保することを推奨しています。もう一方の大きな要素は PostgreSQL です。同じガイドでは、100 requests per second あたり約 1 コア、1 コアあたり 4 GB の RAM を見積もっています。

大きい方の 2 つの行は、単一サーバー向けの数値ではありません。最小構成の高可用性環境として、ガイドでは 3 ノードのクラスタを推奨しています。各ノードは 4 コアと 16 GB を備えます。ログ収集とメトリクスを省けば、各ノードを約 4 コアと 8 GB まで減らせるとも説明されています。単一ノード向けのサイジングは示されていません。

したがって、2 GB の VPS でもこのスタックは起動します。ただし、実際のトラフィックが発生すると、ガイドがデータベースだけに見積もる量を大きく下回ります。ログインは、他のすべてのサービスが依存するサービスです。これが停止すると、これを信頼するサービスは誰もログインさせられません。認証に対して、ガイドが示すデータベースとハッシュ処理の予算は大きすぎると判断するのは妥当です。その判断は、移行後に行うより今行う方がはるかに安く済みます。Keycloak、Authentik、Zitadel の比較では、それぞれに必要なメモリと運用作業を扱っています。また、セルフホストの Authentik サーバーは、より小規模なサーバーで一般的に選ばれる回答です。

スタックを取得してバージョンを固定する

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

このファイルでは、実際に起動する 4 つのサービスを定義しています。Traefik はリバースプロキシです。パスに基づいてルーティングし、後述のオーバーレイを使用すると TLS (transport layer security) を終端します。zitadel-api は port 8080 で待ち受ける Go バイナリです。zitadel-login は /ui/v2/login で提供されるログインインターフェースです。postgres がすべてを保持します。Redis キャッシュと OpenTelemetry collector も同じファイルに定義されていますが、Compose profiles の背後にあるため、明示的に有効にするまで起動しません。

まだ docker compose up は実行しないでください。最初の起動で instance が作成され、その後は以下のいくつかの設定を追加作業なしで変更できなくなります。

コピーした .env では、使用する image tag が固定されています。

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

現在の v4 release は v4.20.3 です。これは 13 November 2026 にリリースされ、配布されたファイルで固定されているバージョンより minor version で 4 つ先です。v4.20.0 より前の release である v4.19.5 は 15 October 2026 のもので、Zitadel の technical advisory A-10018 の対象となる最初の release です。影響を受ける list endpoint では、v1 API と v2 API にデフォルト値と最大値が適用されるようになりました。そのため、limit なしで一覧を取得する client はすべての結果を受け取らず、pagination が必要になります。また、最大値を超える件数を要求した request は拒否されます。v4.20.0 を含む、それ以降のすべての release にこの変更が含まれています。実行するバージョンを ZITADEL_VERSION に設定し、最新のバージョンを追跡するのではなく v4 系列に留めてください。手動でバージョンを選ぶ場合は v4.18.0 を省略してください。その release notes には、そのバージョンでは setup step が失敗するため、代わりに v4.19.0 を使用するよう記載されています。上記の curl は main branch から docker-compose.yml を取得しますが、その branch ではバージョンが固定されていません。そのため、両方のファイルのコピーを git repository に commit してください。そうしないと、来月に新しいマシンで同じ command を実行したとき、別のファイルが取得されても何が変わったのか分からなくなります。

.env の LOGIN_SESSION_COOKIE_SECRET を、openssl rand -base64 32 で生成したランダムな値に置き換えてください。Login UI はこの値を使用して session cookie に署名します。v4.19.5 release notes でも、例の値をそのまま使用しないよう明確に警告しています。

Postgres 専用のユーザーと実際のパスワードを設定する

同梱の .env は、スーパーユーザーとして PostgreSQL に接続する Zitadel の設定になっており、パスワードは postgres です。

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

ここでのハードニング手順には注意点があります。Zitadel のドキュメントでは POSTGRES_ZITADEL_PASSWORD を .env に追加するよう指示されています。しかし、ベースとなる docker-compose.yml はその変数を読み取らないため、設定しても何も変わりません。一方、POSTGRES_ADMIN_PASSWORD だけを変更すると接続に失敗します。パスワードは DSN(データソース名)文字列内にも直接記述されているためです。Zitadel の接続方法を決めるのは、この DSN の行です。

.env.example のコメントには、残りの動作も明記されています。DSN を設定すると、Zitadel はそのユーザーを直接使用し、権限の低いユーザーを自動作成しません。そのため、最初の起動前にロールを作成しておく必要があります。ロール用のパスワードを生成し、Postgres の起動前に POSTGRES_ADMIN_PASSWORD へ別のランダムなパスワードを .env に設定します。その後、Postgres だけを起動してロールを作成します。Postgres イメージが管理者パスワードを適用するのは、空のデータディレクトリを初期化するときだけです。既存のデータベースに対して後から .env を変更しても、パスワードは変更されません。

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

これらの psql 呼び出しは、コンテナ内のローカルソケット経由で実行されます。公式の Postgres イメージはこの接続を信頼するため、パスワードは要求されません。重要なのは所有権です。Zitadel の初期化処理は、独自のスキーマ(eventstore、projections、system)とテーブルを作成します。データベースの所有権により、ロールはこれらのスキーマを初期化するために必要な CREATE 権限を持ちます。PostgreSQL 15 で public スキーマに対する CREATE 権限の扱いが変更されたことは別の問題であり、Zitadel のスキーマ初期化が失敗することを意味しません。

次に DSN を新しいロールへ向け、Postgres の起動前に設定した管理者パスワードはそのまま保持します。

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable は、プライベートな Compose ネットワーク上でデータベース接続を暗号化しません。ポートがホストへ公開されることもありません。Zitadel のデータベースガイドでは、本番環境のデータベース接続に TLS を推奨しています。最初の完全な起動後に、ロールが実際にデータを所有していることを確認します。

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

ここでは eventstore スキーマ、projections スキーマ、system スキーマが表示されるはずです。これらのスキーマがない場合、初期化処理はそこまで到達していません。API コンテナのログに原因が出力されます。

マスターキーと、失った場合の影響

Zitadel は、保存する前にシークレットを暗号化します。対象には、IdP の認証情報、SMTP パスワード、ワンタイムパスワードのシード、マシンキーが含まれます。マスターキーは、これらすべてのロックを解除します。長さは正確に 32 bytes です。ドキュメントにも明記されているとおり、マスターキーは変更できません。変更すると、暗号化データにアクセスできなくなります。

マスターキーを 1 つ生成し、.env のプレースホルダー行を置き換えます。

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters の行を編集してください。2 行目を追加してはいけません。Compose は同じキーが複数ある場合、最後の定義を使用するため、追加しても動作します。しかし、マスターキーの行が 2 つあるファイルは、次に読む人を混乱させます。

次に、そのキーの保存場所を確認します。compose ファイルは、次のように API コンテナを起動します。

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

そのため、マスターキーはコンテナのコマンドラインに置かれます。docker inspect にアクセスできるユーザーであれば、その値を確認できます。単一の管理者が運用する VPS では、この方法は許容できる場合があります。ディスク上のキーは、.env の mode によって保護されます。許容できない場合は、キーをファイルとしてマウントし、代わりに --masterkeyFile /run/secrets/zitadel-masterkey を使用してください。これにより、値がプロセス引数に含まれなくなります。

初回起動の前に、マスターキーをパスワードマネージャーへコピーしてください。マスターキーはデータベースダンプには含まれません。そのため、別のマスターキーでダンプを復元すると、インスタンス自身のシークレットを読み取れなくなります。ダンプを保存したアーカイブとは別の場所に保管してください。バックアップを 1 つ盗まれただけで、暗号化データとそのキーの両方を取得されないようにするためです。

最初の起動前に外部ドメインを設定する

ZITADEL_DOMAIN は .env を介してコンテナ内の ZITADEL_EXTERNALDOMAIN に渡され、ユーザーが入力する名前になります。Zitadel はこの値から OIDC issuer、ログイン画面のベース URI、SAML エンドポイント、最初の管理者のログイン名を生成するため、単なる表示上の設定ではありません。

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel は Host ヘッダーから、接続先のインスタンスを判別します。このヘッダーが認識済みのドメインと一致しない場合、すべてのリクエストに同じ応答を返します。

ID=QUERY-1kIjX Message=Instance not found

このエラーが表示されたら、2 点を確認してください。ZITADEL_DOMAIN がアクセス先の名前になっていないか、または前段のプロキシが Host を upstream のアドレスに書き換えていないかを確認します。名前ではなくサーバーの IP アドレスにアクセスした場合も、このエラーが発生します。

これらの値は後から変更できます。ただし、変更を反映するには Zitadel のセットアップ処理を再実行する必要があり、登録済みの各アプリケーションには古い redirect URI が残ります。最終的に使用する名前を今決めておく方が、後から移行するよりもはるかに手間がかかりません。

Let's Encrypt オーバーレイで TLS を終端する

公開ドメインでは、Zitadel の Let's Encrypt オーバーレイを追加します。このオーバーレイにより、Traefik は ACME(自動証明書管理環境)の HTTP チャレンジを使用し、公開ポートは 80 と 443 に置き換えられます。そのため、サーバー上のほかのプロセスがこれらのポートを使用していてはなりません。

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

このオーバーレイは API コンテナに ZITADEL_EXTERNALPORT: 443 と ZITADEL_EXTERNALSECURE: true も設定します。これにより、公開 URL と Zitadel が自身のために生成する URL が一致します。開始前に A レコードが名前解決できなければなりません。A レコードがないと HTTP チャレンジは失敗します。

すでに nginx またはロードバランサーで TLS を終端している場合は、代わりに docker-compose.mode-external-tls.yml を使用し、TRAEFIK_TRUSTED_IPS にはプロキシが送信元として使用する範囲を設定します。Traefik は、その一覧に含まれるアドレスからの X-Forwarded-* ヘッダーだけを信頼します。このオーバーレイは、Zitadel の外部 URL とログイン URL を HTTPS に明示的に設定します。

上流プロキシには、Zitadel が厳密に要求する役割が 2 つあります。API は gRPC を使用するため、バックエンドとは HTTP/2 で通信する必要があります。また、Host を X-Forwarded-Proto: https とともに変更せずに転送する必要があります。この Compose スタックでは、nginx の設定は次の形になります。

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

上流のプレースホルダーは、nginx から到達できるアドレスに置き換えます。Zitadel を 443 以外のポートで提供する場合は、ポートもヘッダーに含めるために grpc_set_header Host $host:$server_port; を使用します。それ以外は通常の仮想ホストです。Zitadel 固有でない部分については、nginx リバースプロキシ設定を 1 行ずつ読むで説明しています。

最初の管理者とパスワード変更の強制

初回起動時に、1つのインスタンス、1つの組織、および1人の管理者が作成されます。ログイン名は zitadel-admin@ と zitadel.、そして外部ドメインを組み合わせたものになります。ZITADEL_DOMAIN=auth.example.com を使用する場合、以下のようになります。

zitadel-admin@zitadel.auth.example.com

パスワードは、独自に設定しない限り Password1! です。Zitadel のアップストリームのデフォルトでは初回ログイン時にパスワード変更が強制されますが、提供されている compose ファイルではそのデフォルト設定が上書きされています。

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

この行は .env から読み込まれるのではなく docker-compose.yml にハードコードされているため、独自の値は別の小さなオーバーレイファイルに記述してください。ファイル名を docker-compose.local.yml とします。

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

Compose は -f フラグを指定せずに実行した場合のみ自動的に docker-compose.override.yml を読み込みますが、Zitadel のガイド内のすべてのコマンドは -f を渡すため、この自動読み込みは無効化されます。フラグを毎回指定する代わりに、.env でファイルリストを固定します。

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

次に起動します。

docker compose pull
docker compose up -d --wait

--wait はヘルスチェックが通過するまでコマンドの実行を待機します。API コンテナが正常に起動しない場合、Compose は dependency failed to start: container zitadel-zitadel-api-1 is unhealthy で停止し、docker compose logs zitadel-api にその理由が記録されます。コンテナ名はプロジェクト名に基づいて命名され、提供されている compose ファイルはトップレベルの name: zitadel でそれを設定しているため、ディレクトリ名は反映されません。初回起動時に失敗する場合、その原因は通常、マスターキーの長さまたはデータベースの DSN です。

https://auth.example.com/ui/console からログインし、パスワードを変更してください。他の設定を行う前に、そのアカウントで二要素認証を有効にしてください。すべての ZITADEL_FIRSTINSTANCE_* の値は、最初のインスタンスが作成される間のみ適用されます。インスタンスが作成された後では、それらを編集しても何も反映されません。

SMTP が機能するまでパスワードリセットが何も起こさない理由

メールを送信できないアイデンティティプロバイダーは、数週間にわたって問題が表面化しない形で壊れています。Zitadel は、ユーザー招待、アドレス確認、パスワードリセットリンク、ワンタイムコード、ドメイン所有権確認の通知でメールを送信します。SMTP プロバイダーを設定していない場合でも、Console は処理を完了したと表示します。しかし、メッセージは送信先のない通知処理に渡されます。v4.20.0 では、通知はデフォルトでレガシーモード(LegacyEnabled: true)を使用します。このモードは、並列ワーカーの MaxAttempts: 3 と MaxTtl: 5m の設定を無視します。これらの値は、デフォルトの通知リトライ動作を示すものではありません。リンクを待っているユーザーには、何も通知されません。

Console のインスタンス設定にある https://auth.example.com/ui/console/settings で設定します。SMTP プロバイダーのフォームでは、送信元メールアドレス、送信者名、ホストとポート、ユーザー、SMTP パスワード、TLS の切り替えを指定します。保存する前に、そのフォームのテストボタンを使用してください。実際のメッセージが送信されるため、届くか届かないかで結果を確認できます。プロバイダーを有効化すると、Zitadel はそのプロバイダーを使ってメールを送信します。

対応する環境変数のセットとして ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST とその関連変数もあります。これらはインスタンスの作成時に適用されます。すでに稼働しているスタックでは効果がないため、既存のインスタンスには Console を使用します。

VPS からのメール配信について、通常問題になる点を2つ確認します。リレーを選ぶ前に、プロバイダーの外向き SMTP ポリシーを確認してください。DigitalOcean はデフォルトで Droplet のポート 25、465、587 をブロックするため、ポート 587 が常に使える回避策とは限りません。プロバイダーが許可しているポートで、認証付きのリレーを使用します。また、送信ドメインに SPF(sender policy framework)と DKIM(domainkeys identified mail)のレコードを公開してください。設定しないと、リセットリンクがスパムフォルダーに入ります。ユーザーには、メールが送信されなかった場合と同じように見えます。

v4.20.0 では、外向き SMTP の TLS 接続が、侵害された eMudhra 中間 CA を経由する証明書チェーンを拒否します。影響を受けるリレーでは、証明書を交換する必要があります。

ユーザーを招待する前に、実際に確認してください。使い捨てのユーザーを作成し、パスワードリセットを要求して、メッセージが届くか監視します。届かない場合は、docker compose logs -f zitadel-api に SMTP の失敗理由が示されます。SMTP パスワードはデータベース内で暗号化して保存されます。これは、masterkey が管理する対象がもう1つ増えるということです。

Postgres と masterkey は分けてバックアップする

Zitadel が認識するすべての情報は PostgreSQL に保存されています。その情報を復号するのが masterkey です。これらは別々の場所にバックアップします。

まずダンプを作成します。

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc は custom format を指定します。出力時に圧縮され、pg_restore で必要な内容だけを選択して読み込めます。exec -T は端末を切り離します。cron から端末なしで実行するために必要です。

次に、暗号化と重複排除を行う restic で、そのディレクトリをオフサイトへ転送します。

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init は初回の1回だけ実行します。ダンプと最後の2つのコマンドを /usr/local/bin/zitadel-backup.sh に記述し、毎晩実行します。

0 3 * * * /usr/local/bin/zitadel-backup.sh

.env と使用するすべての compose ファイルは、git でバックアップします。masterkey はこの原則の例外です。masterkey はパスワードマネージャーと、現在の restic リポジトリとは別の2番目の場所に保存します。データベースとその復号鍵を同じアーカイブに保存すると、暗号化されたシステムのバックアップとして機能しなくなるためです。

復元していないバックアップは、推測にすぎません。同じサーバー上の一時データベースに復元し、内容を確認します。

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

eventstore スキーマ内のテーブル一覧が表示されれば、ダンプは正常です。スキーマが存在しないというエラーが表示された場合、ダンプは正常ではありません。損失が発生しない日に問題を発見できたことになります。Compose スタックをバックアップしてアップグレードする一般的な手順は、ほぼそのままここにも適用できます。同じアーカイブに masterkey を保存しないことだけが、Zitadel 固有の対応です。

Zitadel のインスタンスを失わずにアップグレードする

アップグレードでは、.env のバージョンを更新した後、次の 2 つのコマンドを実行します。

docker compose pull
docker compose up -d --wait

ユーザーがログインする環境に対して実行する前に、2 つ目のコマンドの動作を理解してください。コンテナの command は start-from-init です。これはサービスの提供を開始する前に init フェーズと setup フェーズを実行します。setup フェーズではデータベースのマイグレーションが実行されます。つまり、バージョンを更新すると、コンテナの起動時に稼働中のデータベースに対してスキーママイグレーションが無人で実行され、その間 --wait はヘルスチェックを待機します。上記のリストアテストが省略できない理由はこれです。

アップグレードの直前に、最新のダンプを取得してください。前夜のダンプは別のものです。

v4.20.3 では、進行中の外部 ID プロバイダーによるサインインを再開する必要があります。また、未使用の Login V1 認可コードは一度だけ拒否されます。カスタムのログイン UI で OIDC または SAML リクエストを完了するには session.link 権限が必要です。アップグレード前に、そのサービスユーザーへ IAM_LOGIN_CLIENT を付与してください。提供されている Login V2 のサービスユーザーには、すでにそのロールがあります。Session API のパスワードチェックでは、ユーザーの組織のログインポリシーが適用されるようになりました。そのため、ユーザー名/パスワードによるログインを無効にしている組織では、ユーザーを ID プロバイダーへ誘導する必要があります。

メジャーバージョンをまたいでアップグレードしないでください。v3 から v4 に移行する前に、まず v3.4.1 以降へ更新してください。v4 では OIDC web keys が必須になり、従来の署名経路が削除されます。そのため、v3 のインスタンスで web keys を有効にしていなかった場合、従来の legacy keys で署名されたトークンはアップグレード後に検証できなくなります。Zitadel の technical advisory A-10017 によると、既存の JWT access tokens と ID tokens は直ちに無効になる可能性があり、ユーザーは再度サインインを求められる可能性があります。対策は、v3.4.1 以降を経由し、legacy 署名のトークンとセッションが期限切れになるまで待ってからアップグレードすることです。または、計画的な再ログイン期間を受け入れます。すでに v3.4.1 以降を実行しており、web keys を有効にしてから待機期間を置いている場合、advisory では対応不要とされています。

docker compose logs -f zitadel-api で setup フェーズを監視してください。大規模な eventstore ではマイグレーションに数分かかります。Traefik はヘルスチェックに合格するまで API へルーティングしないため、その間サイトは停止します。実際に発生してから把握するのではなく、あらかじめ計画してください。

ロールバックは、古い tag に戻すだけでは済みません。マイグレーションが実行されると、古い binary は見つかったスキーマを理解できなくなります。そのため、ロールバックではダンプをリストアします。インスタンスに実際のユーザーが存在するようになったら、docker-compose.prodlike.yml へ移行してください。これは init と setup を start とは別のステップとして実行する overlay です。これにより、マイグレーションをコンテナ再起動の副作用ではなく、明示的に実行して監視する処理にできます。

新しいアイデンティティプロバイダーで指定する項目

Console でプロジェクトを作成し、その中にアプリケーションを作成します。最新の方式には OIDC を選択します。Zitadel から client ID、client secret、https://auth.example.com/.well-known/openid-configuration にある discovery document が提供されます。シングルサインオンに対応する自己ホスト型ソフトウェアの多くは、これらをそのまま要求します。

対応していないソフトウェアも多く、対応していても有料プランに限られる場合があります。前者には、アプリの前段に oauth2-proxy を置く方法が有効です。これにより、任意の HTTP サービスを Zitadel で保護できます。後者については、料金を支払っていない機能を前提に移行計画を立てる前に、自己ホスト型アプリにおける SSO の追加料金を読む価値があります。

FAQ

自己ホスト型 Zitadel にはどの程度の RAM と CPU が必要ですか?

Zitadel の本番環境ガイドによると、Zitadel 自体には約 0.5 GB の RAM が必要で、CPU コア 1 個未満でも動作します。ただし、パスワードハッシュ処理用に 4 コアを確保することが推奨されています。PostgreSQL に必要なリソースは別に見積もります。目安は、100 requests per second あたり約 1 コア、1 コアあたり 4 GB の RAM です。ガイドにある大きな値は、3 ノードの高可用性クラスターにおける 1 ノードあたりの値です。各ノードに 4 コアと 16 GB が必要です。ログ収集とメトリクスを使用しない場合は、約 4 コアと 8 GB です。Compose のクイックスタートでは少なくとも 2 GB が必要です。試用には十分ですが、他のシステムサービスが依存するデータベースに必要なリソースを確保する余裕はほとんどありません。

Zitadel の masterkey を失うとどうなりますか?

masterkey で暗号化されたデータは、暗号化されたままになります。Identity provider の認証情報、SMTP パスワード、one-time-password の seed は復号できません。また、後から key を変更することもできません。データベースの dump だけでは、動作するインスタンスを復元できません。dump には暗号文しか含まれず、key がないためです。masterkey は password manager に保存し、dump を保持するバックアップとは別の場所にも保管してください。両方を失った場合、残された方法はインスタンスを最初から再構築することだけです。

Zitadel の password reset メールがまったく届かないのはなぜですか?

SMTP provider が設定されていないか、設定した provider が配信できないためです。Zitadel v4.20.0 では、デフォルトで従来の notification processing が使用されます。そのため、並列 worker に設定された 3 回の試行と 5 分間の設定は無視されます。instance settings で SMTP provider を設定し、そのフォームにある test ボタンを使用してください。実際のメッセージが送信されます。provider を有効にし、VPS provider が許可している port で認証済み relay を使用してください。また、送信元 domain の SPF および DKIM record を公開し、メールが spam として filtering されないようにします。

インストール後に Zitadel の external domain を変更できますか?

はい。ただし、.env だけを編集しても変更できません。ZITADEL_EXTERNALDOMAIN、ZITADEL_EXTERNALPORT、ZITADEL_EXTERNALSECURE を変更し、Zitadel に setup phase を再実行させて変更を反映します。登録済みのアプリケーションには以前の redirect URI が残るため、手動で更新する必要があります。また、Host header が Zitadel が認識している domain と一致しない request には、Instance not found が返されます。初回起動前に最終的な名前を決めておけば、これらの問題を避けられます。

この記事は役に立ちましたか?