Skip to main content
Twenty には、互いに独立した 2 つのキー群があります。
  • JWT 署名キー — core."signingKey" に保存された非対称 ES256 キーペア（kid タグ付き）で、アクセストークン / リフレッシュトークンの署名および検証に使用されます。
  • 保存データ暗号化キー — ENCRYPTION_KEY。OAuth トークン、アプリケーション変数、署名キーの秘密鍵、機密性の高い設定値、および enc:v2: エンベロープ内の TOTP シークレットを暗号化するために使用されます。
APP_SECRET は後方互換性のために保持されているレガシーなシークレットです。ENCRYPTION_KEY が未設定の場合、保存データ暗号化 / セッション Cookie のフォールバックとして動作し、既存の HS256 アクセストークンの検証にも引き続き使用されます。 これは非推奨となる予定です。

​
JWT 署名キー

各キーには、publicKey（過去に発行されたトークンを検証できるよう、無期限に保持）、暗号化された privateKey（そのキーが現行の間のみ使用）、isCurrent フラグ（同時にちょうど 1 行だけ true）、および任意の revokedAt が含まれます。

​
現在のキーをローテーションする

オプトインするには SIGNING_KEY_ROTATION_DAYS を設定します。日次の cron により、既存のキーがその閾値より古くなると、新しいキーが現行キーとして発行されます。 以前のキーは 失効しない ため、そのキーで署名されたトークンは検証に通り続けます。 自動ローテーションを無効にするには、変数を未設定のままにします。
自動ローテーションは v2.6 以降で提供されています。

​
キーを失効させる（漏えい時 / 緊急時のみ）

非現行の行で Settings → Admin Panel → Signing keys → Revoke を実行します。 暗号化された秘密情報を消去し、revokedAt を設定し、その kid で署名された既存トークンをすべて拒否します。

​
ENCRYPTION_KEY をローテーションする

以下で説明する secret-encryption:rotate コマンドは v2.6+ で提供されています。
すべての暗号化された値は enc:v2:\<keyId>:\<payload> の形式でラップされます。ここで \<keyId> は、生のキーから導出された 8 文字の 16 進プレフィックスです。 ローテーションはオンラインで実行でき、中断しても再開可能です。
  1. 新しいキーを生成: openssl rand -base64 32.
  2. .env に 両方のキーを並べて設定 し、再起動します: 
    ENCRYPTION_KEY=NEW_VALUE
FALLBACK_ENCRYPTION_KEY=OLD_VALUE
    新規書き込みは新しいキーを使用し、既存行はフォールバック経由で引き続き復号されます。
  3. 既存行を再暗号化する: 
    docker exec -it {server_container} yarn command:prod secret-encryption:rotate
    このコマンドは 6 つのサイト（connected-account-tokens、application-variable、application-registration-variable、signing-key-private-keys、sensitive-config-storage、totp-secrets）を走査します。 SQL フィルターにより、すでに新しい \<keyId> になっている行はスキップされるため、このコマンドはべき等です。必要に応じて中断し、再実行できます。 いずれかの行で失敗した場合は非ゼロで終了します。再実行してリトライしてください。
    フラグ説明
    -s, --site \<site>単一のサイトに限定します。
    -b, --batch-size \<n>バッチごとの行数（デフォルト 200、最大 5000）。
    -d, --dry-runメモリ上で復号 + 再暗号化を行い、UPDATE は実行しません。
  4. --dry-run で残り行数が 0 になったことを確認したら フォールバックを削除 します。FALLBACK_ENCRYPTION_KEY を削除して再起動してください。

​
レガシーな APP_SECRET サポート

これまで一度も ENCRYPTION_KEY を設定していない古いインスタンスは、APP_SECRET を保存データ暗号化キー（および、そこから導出されるセッション Cookie シークレット）として使用します。 この経路は後方互換性のために保持されていますが、非推奨 です。専用の ENCRYPTION_KEY を設定し、上記のローテーション手順に従って移行してください。 APP_SECRET 自体はレガシーな HS256 アクセストークンを検証するために引き続き使用されます。