Trezor

Trezor je centrální úložiště hesel, API tokenů, client secretů a certifikátů. Do šablon, cronů a smart eventů se místo skutečné hodnoty píše jen odkaz na položku trezoru. Hodnota se dosadí až na serveru za běhu a nikdy se nedostane do prohlížeče, do logů ani do exportu šablony.

Dostupné od 5.17 (výpočty a smart eventy), certifikáty od 5.19, generování párů klíčů od 5.19, odkazy v cronech od 5.19.

Co Trezor umí uložit

Kde ho najdu a kdo do něj vidí

Administrace → Bezpečnost a autentizace → dlaždice Trezor.

Tajné klíče

Vytvoření

Tlačítko Vytvořit tajný klíč. Vyplňuje se Název, Hodnota (maskovaná) a volitelně Popis.

Úprava

Editovat lze pouze hodnotu. Pole je při otevření vždy prázdné, hodnotu je nutné zadat celou znovu. Název a popis změnit nejdou – položku je potřeba smazat, založit znovu a přepsat všechny odkazy.

Zobrazení a smazání

Akce Zobrazit ukáže maskovanou hodnotu s tlačítkem pro kopírování. Každé zobrazení se zapisuje do logu včetně toho, kdo a co četl.

Před smazáním systém hledá reference na šablonových úkolech – vault.get('název') ve výpočtech a {{vault:název}} v parametrech smart eventů. Pokud něco najde, mazání odmítne.

Certifikáty

Nahrání certifikátu

Tlačítko Nahrát certifikát, přípony .pem, .cer, .crt, .der. Server soubor rozparsuje jako X.509 a sám doplní Platnost od / Platnost do a do popisu issuer a subject.

Editace certifikátu neexistuje – nová verze se nahraje pod stejným názvem a původní se tím přepíše.

Generování páru klíčů

Tlačítko Vygenerovat pár klíčů na záložce Certifikáty. Typické použití je podepisování JWT.

• RSA – 4096 bitů, PEM (spki / pkcs8)
• ECDSA – křivka P-256
• Formát – PEM nebo JWK

Vzniknou dvě položky typu certificate: název.public a název.private. Veřejný klíč se zobrazí hned po vygenerování a lze ho kdykoli otevřít znovu. Privátní klíč se v UI nikdy nezobrazí – použitelný je jen odkazem.

Externí zdroje (.env)

Záložka viditelná jen pro super administrátora. Obsahuje hodnoty vložené do prostředí serveru:

TAS_SECRET_<NÁZEV>=hodnota
TAS_SECRET_<NÁZEV>_FILE=/run/secrets/nazev   # varianta pro Docker secrets

Název položky trezoru je pak <NÁZEV>, tedy část za prefixem TAS_SECRET_.

• Záložka je jen ke čtení – změna jde jen zásahem do konfigurace prostředí.
• .env secrety se načítají při startu aplikace, změna se projeví až po restartu.
• .env má přednost před databází. Existuje-li TAS_SECRET_ERP_TOKEN i databázový secret ERP_TOKEN, použije se vždy ten z .env.

Jak se na položku odkazuji

Oba zápisy prohledávají tajné klíče i certifikáty a respektují přednost .env. Uvnitř tokenu {{vault:…}} nesmí být mezery.

Vkládání odkazu přes ikonu

U podporovaných polí je vpravo ikona pro vložení proměnné (tooltip Přidat proměnnou). Po kliknutí se nabídnou zdroje: Proměnné ({proměnná}), Trezor ({{vault:název}}), AI zdroje ({{ai-content:název}}) a Dokumenty ({{documents:název}}). Odkaz se vloží na pozici kurzoru.

• Smart eventy – nabízí všechny čtyři zdroje.
• Crony – ikona se objeví jen u polí typu heslo a nabízí pouze Trezor.

Použití v cronech (od 5.19)

1. Otevřete detail cronu v administraci.
2. U pole s citlivou hodnotou (např. clientSecret u MS Graph mailových cronů) klikněte na ikonu vložení proměnné.
3. Vyberte tajný klíč – do pole se vloží {{vault:název}}.
4. Uložte.

