Průvodce rotací tokenů Entra ID¶

Přehled¶

MazeVault poskytuje automatizovanou správu životního cyklu přihlašovacích údajů enterprise aplikací v Microsoft Entra ID (Azure AD). Zahrnuje automatické zjišťování, monitoring expirace, dual-secret rotaci s grace period a seřazený post-rotation deployment do Azure Key Vaultu, Kubernetes, agentem spravovaných runtime souborů, IIS app poolů, Spring aplikací a webhooků.

Klíčové funkce¶

Automatické zjišťování: Synchronizace registrací aplikací a přihlašovacích údajů z Entra ID
Monitoring expirace: Upozornění při 30denním a 7denním prahu
Dual-Secret rotace: Nový přihlašovací údaj vytvořen před odstraněním starého
Grace Period: Konfigurovatelné období (výchozí 30 dní), kdy jsou oba údaje platné
Seřazené rollout akce: Publikace nového přihlašovacího údaje do externích úložišť a následný refresh nebo recycle konzumentů v definovaném pořadí
Multi-Target propagace: Synchronizace do Azure Key Vault, Kubernetes Secret, Spring Actuatoru, webhooků a agentů
Kompletní audit trail: Každá rotace zaznamenána s časovými razítky a stavem

Začínáme¶

1. Konfigurace integrace Entra ID¶

Přejděte na Integrace → Přidat integraci → Microsoft Entra ID.

Zadejte: - Tenant ID: ID vašeho Azure AD tenanta - Client ID: Client ID service principalu - Client Secret nebo Managed Identity: Metoda autentizace

MazeVault nyní před uložením integrace validuje interaktivní i background autentizaci. Pokud onboarding používá delegovaný nebo OBO přístup, nakonfigurujte také kompatibilní background autentizační metodu pro synchronizaci, preflight a rotační úlohy.

2. Synchronizace registrací aplikací¶

Po konfiguraci integrace klikněte na Synchronizovat pro zjištění všech registrací aplikací ve vašem tenantovi. MazeVault importuje: - Metadata registrace aplikace - Client secrety s daty expirace - Certifikátové přihlašovací údaje

Pokud integrace používá scope selected_apps, uložte před prvním během synchronizace alespoň jeden binding vybrané aplikace. Když je zvolen tento scope, ale bindingy ještě neexistují, sync endpoint vrátí HTTP 409 Conflict, stav integrace se zapíše jako pending a hodinový background scheduler běh přeskočí, dokud není seznam vybraných aplikací nakonfigurován.

3. Zobrazení stavu přihlašovacích údajů¶

Entra Dashboard zobrazuje: - Celkový počet aktivních přihlašovacích údajů - Údaje expirující za 7/30/90 dní - Údaje v grace period - Nejnaléhavější údaje vyžadující pozornost

4. Konfigurace rotace¶

Pro každý přihlašovací údaj můžete nakonfigurovat: - Auto-rotace: Povolení automatické rotace před expirací - Dní před expirací: Kdy spustit rotaci (výchozí: 30 dní) - Grace period: Jak dlouho ponechat oba údaje aktivní (výchozí: 30 dní) - Key Vault cíle: Primární a sekundární Key Vault secrety pro uložení hodnoty - Kubernetes cíle: Namespace, název secretu a klíč k aktualizaci - Agent file cíle: Spravované runtime soubory na připojených Windows nebo Linux agentech - IIS recycle cíle: Windows IIS app pooly k recyklaci po zapsání souboru - Spring endpointy: Spring Actuator refresh endpointy - Webhook URL: Notifikační nebo deployment webhooky

5. Manuální rotace¶

Klikněte na tlačítko Rotovat u libovolného přihlašovacího údaje pro okamžitou rotaci. Proces:

Vytvoří nový přihlašovací údaj v Entra ID
Spustí post-rotation deployment akce v definovaném pořadí
Uloží nový secret do nakonfigurovaných Key Vaultů, Kubernetes Secretů nebo agentem spravovaných souborů
Obnoví nebo recykluje konzumentské aplikace
Pokud je to nakonfigurováno, odešle webhook notifikace
Označí starý údaj pro cleanup po grace period

Post-Rotation Deployment Akce¶

MazeVault spouští post-rotation akce v pořadí po vytvoření nového Entra přihlašovacího údaje. Pro produkční rollout používejte tento sled:

Publikujte nový secret do externích úložišť nebo runtime souborů.
Reloadujte nebo recyklujte konzumentskou aplikaci.
Nakonec odešlete webhook notifikace, pokud navazující systémy potřebují potvrzení.

