github-actions[bot]
a0493dbc4b
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
61 lines
5.0 KiB
Plaintext
61 lines
5.0 KiB
Plaintext
---
|
|
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 アクセストークンを検証するために引き続き使用されます。
|