Cron si tokeny při každém běhu rekurzivně dosadí – projde celý objekt parametrů včetně vnořených objektů a polí. V uložené konfiguraci zůstává jen token.

Použití ve smart eventech

Do libovolného textového pole v parametrech smart eventu lze vložit {{vault:název}}. Server před spuštěním projde konfiguraci rekurzivně a dosadí v tomto pořadí:

1. odkazy do trezoru {{vault:název}},
2. AI obsah {{ai-content:název}},
3. proměnné šablony {proměnná}.

Typicky: hlavička Authorization u HTTP smart eventu, heslo u FTP smart eventu, API klíč u AI konektorů.

SmartEventJwtGenerator (od 5.19)

Podepíše krátkodobý JWT token privátním klíčem z trezoru.

Použití ve výpočtech

Funkce vault.get() je dostupná pouze ve výpočtu na úkolu a prohledává tajné klíče i certifikáty. Pokud položka neexistuje, volání skončí chybou.

Vrací objekt VaultSecretRef, ne řetězec. Reference je záměrně neprozraditelná – při převodu na text, JSON.stringify() nebo výpisu do logu vrátí vždy jen [VaultSecretRef].

const ref = vault.get('erp-api-token');
proc.info(`${ref}`);        // zaloguje "[VaultSecretRef]", ne hodnotu
JSON.stringify({ ref });    // {"ref":"[VaultSecretRef]"}

HTTP volání (axios)

const client = axios.getAxios({ baseURL: 'https://erp.example.com', timeout: 10000 })
  .setVaultHeader('Authorization', vault.get('erp-api-token'), 'Bearer ');

const orders = client.get('/orders');

OAuth client credentials:

const client = axios.getAxios({ baseURL: 'https://api.example.com', timeout: 10000 });

const tokens = client.requestWithVaultField(
  {
    method: 'POST',
    url: '/oauth/token',
    data: { grant_type: 'client_credentials', client_id: 'my-app' },
  },
  [{ fieldName: 'client_secret', ref: vault.get('oauth-client-secret') }],
);

mTLS – ca, cert i key přijímají řetězec, Buffer i VaultSecretRef:

const client = axios.getAxios({ baseURL: 'https://soap.partner.cz', timeout: 10000 });

client.applySslConfig({
  ca: vault.get('partner-ca'),
  cert: vault.get('partner-client-cert'),
  key: vault.get('partner-client-key'),
});

FTP / SFTP

Konfigurace se předává bez hesla, heslo jde samostatně jako reference:

const client = ftp.getFtpClientWithVaultPassword(
  { host: 'sftp.partner.cz', port: 22, user: 'tas', protocol: 'sftp' },
  vault.get('sftp-password'),
);

JWT

jwt.sign() i jwt.verify() přijímají jako klíč běžný řetězec nebo VaultSecretRef (od 5.18.3):

const token = jwt.sign({ sub: 'tas', scope: 'read' }, vault.get('partner-api.private'), { algorithm: 'RS256' });

Certifikát jako text

const pem = lib.getCertificate('partner-ca', 'utf8');

Druhý parametr je kódování výsledku, výchozí binary.

Zrušené funkce

Validace šablony na ně upozorní:

Hlídání expirace

Cron B2bAndSecretStoreValidationCron (alias Secret store & API token validation) hlídá, co v nejbližší době expiruje. Výchozí plán je 00 00 05 * * * (denně v 05:00) a ve výchozím stavu je vypnutý.

Doporučené postupy

• Vlastnictví – citlivé položky zakládejte pod super administrátorským účtem, ať zůstanou spravovatelné i po odchodu konzultanta z projektu.
• Rotace – při výměně hesla stačí změnit hodnotu v Trezoru, odkazy v šablonách i cronech zůstávají beze změny.
• Verzované názvy certifikátů – např. partner-ca-2026, aby nová verze nepřepsala tu původní bez varování.
• Migrace mezi prostředími – exportovaná šablona obsahuje jen odkazy {{vault:…}}. Položky Trezoru se stejnými názvy je nutné na cílovém prostředí vytvořit ručně, nepřenášejí se.
• Zálohování – TAS_DATABASE_ENCRYPTION_KEY zálohujte odděleně od databáze a mimo repozitář.

Časté potíže

Technické detaily