Podporované typy akcí:

Azure Key Vault: Zápis otočené hodnoty do nové verze Key Vault secretu.
Kubernetes Secret: Aktualizace dvojice namespace/secret/key novou hodnotou.
Agent File Sync (agent_secret_sync): Zápis otočené hodnoty do souboru na hostu spravovaném připojeným MazeVault agentem.
IIS App Pool Recycle (iis_recycle): Recyklace Windows IIS app poolu přes připojeného MazeVault agenta.
Spring Actuator Refresh: Zavolání /actuator/refresh po publikaci nového secretu.
Webhook: Odeslání POST události do downstream deployment nebo notifikačního endpointu.

Agent File Sync (`agent_secret_sync`)¶

Použijte agent_secret_sync, pokud se má otočený client secret zapsat přímo do aplikačního konfiguračního souboru.

Povinná pole:

agent_id: ID připojeného MazeVault agenta. To je doporučený cíl, protože preflight umí ověřit připravenost agenta.
target_path: Absolutní cesta k runtime konfiguračnímu souboru na spravovaném hostu.
secret_key: Název pole nebo klíče, který dostane otočený secret.
file_format: Formát rendereru jako json, yaml nebo env.

Poznámky pro operátora:

Tento krok zařaďte před jakýkoliv aplikační refresh nebo recycle.
Legacy cílení přes přímé agent_url zůstává kvůli kompatibilitě podporované, ale MazeVault ho označuje jako manual review, protože cíl neumí automaticky sondovat.
Cílový agent musí mít práva k souborovému systému pro danou cestu.

Příklad:

[
    {
        "type": "agent_secret_sync",
        "order": 10,
        "on_failure": "abort",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "target_path": "C:\\inetpub\\app\\appsettings.json",
            "secret_key": "Entra:ClientSecret",
            "file_format": "json"
        }
    }
]

IIS App Pool Recycle (`iis_recycle`)¶

Použijte iis_recycle, pokud konzument běží na IIS a po dokončení file sync kroku musí načíst nový secret.

Povinná pole:

agent_id: ID připojeného Windows MazeVault agenta s právy pro správu IIS.
app_pool: Název IIS application poolu k recyklaci.

Poznámky pro operátora:

Tento krok umístěte za agent_secret_sync, aby k recyklaci IIS došlo až po zapsání nové hodnoty na disk.
Legacy pole site_name je kvůli kompatibilitě stále přijímáno, ale MazeVault ho normalizuje na app_pool.

Příklad:

[
    {
        "type": "agent_secret_sync",
        "order": 10,
        "on_failure": "abort",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "target_path": "C:\\inetpub\\app\\appsettings.json",
            "secret_key": "Entra:ClientSecret",
            "file_format": "json"
        }
    },
    {
        "type": "iis_recycle",
        "order": 20,
        "on_failure": "continue",
        "agent_id": "11111111-1111-1111-1111-111111111111",
        "config": {
            "app_pool": "DefaultAppPool"
        }
    }
]

Preflight a rollout doporučení¶

Před produkční rotací použijte Dry Run pro validaci Entra autentizace, dosažitelnosti Key Vaultu a připravenosti agenta.
Pokud preflight hlásí manual review required pro přímé agent_url, potvrďte dosažitelnost hostu a Windows/IIS oprávnění před spuštěním rotace.
Pokud neabortační deployment krok selže, MazeVault označí execution jako vyžadující operátorskou pozornost místo hlášení plně zdravého rolloutu.
Po rolloutu zkontrolujte historii execution. MazeVault ukládá lidsky čitelné názvy delivery kroků a souhrn rollout plánu pro rychlejší incident triage.
Používejte záložku Project Rotations jako souhrnný pohled napříč zdroji. Nově zobrazuje inline readiness i pro Entra přihlašovací údaje a související certifikátové rotační zdroje, které sdílejí stejnou rollout surface.

Cleanup rotačního inventáře při odebrání¶

Odstranění Entra integrace nebo lokálně spravované registrace aplikace nyní ve stejné lifecycle operaci smaže i odpovídající záznamy rotačních zdrojů.
Upgrade cleanup navíc odstraňuje zastaralé historické řádky Entra rotací ze starších vydání, takže inventář v Project Rotations zůstává v souladu se skutečnými Entra objekty.

6. Monitoring historie rotací¶

Zobrazte kompletní historii rotací pro libovolný přihlašovací údaj nebo registraci aplikace, včetně: - Typ rotace (manuální/automatická) - Doba trvání - Dokončené kroky - Případné chyby

