Správa tokenů¶
Životní cyklus externích API tokenů — povinné sledování exspirace, upozornění, ruční obnova a nasazení
Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-10-22
Od verze v1.0.60 — Enterprise funkce (licence PoC / Enterprise)
1. Přehled¶
Řada externích systémů — Jira, Signi, GitLab, platební brány, SaaS API — vydává dlouhodobé API tokeny, které MazeVault nedokáže rotovat automaticky, protože nový token lze získat pouze přihlášením do GUI zdrojového systému a jeho ručním vygenerováním. Takové tokeny často tiše exspirují a rozbijí integrace.
Správa tokenů (Token Management) dává těmto externě vydaným tokenům řízený životní cyklus uvnitř MazeVaultu:
| Funkce | Popis |
|---|---|
| Povinná exspirace | Každý token musí být zaevidován s datem exspirace; MazeVault sleduje zbývající dny |
| Upozornění na exspiraci | Před vypršením tokenu vznikne incident token_expiry, po vypršení je eskalován na critical |
| Ruční obnova | Novou hodnotu i nové datum exspirace zaznamenáte v jednom kroku; otevřený incident se automaticky vyřeší |
| Cíle nasazení | Doručení hodnoty tokenu do konfiguračních souborů spravovaných agentem, Kubernetes secretů, Azure Key Vault nebo AWS Secrets Manager |
| Synchronizace při obnově | Cíle označené pro synchronizaci se po obnově automaticky znovu nasadí |
| Šifrování v klidu | AES-256-GCM ve standardním režimu; v režimu Orchestrátora odeslání do externího správce tajemství |
| Podpora Terraformu | Resource mazevault_token a data source mazevault_tokens |
Správa tokenů je dostupná v hlavním menu pod Enterprise Functions → Token Management.
Čím se liší od ostatních úložišť klíčů¶
| Úložiště | Účel | Kde |
|---|---|---|
| Token Management | Externě vydané API tokeny s ruční obnovou (Jira, Signi, …) | Enterprise Functions → Token Management |
| Key management projektu | Projektová tajemství (hesla, connection stringy, generované klíče) spravovaná a rotovaná MazeVaultem | Projekt → Secrets |
| System Keys | Vlastní infrastrukturní klíče MazeVaultu (šifrovací, podpisové, bootstrap) | Nastavení organizace → System Keys |
| Uživatelské API tokeny | Osobní/servisní API tokeny pro volání MazeVault API | Uživatelské menu → API Tokens |
Licenční požadavek
Správa tokenů je gatovaná licenční funkcí token_management, kterou mají licence PoC a Enterprise (ve stavu active, grace nebo expiring). U licence Small Business nebo bez licence vrací API /api/v1/tokens HTTP 403 a stránka zobrazí banner s výzvou k upgradu. Viz Licencování.
2. Zaevidování tokenu¶
- Přejděte na Enterprise Functions → Token Management
- Klikněte na Add Token
- Vyplňte údaje tokenu:
| Pole | Povinné | Popis |
|---|---|---|
| Name | ✅ | Unikátní zobrazovaný název, např. jira-automation-token |
| Provider | — | Volný textový štítek vydávajícího systému (jira, signi, gitlab, …). Jira a Signi mají vlastní ikony |
| Description | — | Účel tokenu |
| Value | ✅ | Tajná hodnota tokenu. Je okamžitě zašifrována a nikdy není vrácena v seznamu ani detailu |
| Expires at | ✅ | Datum a čas exspirace tak, jak je uvádí zdrojový systém |
| Alert lead time (days) | — | Kolik dní před exspirací se otevře upozornění. Výchozí hodnota 30 |
| Project | — | Volitelná vazba na projekt. Tokeny vázané na projekt lze nasazovat na agenty a integrace daného projektu |
| Metadata | — | Volné páry klíč/hodnota (vlastník, ticket, nákladové středisko, …) |
- Klikněte na Save
Datum exspirace je povinné
MazeVault nedokáže exspiraci externího tokenu zjistit sám. Zkopírujte datum přesně tak, jak jej zobrazuje vydávající systém. Pokud systém vydává tokeny bez exspirace, nastavte exspiraci dle interní politiky (např. 12 měsíců), aby byl token pravidelně revidován.
Stav tokenu¶
| Stav | Význam |
|---|---|
active |
Token je používán a sledován na exspiraci |
expired |
expires_at uplynulo; incident je eskalován na critical |
revoked |
Ručně označen jako zneplatněný ve zdrojovém systému; vyloučen ze sledování |
Režim uložení¶
| Režim | Chování |
|---|---|
| Standardní | Hodnota je zašifrována AES-256-GCM a uložena v databázi MazeVaultu (storage_mode: local) |
| Režim Orchestrátora | Lokálně se ukládají pouze metadata; hodnota je odeslána do nakonfigurovaného externího správce tajemství (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) a záznam nese storage_mode: external a external_provider_type |
3. Sledování exspirace a upozornění¶
Plánovač notifikací vyhodnocuje každý active token jednou denně:
| Podmínka | Výsledek |
|---|---|
expires_at je dále než lead time dní |
Žádná akce |
expires_at spadá do okna lead time |
Otevřen (nebo obnoven) incident token_expiry se závažností high |
expires_at uplynulo |
Závažnost incidentu eskalována na critical; stav tokenu se změní na expired |
Incident je doručen standardní cestou incidentních notifikací — kontakty pro incidenty, e-mail, webhook, Microsoft Teams, Slack, Jira a integrace SMSEagle. Viz Notifikace a upozornění.
Seznam tokenů zobrazuje barevně odlišený štítek exspirace (zbývající dny / expirováno), takže operátoři mohou třídit bez otevírání jednotlivých záznamů.
Lead time per token
U tokenů, jejichž obnova vyžaduje schvalovací proces nebo třetí stranu, použijte delší lead time (např. 60–90 dní pro tokeny vydávané partnerem).
4. Ruční obnova¶
Jakmile byl token ve zdrojovém systému znovu vygenerován:
- Otevřete token a klikněte na Renew
- Vložte novou hodnotu a zadejte nové datum exspirace
- Volitelně doplňte poznámku k obnově (číslo ticketu, kdo obnovu provedl)
- Klikněte na Renew
MazeVault poté:
- Nahradí uloženou hodnotu (zašifrovanou nebo externě odeslanou) a zaznamená
last_renewed_at - Vrátí stav na
active - Vyřeší otevřený incident
token_expirys důvodem Token renewed - Znovu nasadí každý cíl nasazení, který má zapnuto Sync on renewal
- Zapíše
TOKEN_RENEWdo audit logu (aTOKEN_RENEW_SYNC_FAILEDpro každý cíl, kde nasazení selhalo)
Obnova vs. úprava
Update mění pouze metadata (název, popis, provider, lead time, datum exspirace, stav). Renew je jediná operace, která mění hodnotu tokenu.
5. Cíle nasazení¶
Token lze doručit na stejné typy cílů jako tajemství. Nasazení využívá sdílené doručovací exekutory MazeVaultu, takže chování, auditování i zpracování chyb odpovídá nasazení tajemství.
| Typ cíle | Popis | Požadovaná konfigurace |
|---|---|---|
agent_file |
Konfigurační soubor na serveru spravovaný agentem. Token je zapsán jako položka klíč → hodnota | agent_id, target_path, file_format (json / yaml / env, výchozí env), secret_key, volitelně post_install_cmd, backup |
kubernetes_secret |
Klíč uvnitř Kubernetes Secretu | integration_id (integrace Kubernetes), config.namespace, config.secret_name, config.key_name |
azure_keyvault |
Secret v Azure Key Vault | integration_id (integrace Azure Key Vault), config.secret_name |
aws_secrets_manager |
Secret v AWS Secrets Manager | integration_id (integrace AWS), config.secret_id, config.region |
Cíle Windows registry a IIS nejsou pro tokeny záměrně podporovány.
5.1 Konfigurační soubor agenta¶
Agent sloučí token do existujícího (nebo nového) konfiguračního souboru, aniž by se dotkl ostatních klíčů:
| Formát | Příklad výsledku |
|---|---|
json |
{ "jira": { "api_token": "<hodnota>" } } pro secret_key: jira.api_token |
yaml |
jira:\n api_token: <hodnota> |
env |
JIRA_API_TOKEN=<hodnota> |
Volby:
- Backup — agent před zápisem uloží kopii předchozího souboru s časovým razítkem
- Post-install command — spustí se po úspěšném zápisu (např.
systemctl restart jira-sync). Provedou se pouze příkazy odpovídající allowlistu příkazů agenta; viz Nasazení agenta → Allowlist příkazů - Sync on renewal — automatické opětovné nasazení po každé obnově
5.2 Stav nasazení¶
deployment_status |
Význam |
|---|---|
pending |
Cíl vytvořen, první nasazení dosud nepotvrzeno |
deployed |
Poslední synchronizace uspěla (last_sync_at, last_sync_status) |
failed |
Poslední synchronizace selhala; error_message obsahuje důvod |
Pomocí Sync now na cíli zopakujete neúspěšné nasazení nebo okamžitě odešlete aktuální hodnotu.
Vazba na projekt
Cíle nasazení se vyhodnocují v rámci projektu tokenu. Změna nebo odebrání vazby na projekt smaže cíle nasazení tokenu.
6. Zobrazení hodnoty tokenu¶
Uložená hodnota není nikdy součástí odpovědí seznamu ani detailu. Uživatelé s oprávněním token:admin ji mohou zobrazit z detailu tokenu (Reveal value). Každé zobrazení je zaznamenáno jako TOKEN_REVEAL v audit logu včetně jednajícího uživatele.
7. Oprávnění¶
| Oprávnění | Popis | Vestavěné role |
|---|---|---|
token:read |
Zobrazení tokenů, stavu exspirace a cílů nasazení | org_admin, operator, user, auditor |
token:write |
Vytvoření, úprava, obnova tokenů; přidání, odebrání a synchronizace cílů nasazení | org_admin, operator |
token:delete |
Smazání tokenů | org_admin, operator |
token:admin |
Zobrazení uložených hodnot tokenů (zahrnuje write i deploy) | org_admin |
Položka menu Token Management se zobrazí každému, kdo má token:read; o funkčnosti stránky rozhoduje licenční funkce. Viz RBAC role.
8. Audit trail¶
| Auditní akce | Spouštěč |
|---|---|
TOKEN_CREATE |
Token zaevidován |
TOKEN_UPDATE |
Změna metadat |
TOKEN_RENEW |
Obnovena hodnota a exspirace |
TOKEN_REVEAL |
Hodnotu zobrazil administrátor |
TOKEN_DELETE |
Token smazán |
TOKEN_TARGET_CREATE / TOKEN_TARGET_DELETE |
Cíl nasazení přidán nebo odebrán |
TOKEN_DEPLOY / TOKEN_DEPLOY_FAILED |
Nasazení na cíl uspělo nebo selhalo |
TOKEN_RENEW_SYNC_FAILED |
Opětovné nasazení cíle po obnově selhalo |
TOKEN_INCIDENT_RESOLVE_FAILED |
Incident exspirace se po obnově nepodařilo vyřešit |
TOKEN_OFFLOAD_CLEANUP_FAILED |
Externě uloženou hodnotu se nepodařilo smazat (režim Orchestrátora) |
Viz Audit logování.
9. Terraform¶
Tokeny lze spravovat jako kód pomocí resource mazevault_token a vypisovat přes data source mazevault_tokens — včetně povinného expires_at, lead_time_days a write-only value_wo. Obnova samotné hodnoty se provádí přes renew flow v UI/API, nikoli přes Terraform. Viz Terraform Provider → Správa externích API tokenů.
10. Režim Orchestrátora¶
V režimu Orchestrátora se hodnota tokenu nikdy nenachází v databázi MazeVaultu. Při vytvoření a obnově je hodnota zapsána do externího správce tajemství nakonfigurovaného pro organizaci a lokálně zůstává pouze reference. Smazání tokenu odstraní i externí hodnotu; případné selhání je auditováno jako TOKEN_OFFLOAD_CLEANUP_FAILED, ale smazání neblokuje.
| Pole | Hodnota |
|---|---|
storage_mode |
external |
external_provider_type |
Schéma externí reference (Azure Key Vault, AWS Secrets Manager nebo HashiCorp Vault podle nakonfigurovaného offload providera) |