Skip to main content
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.
Automatická rotace je k dispozici od verze v2.6+.

​
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

Příkaz secret-encryption:rotate popsaný níže je k dispozici od verze v2.6+.
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: 
    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: 
    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-runDeš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ů.