github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
61 lines
4.3 KiB
Plaintext
61 lines
4.3 KiB
Plaintext
---
|
|
title: Rotace klíčů
|
|
icon: rotate
|
|
---
|
|
|
|
Twenty má dvě nezávislé rodiny klíčů:
|
|
|
|
* **Klíče pro podepisování JWT** — asymetrické páry klíčů ES256 (označené `kid`), uložené v `core."signingKey"`, používané k podepisování a ověřování přístupových/obnovovacích tokenů.
|
|
* **Šifrovací klíč pro data v klidu** — `ENCRYPTION_KEY`, používaný k šifrování OAuth tokenů, aplikačních proměnných, soukromých klíčů podepisovacích klíčů, citlivých konfiguračních hodnot a TOTP tajemství uvnitř obálky `enc:v2:`.
|
|
|
|
`APP_SECRET` je starší tajný klíč ponechaný kvůli zpětné kompatibilitě: pokud `ENCRYPTION_KEY` není nastaven, slouží jako záložní řešení pro šifrování dat v klidu i pro soubory cookie relace a stále ověřuje dříve existující HS256 přístupové tokeny. Bude označen jako zastaralý (deprecated).
|
|
|
|
## Klíče pro podepisování JWT
|
|
|
|
Každý klíč nese `publicKey` (uchovávaný neomezeně dlouho, aby mohl ověřovat dříve vydané tokeny), zašifrovaný `privateKey` (používaný pouze tehdy, když je klíč aktuální), příznak `isCurrent` (vždy přesně jeden záznam) a volitelné `revokedAt`.
|
|
|
|
### Rotace aktuálního klíče
|
|
|
|
Nastavte `SIGNING_KEY_ROTATION_DAYS`, chcete-li funkci povolit: denní cron poté vydá nový klíč jako aktuální, jakmile je stávající starší než zadaný práh. Předchozí klíče *nejsou* odvolány, takže tokeny pod nimi podepsané se dál úspěšně ověřují. Ponechte proměnnou nenastavenou, abyste deaktivovali automatickou rotaci.
|
|
|
|
<Note>Automatická rotace je k dispozici od verze v2.6+.</Note>
|
|
|
|
### Odvolání klíče (pouze při úniku / v nouzi)
|
|
|
|
**Settings → Admin Panel → Signing keys → Revoke** na neaktuálním řádku. Smaže zašifrovaný privátní materiál, nastaví `revokedAt` a odmítne každý existující token podepsaný pod daným `kid`.
|
|
|
|
## Rotace `ENCRYPTION_KEY`
|
|
|
|
<Note>Příkaz `secret-encryption:rotate` popsaný níže je k dispozici od verze v2.6+.</Note>
|
|
|
|
Každá zašifrovaná hodnota je zabalena jako `enc:v2:\<keyId>:\<payload>`, kde `\<keyId>` je 8místný hexadecimální prefix odvozený ze surového klíče. Rotace probíhá online a je možné ji kdykoli znovu spustit.
|
|
|
|
1. **Vygenerujte nový klíč**: `openssl rand -base64 32`.
|
|
|
|
2. **Nakonfigurujte oba klíče vedle sebe** v `.env` a poté restartujte:
|
|
```ini
|
|
ENCRYPTION_KEY=NEW_VALUE
|
|
FALLBACK_ENCRYPTION_KEY=OLD_VALUE
|
|
```
|
|
Nové zápisy používají nový klíč, existující řádky se stále dešifrují pomocí záložního klíče.
|
|
|
|
3. **Znovu zašifrujte existující řádky**:
|
|
|
|
```bash
|
|
docker exec -it {server_container} yarn command:prod secret-encryption:rotate
|
|
```
|
|
|
|
Příkaz prochází šest míst (`connected-account-tokens`, `application-variable`, `application-registration-variable`, `signing-key-private-keys`, `sensitive-config-storage`, `totp-secrets`). SQL filtr přeskočí řádky, které už jsou na novém `\<keyId>`, takže příkaz je idempotentní: přerušte ho a znovu spusťte podle potřeby. Ukončí se s nenulovým kódem, pokud jakýkoli řádek selže — spusťte znovu pro opakování.
|
|
|
|
| Přepínač | Popis |
|
|
| ---------------------------------------- | -------------------------------------------------------- |
|
|
| `-s, --site \<site>` | Omezí běh na jedno místo (site). |
|
|
| `-b, --batch-size \<n>` | Počet řádků v dávce (výchozí `200`, maximum `5000`). |
|
|
| `-d, --dry-run` | Dešifruje + znovu zašifruje v paměti, přeskočí `UPDATE`. |
|
|
|
|
4. **Odstraňte záložní klíč** jakmile `--dry-run` ukáže, že nezbývají žádné řádky: odeberte `FALLBACK_ENCRYPTION_KEY` a restartujte.
|
|
|
|
## Podpora staršího `APP_SECRET`
|
|
|
|
Starší instance, které nikdy nenastavily `ENCRYPTION_KEY`, používají `APP_SECRET` jako šifrovací klíč pro data v klidu (a jako tajemství pro soubor cookie relace, odvozené z něj). Tato cesta je zachována kvůli zpětné kompatibilitě, ale je **zastaralá (deprecated)** — nastavte vyhrazený `ENCRYPTION_KEY` a podle výše uvedeného postupu rotace proveďte migraci pryč od něj. Samotný `APP_SECRET` zůstává v používání pro ověřování starších HS256 přístupových tokenů.
|