---
title: キーのローテーション
icon: rotate
---

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 により、既存のキーがその閾値より古くなると、新しいキーが現行キーとして発行されます。 以前のキーは *失効しない* ため、そのキーで署名されたトークンは検証に通り続けます。 自動ローテーションを無効にするには、変数を未設定のままにします。

<Note>自動ローテーションは v2.6 以降で提供されています。</Note>

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

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

## `ENCRYPTION_KEY` をローテーションする

<Note>以下で説明する `secret-encryption:rotate` コマンドは v2.6+ で提供されています。</Note>

すべての暗号化された値は `enc:v2:\<keyId>:\<payload>` の形式でラップされます。ここで `\<keyId>` は、生のキーから導出された 8 文字の 16 進プレフィックスです。 ローテーションはオンラインで実行でき、中断しても再開可能です。

1. **新しいキーを生成**: `openssl rand -base64 32`.

2. `.env` に **両方のキーを並べて設定** し、再起動します:
   ```ini
   ENCRYPTION_KEY=NEW_VALUE
   FALLBACK_ENCRYPTION_KEY=OLD_VALUE
   ```
   新規書き込みは新しいキーを使用し、既存行はフォールバック経由で引き続き復号されます。

3. **既存行を再暗号化する**:

   ```bash
   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 アクセストークンを検証するために引き続き使用されます。