Stavy životního cyklu¶

Stav	Popis
Aktivní	Údaj je platný a používaný
Brzy expiruje	Údaj expiruje v rámci prahu
Rotuje se	Rotace probíhá
Čeká na ověření	Nový údaj vytvořen; čeká se na ověření downstream propagace
Grace Period	Starý i nový údaj jsou platné
Expirovaný	Údaj expiroval
Vyčištěný	Starý údaj odstraněn po grace period

Automatické obnovení zaseknutých rotací¶

Pokud je rotační proces přerušen (například restartem podu nebo neočekávaným ukončením procesu), může přihlašovací údaj zůstat trvale ve stavu Rotuje se nebo Čeká na ověření.

MazeVault obsahuje automatický watchdog pro zaseknuté rotace, který tyto situace řeší:

Práh: Přihlašovací údaje zaseknuté v Rotuje se nebo Čeká na ověření déle než 30 minut jsou způsobilé pro automatické obnovení.
Frekvence: Watchdog běží každých 5 minut jako součást plánovače rotací.
Scénáře obnovení:
Scénář A — Proces byl přerušen před vytvořením nového přihlašovacího údaje v Azure. Zaseknutý údaj je obnoven do stavu Aktivní, aby mohla proběhnout nová rotace.
Scénář B — Proces byl přerušen poté, co byl nový přihlašovací údaj v Azure vytvořen, ale před aktualizací databáze. Nový údaj je automaticky povýšen na primární a starý údaj vstoupí do grace period.
Vyloučení staged rotace: Přihlašovací údaje v aktivní fázi staged rotace (secondary_pending, secondary_deployed, primary_rotation_eligible) watchdog neupravuje; jsou spravovány tokem staged promotion.
Indikátor v UI: Pokud je přihlašovací údaj ve stavu Rotuje se déle než 10 minut, zobrazí seznam přihlašovacích údajů varovnou ikonu s tooltipem vysvětlujícím, že automatické obnovení proběhne do 30 minut. Není třeba žádné manuální akce.
Auditní stopa: Každé obnovení watchdogem je zaznamenáno v auditním logu pod akcí entra.credential.stuck_rotation_recovered.

Bezpečnost¶

Všechny hodnoty přihlašovacích údajů šifrovány v klidu pomocí AES-256-GCM
Graph API volání používají exponenciální backoff s retry
OData filter vstupy sanitizovány proti injection útokům
RBAC oprávnění: entra:read, entra:write, entra:rotate

Řešení problémů¶

Rotace selhala¶

Zkontrolujte historii rotací pro detaily chyby. Běžné příčiny: - Nedostatečná oprávnění Graph API - Přístup ke Key Vault zamítnut - Agent je offline nebo nedostupný během file deploymentu - Windows agentu chybí oprávnění pro správu IIS - Problémy se síťovým připojením

Přihlašovací údaj zaseknutý ve stavu Rotuje se¶

Pokud přihlašovací údaj zůstane ve stavu Rotuje se, bude automaticky obnoven watchdogem na pozadí do 30 minut. Není třeba žádné manuální akce.

Pokud potřebujete rotaci odblokovat okamžitě, ověřte: - Žádný jiný přihlašovací údaj stejné aplikace není aktivně rotován (zkontrolujte historii rotací) - Aplikace stále existuje v Azure a je přístupná přes konfigurovanou integraci - Přihlašovací údaje integrace (tenant ID, client ID, secret nebo managed identity) jsou platné

Sync vrací 409 Conflict¶

Pokud POST /api/v1/entra/{integrationId}/sync vrací 409 Conflict, integrace je obvykle nakonfigurována pro scope selected_apps, ale zatím k ní nejsou přiřazeny žádné bindingy vybraných aplikací.

Ověřte: - K integraci je přiřazena alespoň jedna vybraná Entra aplikace - Režim scope má skutečně zůstat selected_apps; jinak jej přepněte zpět na synchronizaci celého tenanta - Stav integrace je během nedokončeného onboardingu pending, nikoli failed

Chování na pozadí: - Hodinový plánovač synchronizace Entra tuto integraci přeskočí, dokud neexistuje seznam vybraných aplikací - last_sync_error zůstává prázdné, takže provozní dashboardy nehlásí tuto etapovou konfiguraci jako runtime výpadek

Údaje se nesynchronizují¶

Ověřte: - Integrace je povolena - Service principal má oprávnění Application.ReadWrite.All - Tenant ID a Client ID jsou správné