Konfigurace Azure identit a oprávnění¶

Kompletní nastavení Azure Entra ID, Managed Identity a RBAC pro MazeVault

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-09
Licenční úroveň: Enterprise+

Tento dokument specifikuje všechny Azure identitní objekty, které MazeVault vyžaduje. Je určen jako přesné zadání pro infrastrukturní tým — postupujte podle jednotlivých sekcí a nakonfigurujte všechny app registrace, managed identity, RBAC role a federované přihlašovací údaje.

Oddělení prostředí

Vytvořte samostatné app registrace a managed identity pro každé prostředí (např. NPR, PRO). Nikdy nesdílejte přihlašovací údaje mezi prostředími.

1. Přehled¶

graph TB
    subgraph EntraID["🆔 Azure Entra ID"]
        SSO["App Reg #1<br/><b>MazeVault SSO</b><br/>Přihlášení + OBO"]
        Email["App Reg #2<br/><b>MazeVault Email</b><br/>Graph Mail.Send"]
        EntraMgmt["App Reg #3<br/><b>MazeVault Entra Mgmt</b><br/>Správa app/credentials"]
        TFSP["Service Principal<br/><b>Terraform / CI-CD</b><br/>Deploy infrastruktury"]
    end

    subgraph Azure["☁️ Azure Resources"]
        MI["🔐 User-Assigned<br/>Managed Identity"]
        KVgw["🗝️ Gateway<br/>Key Vault"]
        KVproj["🗝️ Projektový<br/>Key Vault"]
        SQL["🗄️ Azure SQL"]
        AKS["☸️ AKS Cluster"]
        ACR["📦 Container<br/>Registry"]
    end

    subgraph AKSPods["☸️ AKS Pody"]
        BEPod["⚙️ Backend Pod"]
        GWPod["🌐 Gateway Pod"]
        ESO["🔄 External Secrets<br/>Operator"]
    end

    SSO -->|OBO tokeny| BEPod
    Email -.->|Mail.Send grant| MI
    EntraMgmt -->|Graph API| BEPod
    MI -->|RBAC| KVgw
    MI -->|RBAC| KVproj
    BEPod -->|Workload Identity| MI
    GWPod -->|Workload Identity| MI
    ESO -->|Workload Identity| MI
    ESO -->|Sync secrets| KVgw
    BEPod -->|SQL Auth| SQL
    TFSP -->|Admin| KVgw
    TFSP -->|Admin| KVproj
    AKS -.->|AcrPull| ACR

    classDef identity fill:#E8EAF6,stroke:#3F51B5,stroke-width:2px,color:#283593
    classDef resource fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px,color:#2E7D32
    classDef pod fill:#FFF8E1,stroke:#FF9800,stroke-width:2px,color:#E65100

    class SSO,Email,EntraMgmt,TFSP identity
    class MI,KVgw,KVproj,SQL,AKS,ACR resource
    class BEPod,GWPod,ESO pod

Souhrnná tabulka¶

#	Identitní objekt	Typ	Účel	Konfigurace
1	MazeVault SSO	App Registration	Přihlášení uživatelů + OBO přístup ke zdrojům	Proměnné prostředí
2	MazeVault Email	App Registration	E-mailové notifikace přes Graph API	Proměnné prostředí
3	MazeVault Entra Management	App Registration	Rotace app credentials a synchronizace	MazeVault UI (per-integrace)
4	MazeVault System Identity	User-Assigned Managed Identity	Key Vault a HSM operace na pozadí	Proměnné prostředí
5	Workload Identity Federation	Federované přihlašovací údaje na MI	AKS pody → MI autentizace	AKS + MI konfigurace
6	Azure DevOps PAT	Personal Access Token	CI/CD sync proměnných a Helm	MazeVault UI (per-integrace)
7	Terraform / CI-CD SP	Service Principal	Provisioning infrastruktury	CI/CD pipeline

2. App Registration #1 — MazeVault SSO + On-Behalf-Of¶

Účel: Přihlášení uživatelů přes OpenID Connect a On-Behalf-Of (OBO) výměna tokenů, aby backend mohl přistupovat k Azure zdrojům (Key Vaults, subscriptions, SQL servery) v bezpečnostním kontextu uživatele.

Doporučený název: APP_MZV_INT_{ENV}_01 (např. APP_MZV_INT_PRO_01)

2.1 API Oprávnění¶

Delegovaná oprávnění (vyžadují přihlášení uživatele)¶

API	Oprávnění	GUID oprávnění	Admin Consent	Účel
Microsoft Graph	`openid`	`37f7f235-527c-4136-accd-4a02d197296e`	Ne	OIDC přihlášení
Microsoft Graph	`profile`	`14dad69e-099b-42c9-810b-d002981feec1`	Ne	Zobrazované jméno uživatele
Microsoft Graph	`email`	`64a6cdd6-aab1-4aaf-94b8-3cc8405e90d0`	Ne	E-mail uživatele
Microsoft Graph	`User.Read`	`e1fe6dd8-ba31-4d61-89e7-88639da4683d`	Ne	Čtení profilu uživatele
Microsoft Graph	`GroupMember.Read.All`	`bc024368-1153-4739-b217-4326f2e966d0`	Ano	Mapování skupin na role
Microsoft Graph	`offline_access`	`7427e0e9-2fba-42fe-b0c0-848c9e6a8182`	Ne	Refresh token pro OBO
Azure Key Vault	`user_impersonation`	`f53da476-18e3-4152-8e01-aec403e6edc0`	Ne	Prohlížení Key Vault uživatelem
Azure Service Management	`user_impersonation`	`41094075-9dad-400e-a0bd-54e686782033`	Ne	Vyhledávání subscriptions a zdrojů

ID API zdrojů

Microsoft Graph: 00000003-0000-0000-c000-000000000000
Azure Key Vault: cfa8b339-82a2-471a-a3c9-0fc0be7a4093
Azure Service Management: 797f4846-ba00-4fd7-ba43-dac1f8f63013

Aplikační oprávnění (bez kontextu uživatele — záložní varianta)¶

API	Oprávnění	GUID oprávnění	Admin Consent	Účel
Microsoft Graph	`Application.Read.All`	`9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30`	Ano	Vyhledávání app registrací (záloha pokud OBO není dostupné)

2.2 Autentizační platforma¶

Nastavení	Hodnota
Typ platformy	Web
Redirect URI	`https://<BACKEND_NEBO_PUBLIC_API_HOST>/api/v1/auth/sso/entra/callback`
ID tokeny	✅ Povoleno
Access tokeny	❌ Zakázáno

Redirect URI

Nahraďte <BACKEND_NEBO_PUBLIC_API_HOST> skutečným veřejným API hostem MazeVault backendu (např. https://mazevault.firma.cz). Callback cesta /api/v1/auth/sso/entra/callback je pro tento model nasazení povinná.

2.3 Client Secret¶

Vytvořte client secret a uložte jeho hodnotu bezpečně do Azure Key Vault. Tento secret je nutný pro:

Výměnu autorizačního kódu (confidential client)
Výměnu refresh tokenu (OBO tok)

2.4 RBAC mapování — App Roles a Security Groups¶

MazeVault mapuje uživatele z Entra ID na interní role pomocí dvou mechanismů. App Roles jsou doporučená primární metoda. Security Groups jsou podporovány jako alternativa.

App Roles (Doporučeno)¶

App Roles se definují v manifestu App Registration a přiřazují uživatelům na Enterprise Application. Po přiřazení se automaticky zobrazí jako claim roles v ID tokenu — žádná konfigurace volitelných claims není potřeba.

Krok 1 — Definice App Roles v App Registration:

Přejděte na App registrations → vaše SSO aplikace → App roles → Create app role
Nastavte:

Pole	Hodnota
Display name	např. `APP_MZV_PRO_ADMIN`
Allowed member types	Users/Groups
Value	např. `APP_MZV_PRO_ADMIN` (tato hodnota se objeví v claimu `roles`)
Description	MazeVault administrátorská role

Opakujte pro každou MazeVault roli, kterou chcete mapovat (např. APP_MZV_PRO_OPERATOR, APP_MZV_PRO_VIEWER).

Krok 2 — Přiřazení uživatelů k App Roles na Enterprise Application:

Přejděte na Entra ID → Enterprise applications → najděte odpovídající Enterprise App
Users and groups → Add user/group
Vyberte uživatele, poté vyberte App Role k přiřazení
Klikněte na Assign

Krok 3 — Vytvoření mapování v MazeVault:

V MazeVault UI pod Access Control → Group/App Role Mappings vytvořte mapování, kde External ID odpovídá hodnotě App Role value (např. APP_MZV_PRO_ADMIN) a cílem je požadovaná MazeVault role.

Jak to funguje

Když se uživatel s přiřazenou App Role přihlásí přes SSO, ID token obsahuje claim roles s hodnotami App Roles. MazeVault tyto hodnoty porovná s nakonfigurovanými mapováními a přiřadí odpovídající roli. Pro App Roles nejsou potřeba žádné další konfigurace tokenů ani volitelné claims.

Security Groups (Alternativa)¶

Pokud preferujete používat Entra ID Security Groups místo App Roles, přidejte volitelný claim groups:

Přejděte na Token configuration → Add optional claim → ID token → vyberte groups

Claim	Typ tokenu	Další vlastnosti
`groups`	ID Token	—

Poté nastavte groupMembershipClaims na SecurityGroup v manifestu App Registration.

V MazeVault vytvořte mapování, kde External ID je Object ID Security Groups (UUID).

NEPOVOLUJTE emit_as_roles

Při přidávání volitelného claimu groups Azure nabízí checkbox emit_as_roles. NEPOVOLUJTE ho. Převádí Object ID skupin do claimu roles, čímž dochází ke konfliktu s hodnotami App Roles a dojde k rozbití RBAC mapování. Toto bylo ověřeno jako chybná konfigurace.

Přetečení skupin (Groups Overage)

Pokud je uživatel členem více než 150 skupin, Azure vynechá claim groups z tokenu. MazeVault toto automaticky detekuje a stáhne členství ve skupinách přes Microsoft Graph API (/me/memberOf). Žádná další konfigurace není nutná — delegované oprávnění GroupMember.Read.All toto řeší.

Souhrn volitelných claims¶

Nakonfigurujte tyto volitelné claims na ID tokenu:

Claim	Typ tokenu	Další vlastnosti	Povinné?
`email`	ID Token	—	Ano (vždy)
`groups`	ID Token	— (NEZAŠKRTÁVEJTE `emit_as_roles`)	Pouze při použití Security Groups

2.5 On-Behalf-Of (OBO) výměna tokenů — Jak funguje¶

Backend ukládá zašifrovaný refresh token uživatele a vyměňuje ho za přístupové tokeny s konkrétním scope. Delegovaná oprávnění user_impersonation na Key Vault a Service Management API toto umožňují.

Scope vyměňované za běhu:

Scope	Zdroj	Funkce v MazeVault
`https://graph.microsoft.com/.default`	Microsoft Graph	Vyhledávání app registrací, členství ve skupinách
`https://management.azure.com/.default`	Azure Resource Manager	Vyhledávání subscriptions, Key Vaults, SQL serverů
`https://vault.azure.net/.default`	Azure Key Vault	Prohlížení Key Vault secrets v kontextu uživatele
`https://database.windows.net/.default`	Azure SQL	Federovaná autentizace SQL (budoucí funkce)

Nejsou potřeba další API oprávnění

Výše uvedené OBO scope používají oprávnění user_impersonation již nakonfigurovaná v sekci 2.1. Žádná extra registrace API oprávnění není nutná — scope se řeší za běhu přes suffix .default.

Kritické: Rozdíl mezi Application a Delegated oprávněními

Výměna tokenů používá grant_type: refresh_token. Tokeny získané tímto způsobem obsahují pouze Delegated oprávnění — Application oprávnění nikdy nejsou zahrnuta.

Častá chyba konfigurace: Přidání Graph oprávnění jako Directory.Read.All, Group.Read.All nebo User.Read.All jako Application místo požadovaných Delegated. To způsobuje tiché selhání:

OBO výměna pro https://graph.microsoft.com/.default vrátí token bez dostatečného scope
GET /v1.0/applications selže (potřebuje Application.Read.All delegované nebo ekvivalent)
/me/memberOf selže → mapování skupin na role nefunguje (potřebuje GroupMember.Read.All delegované)

Pokud OBO výměna tokenů selhává, ověřte:

✅ Všechna oprávnění v sekci 2.1 jsou nastavena jako Delegated (ne Application)
✅ offline_access je přítomen jako Delegated — bez něj se nevydá refresh token a všechny OBO výměny selžou
✅ GroupMember.Read.All je Delegated — Group.Read.All (Application) ho nenahrazuje
✅ Admin consent byl udělen pro GroupMember.Read.All
✅ Uživatel se znovu přihlásil po změně oprávnění (existující relace používají staré tokeny)

Oprávnění, která na této app registraci NEJSOU potřeba:

Directory.Read.All (App), Group.Read.All (App), User.Read.All (App), RoleManagement.Read.Directory (App) — MazeVault SSO je nepoužívá a měla by být odebrána dle principu nejmenšího oprávnění.

2.6 Proměnné prostředí¶

Proměnná	Hodnota	Popis
`ENTRA_ENABLED`	`true`	Povolit Entra ID SSO
`ENTRA_TENANT_ID`	`<id-vašeho-tenanta>`	Azure AD tenant ID
`ENTRA_CLIENT_ID`	`<client-id-aplikace>`	Application (client) ID z této registrace
🔐 `ENTRA_CLIENT_SECRET`	`<client-secret>`	Hodnota client secret — uložte v Key Vault
`ENTRA_REDIRECT_URI`	`https://<BACKEND_NEBO_PUBLIC_API_HOST>/api/v1/auth/sso/entra/callback`	Musí odpovídat redirect URI nakonfigurovanému výše

2.7 Azure Portal — Krok za krokem¶

Entra ID → App registrations → New registration
Název: APP_MZV_INT_{ENV}_01
Podporované typy účtů: Single tenant
Redirect URI: Web — https://<BACKEND_NEBO_PUBLIC_API_HOST>/api/v1/auth/sso/entra/callback
API permissions → Add a permission → Přidejte každé oprávnění ze sekce 2.1
Grant admin consent pro tenant (nutné pro GroupMember.Read.All a Application.Read.All)
Certificates & secrets → New client secret → Zkopírujte a uložte do Key Vault
Token configuration → Add optional claim → ID token → email. Pokud používáte Security Groups, přidejte také groups (NEZAŠKRTÁVEJTE emit_as_roles)
App roles → Create app role → Definujte role odpovídající vašim MazeVault RBAC mapováním (např. APP_MZV_PRO_ADMIN)
Enterprise Applications → Najděte odpovídající Enterprise App → Users and groups → Přiřaďte uživatele k App Roles
Authentication → Implicit grant → Zaškrtněte pouze ID tokens

3. App Registration #2 — MazeVault Email (Office 365)¶

Účel: Odesílání e-mailových notifikací (reset hesel, upozornění na expiraci certifikátů, stav rotací) přes Microsoft Graph sendMail API.

Doporučený název: APP_MZV_EMAIL_{ENV}_01

3.1 API Oprávnění¶

API	Oprávnění	Typ	GUID oprávnění	Admin Consent
Microsoft Graph	`Mail.Send`	Aplikační	`b633e1c5-b582-4048-a93e-9f11b44c7e96`	Ano

Aplikační oprávnění

Mail.Send je aplikační oprávnění (ne delegované). To umožňuje backendu odesílat e-maily jako daemon bez interakce uživatele. Admin consent je povinný.

3.2 Metoda autentizace¶

MazeVault podporuje tři metody autentizace pro tuto app registraci. Managed Identity je doporučená pro nasazení na Azure:

Managed Identity (Doporučeno)Client SecretCertifikát

Za běhu není potřeba žádný client secret. Backend se autentizuje pomocí User-Assigned Managed Identity (Identita #4).

App registrace je stále nutná pro grant oprávnění Mail.Send — ale autentizace za běhu jde přes Managed Identity.

Proměnná	Hodnota
`O365_EMAIL_ENABLED`	`true`
`O365_TENANT_ID`	`<tenant-id>`
`O365_CLIENT_ID`	`<client-id-této-aplikace>`
`O365_SENDER_EMAIL`	`noreply@firma.cz`
`O365_AUTH_METHOD`	`managed_identity`
`O365_MANAGED_IDENTITY_CLIENT_ID`	Stejná hodnota jako `AZURE_MANAGED_IDENTITY_CLIENT_ID`

Proměnná	Hodnota
`O365_EMAIL_ENABLED`	`true`
`O365_TENANT_ID`	`<tenant-id>`
`O365_CLIENT_ID`	`<client-id-této-aplikace>`
🔐 `O365_CLIENT_SECRET`	`<client-secret>`
`O365_SENDER_EMAIL`	`noreply@firma.cz`
`O365_AUTH_METHOD`	`client_secret`

Proměnná	Hodnota
`O365_EMAIL_ENABLED`	`true`
`O365_TENANT_ID`	`<tenant-id>`
`O365_CLIENT_ID`	`<client-id-této-aplikace>`
`O365_SENDER_EMAIL`	`noreply@firma.cz`
`O365_AUTH_METHOD`	`certificate`
`O365_CERTIFICATE_PATH`	`/cesta/k/cert.pfx`
🔐 `O365_CERTIFICATE_PASSWORD`	`<heslo-pfx>`

E-mail odesílatele

O365_SENDER_EMAIL musí být platná poštovní schránka nebo sdílená schránka ve vašem tenantovi. Managed Identity nebo service principal musí mít oprávnění odesílat jako tato schránka.

3.3 Azure Portal — Krok za krokem¶

Entra ID → App registrations → New registration
Název: APP_MZV_EMAIL_{ENV}_01
Podporované typy účtů: Single tenant
Redirect URI není potřeba
API permissions → Add a permission → Microsoft Graph → Application permissions → Mail.Send
Grant admin consent pro tenant

4. App Registration #3 — MazeVault Entra Management¶

Účel: Správa Azure AD app registrací, rotace client secrets a certifikátů, synchronizace service principalů. Používáno funkcí Entra Token Rotation.

Doporučený název: APP_MZV_ENTRA_{ENV}_01

Metoda konfigurace

Tato identita se NEkonfiguruje přes proměnné prostředí. Konfiguruje se v MazeVault UI: Project → Integrations → Add Integration → Microsoft Entra ID.

4.1 API Oprávnění¶

API	Oprávnění	Typ	GUID oprávnění	Admin Consent
Microsoft Graph	`Application.ReadWrite.All`	Aplikační	`1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9`	Ano
Microsoft Graph	`Directory.Read.All`	Aplikační	`7ab1d382-f21e-4acd-a863-ba3e13f7da61`	Ano

Budoucí (Fáze 5):

API	Oprávnění	Typ	GUID oprávnění	Admin Consent
Microsoft Graph	`AppRoleAssignment.ReadWrite.All`	Aplikační	`06b708a9-e830-4db3-a914-8e69da51d44f`	Ano

4.2 Metody autentizace¶

Tato registrace podporuje tři metody autentizace, konfigurované v nastavení integrace MazeVault:

Metoda	Konfigurační klíče	Případ použití
Client Secret	`tenant_id`, `client_id`, `client_secret`	Výchozí — služba-služba
Managed Identity	`tenant_id`, `client_id` (volitelné)	Nasazení na Azure
Certifikát	`tenant_id`, `client_id`, `certificate_path`, `certificate_password`	Zvýšená bezpečnost

4.3 Prováděné Microsoft Graph operace¶

Tato identita provádí následující Graph API operace:

Operace	Graph Endpoint	HTTP Metoda
Seznam app registrací	`/v1.0/applications`	GET
Vytvoření app registrace	`/v1.0/applications`	POST
Aktualizace app registrace	`/v1.0/applications/{id}`	PATCH
Smazání app registrace	`/v1.0/applications/{id}`	DELETE
Přidání client secret	`/v1.0/applications/{id}/addPassword`	POST
Odebrání client secret	`/v1.0/applications/{id}/removePassword`	POST
Přidání certifikátu	`/v1.0/applications/{id}/addKey`	POST
Odebrání certifikátu	`/v1.0/applications/{id}/removeKey`	POST
Seznam service principalů	`/v1.0/servicePrincipals`	GET
Vytvoření service principala	`/v1.0/servicePrincipals`	POST
Aktualizace service principala	`/v1.0/servicePrincipals/{id}`	PATCH
Smazání service principala	`/v1.0/servicePrincipals/{id}`	DELETE
Seznam app role assignments	`/v1.0/servicePrincipals/{id}/appRoleAssignments`	GET
Seznam OAuth2 grantů	`/v1.0/servicePrincipals/{id}/oauth2PermissionGrants`	GET
Test spojení	`/v1.0/organization`	GET

4.4 Azure Portal — Krok za krokem¶

Entra ID → App registrations → New registration
Název: APP_MZV_ENTRA_{ENV}_01
Podporované typy účtů: Single tenant
Redirect URI není potřeba
API permissions → Add a permission → Microsoft Graph → Application permissions → Application.ReadWrite.All, Directory.Read.All
Grant admin consent pro tenant
Certificates & secrets → Vytvořte client secret (nebo nahrajte certifikát)
Zkopírujte Tenant ID, Client ID a Client Secret — zadejte je v MazeVault při vytváření Entra ID integrace

5. User-Assigned Managed Identity¶

Účel: Systémová autentizace pro operace na pozadí — rotace secrets v Key Vault, push/pull certifikátů, generování a podepisování HSM klíčů, synchronizace External Secrets Operator.

Doporučený název: id-mazevault-{env}-{region} (např. id-mazevault-pro-gwc)

5.1 Vytvoření Managed Identity¶

az identity create \
  --resource-group rg-mazevault-<env> \
  --name id-mazevault-<env>-<region>

5.2 RBAC Role Assignments v Azure¶

Gateway Key Vault (konfigurační trezor)¶

Role	Účel	Operace
Key Vault Secrets User	Čtení konfiguračních secrets (Entra creds, DB URL, TLS certs)	`GetSecret`, `ListSecrets`

az role assignment create \
  --assignee <principal-id-managed-identity> \
  --role "Key Vault Secrets User" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<gateway-kv>

Projektové Key Vault(y) (úložiště secrets a certifikátů)¶

Role	Účel	Operace
Key Vault Secrets Officer	Čtení/zápis secrets při rotaci a synchronizaci	`GetSecret`, `SetSecret`, `DeleteSecret`, `ListSecrets`
Key Vault Crypto Officer	HSM operace s klíči pro podepisování certifikátů	`CreateKey`, `Sign`, `GetKey`, `DeleteKey`, `Verify`

# Přístup k secrets
az role assignment create \
  --assignee <principal-id-managed-identity> \
  --role "Key Vault Secrets Officer" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<project-kv>

# HSM / Crypto přístup
az role assignment create \
  --assignee <principal-id-managed-identity> \
  --role "Key Vault Crypto Officer" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<project-kv>

Crypto Officer vs Crypto User

Pokud nepoužíváte generování HSM klíčů (pouze podepisování existujícími klíči), stačí Key Vault Crypto User místo Key Vault Crypto Officer.

5.3 Reference operací Key Vault¶

Managed Identity provádí tyto Azure SDK operace:

Secrets (azsecrets SDK):

Operace	Používáno	Směr
`SetSecret()`	Rotace secrets, export certifikátů, post-rotační sync	Zápis
`GetSecret()`	Pre-rotační sync, načtení pro porovnání	Čtení
`DeleteSecret()`	Čištění (volitelné)	Smazání
`ListSecrets()`	Health check, sledování změn	Čtení

Klíče/HSM (azkeys SDK):

Operace	Používáno	Směr
`CreateKey()`	Generování RSA-HSM / EC-HSM páru klíčů	Zápis
`Sign()`	Podepisování certifikátů (RS256)	Výpočet
`GetKey()`	Získání veřejného klíče	Čtení
`DeleteKey()`	Správa životního cyklu klíčů	Smazání

5.4 Proměnné prostředí¶

Proměnná	Hodnota	Popis
`AZURE_MANAGED_IDENTITY_CLIENT_ID`	`<mi-client-id>`	Client ID user-assigned managed identity
`AZURE_TENANT_ID`	`<tenant-id>`	Azure AD tenant ID

6. Workload Identity Federation (AKS ↔ Managed Identity)¶

Účel: Umožnit AKS podům autentizovat se jako Managed Identity (#5) pomocí OIDC výměny tokenů — žádné přihlašovací údaje uložené v clusteru.

6.1 Konfigurace AKS clusteru¶

Ujistěte se, že AKS cluster má povolenou workload identity:

az aks update \
  --resource-group rg-mazevault-<env> \
  --name aks-mazevault-<env> \
  --enable-oidc-issuer \
  --enable-workload-identity

Povolení Key Vault CSI ovladače s automatickou rotací:

az aks enable-addons \
  --resource-group rg-mazevault-<env> \
  --name aks-mazevault-<env> \
  --addons azure-keyvault-secrets-provider \
  --enable-secret-rotation \
  --rotation-poll-interval 2m

6.2 Federované přihlašovací údaje¶

Vytvořte federované přihlašovací údaje na Managed Identity pro každý service account:

External Secrets Operator (ESO):

az identity federated-credential create \
  --identity-name id-mazevault-<env>-<region> \
  --resource-group rg-mazevault-<env> \
  --name fic-mazevault-eso \
  --issuer <AKS_OIDC_ISSUER_URL> \
  --subject system:serviceaccount:mazevault:mazevault-sa \
  --audiences api://AzureADTokenExchange

Gateway / Backend Pod:

az identity federated-credential create \
  --identity-name id-mazevault-<env>-<region> \
  --resource-group rg-mazevault-<env> \
  --name fic-mazevault-gateway-sa \
  --issuer <AKS_OIDC_ISSUER_URL> \
  --subject system:serviceaccount:mazevault:mazevault-gateway-sa \
  --audiences api://AzureADTokenExchange

Subject musí přesně sedět

Pokud subject federovaného cred neodpovídá skutečnému service accountu, mount secretů v podu selže s chybou AADSTS700213.

OIDC Issuer URL

Získejte URL issuera příkazem:
az aks show --name aks-mazevault-<env> --resource-group rg-mazevault-<env> --query "oidcIssuerProfile.issuerUrl" -o tsv

6.3 External Secrets Operator — Synchronizované secrets¶

ESO synchronizuje tyto secrets z Gateway Key Vault do Kubernetes každých 5 minut:

K8s Secret Key	Název secretu v Key Vault	Interval obnovy
`DATABASE_URL`	`mazevault-database-url`	5 min
`REDIS_URL`	`mazevault-redis-url`	5 min
`MAZEVAULT_MASTER_KEY`	`mazevault-master-key`	5 min
`MAZEVAULT_JWT_KEY`	`mazevault-jwt-key`	5 min
`MAZEVAULT_SESSION_SECRET`	`mazevault-session-secret`	5 min
`ENTRA_TENANT_ID`	`mazevault-entra-tenant-id`	5 min
`ENTRA_CLIENT_ID`	`mazevault-entra-client-id`	5 min
`ENTRA_CLIENT_SECRET`	`mazevault-entra-client-secret`	5 min
`ENTRA_REDIRECT_URI`	`mazevault-entra-redirect-uri`	5 min
TLS Certifikát	`mazevault-tls-cert`	1 hodina
TLS Privátní klíč	`mazevault-tls-key`	1 hodina

Názvy secrets v Key Vault

Názvy secrets v Key Vault (pravý sloupec) musí přesně odpovídat. Naplňte je při provisioningu infrastruktury před prvním nasazením.

7. Azure DevOps integrace (PAT)¶

Účel: Synchronizace rotovaných secrets do Azure DevOps pipeline proměnných skupin nebo aktualizace Helm chart values v Git repozitářích.

Metoda konfigurace

Azure DevOps integrace NENÍ app registrace. Používá Personal Access Token (PAT) konfigurovaný v MazeVault UI: Project → Integrations → Add Integration → Azure DevOps.

7.1 Požadované PAT scope¶

Scope	Úroveň přístupu	Účel
Code	Read & Write	Aktualizace Helm values souborů v Gitu
Build	Read & Execute	Spuštění pipeline po aktualizaci proměnných
Variable Groups	Read & Manage	Aktualizace hodnot pipeline proměnných skupin

7.2 Podporované režimy synchronizace¶

Režim	Používané API	Popis
Variable Group	`dev.azure.com/{org}/{project}/_apis/distributedtask/variablegroups/{id}`	Přímá aktualizace pipeline proměnných
Helm Values	`dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/pushes`	Commit aktualizovaných YAML values do Gitu

7.3 Konfigurace v MazeVault¶

Při vytváření integrace zadejte:

Pole	Popis
Organization	Název Azure DevOps organizace
Project	Název projektu
Token	Personal Access Token s výše uvedenými scope
Mode	`variable_group` nebo `helm_values`
Group ID	ID proměnné skupiny (pro režim variable_group)
Repository	Název Git repozitáře (pro režim helm_values)
Branch	Cílová větev (pro režim helm_values)
File Path	Cesta k YAML souboru values (pro režim helm_values)

8. Terraform / CI-CD Service Principal¶

Účel: Provisioning infrastruktury — Terraform apply, naplnění Key Vault secrets, správa AKS.

8.1 Požadované role¶

Cílový zdroj	Role	Účel
Gateway Key Vault	`Key Vault Administrator`	Naplnění počátečních secrets
Projektové Key Vault(y)	`Key Vault Administrator`	Naplnění počátečních secrets
Resource Group	`Contributor`	Vytváření/správa zdrojů
Container Registry	`AcrPull`	Povolení AKS stahovat images

9. Matice RBAC přístupu ke Key Vault¶

Souhrn všech identit a jejich přístupu ke Key Vault:

Identita	Gateway KV	Projektové KV	Účel
Managed Identity	Secrets User	Secrets Officer + Crypto Officer	Rotace na pozadí, sync, HSM
OBO (SSO uživatelé)	—	Delegované (per-user Azure RBAC)	Prohlížení v kontextu uživatele přes UI
Service Principal SSO aplikace (APP #1)	—	Secrets User nebo Secrets Officer	Integrační toky s `client_secret` autentizací
Terraform SP	Administrator	Administrator	Provisioning infrastruktury
ESO	Secrets User (přes MI)	—	Sync konfigurace do K8s

Princip nejmenšího oprávnění

Managed Identity má Secrets User (jen čtení) na Gateway KV, protože potřebuje pouze číst konfiguraci. Na projektových KV má Secrets Officer (čtení/zápis), kde probíhá rotace secrets.

9.1 Povinné OBO RBAC pro Azure Discovery a prohlížení Key Vault¶

Aby nevznikalo "0 subscriptions found" a pády OBO browse, uživatelé testující přes Entra SSO musí mít:

Scope	Minimální role	Proč je potřeba
Subscription	`Reader`	Nutné pro `GET /subscriptions` a ARM discovery endpointy
Projektový Key Vault	`Key Vault Secrets User`	Nutné pro `ListSecrets`/`GetSecret` v uživatelském kontextu

Přiřazení rolí (příklad):

az role assignment create \
  --role "Reader" \
  --assignee <user-object-id-nebo-upn> \
  --scope /subscriptions/<subscription-id>

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <user-object-id-nebo-upn> \
  --scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Důležité chování runtime

GET /api/v1/azure/user-permissions-summary může vrátit 200 s prázdným seznamem subscriptions, když OBO token exchange projde, ale uživatel nemá roli Reader na žádné subscription.

10. Azure SQL — Rotace hesel¶

SQL autentizace — ne Azure AD

MazeVault používá SQL nativní autentizaci (uživatelské jméno + heslo) pro rotaci databázových hesel. Pro tuto funkci nepotřebujete povolovat Azure AD autentizaci na vašich SQL serverech.

Co má infrastrukturní tým poskytnout¶

Požadavek	Popis
Síťový přístup	MazeVault backend musí mít přístup k SQL serveru na portu 1433
Admin účet	SQL admin přihlašovací údaje s oprávněními `ALTER USER` a `CREATE USER`
Firewall pravidla	Povolte rozsah IP adres MazeVault podů nebo použijte Private Endpoints

Vyhledávání Azure SQL serverů¶

MazeVault umí vyhledávat Azure SQL servery pro jednodušší onboarding. Toto používá OBO tok (App Registration #1) se scope https://management.azure.com/.default:

API: GET https://management.azure.com/subscriptions/{id}/providers/Microsoft.Sql/servers?api-version=2023-05-01-preview
Oprávnění: Přihlášený uživatel musí mít alespoň roli Reader na subscription
Žádná další konfigurace Azure identity nad rámec sekce 2 není nutná

11. Kubernetes RBAC (in-cluster)¶

Rotační pipeline MazeVault může přímo aktualizovat Kubernetes secrets a spouštět restart podů (bez agenta). Backend pod potřebuje K8s RBAC pro tyto operace.

Požadovaná ClusterRole¶

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: mazevault-rotation
rules:
  # Aktualizace K8s secrets po rotaci
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "update"]
  # Spuštění rolling restartů
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets", "daemonsets"]
    verbs: ["get", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: mazevault-rotation-binding
subjects:
  - kind: ServiceAccount
    name: mazevault-gateway
    namespace: mazevault
roleRef:
  kind: ClusterRole
  name: mazevault-rotation
  apiGroup: rbac.authorization.k8s.io

Rozsah

Pokud jsou cíle rotace omezeny na jeden namespace, použijte Role + RoleBinding místo ClusterRole pro přísnější zabezpečení.

Po vytvoření všech app registrací vyžadují následující oprávnění souhlas správce tenanta:

App Registration	Oprávnění	Typ
#1 SSO	`GroupMember.Read.All`	Delegované
#1 SSO	`Application.Read.All`	Aplikační
#2 Email	`Mail.Send`	Aplikační
#3 Entra Management	`Application.ReadWrite.All`	Aplikační
#3 Entra Management	`Directory.Read.All`	Aplikační

Pro udělení souhlasu: Entra ID → Enterprise applications → Vyberte aplikaci → Permissions → Grant admin consent for {tenant}

13. Kompletní mapa proměnných prostředí¶

Proměnná	Zdroj identity	Funkce
`ENTRA_ENABLED`	—	`true` pro povolení SSO
`ENTRA_TENANT_ID`	App Reg #1	SSO
`ENTRA_CLIENT_ID`	App Reg #1	SSO
🔐 `ENTRA_CLIENT_SECRET`	App Reg #1	SSO + OBO
`ENTRA_REDIRECT_URI`	App Reg #1	SSO callback
`O365_EMAIL_ENABLED`	—	`true` pro povolení Graph e-mailu
`O365_TENANT_ID`	App Reg #2	E-mail
`O365_CLIENT_ID`	App Reg #2	E-mail
`O365_SENDER_EMAIL`	—	Adresa odesílatele
`O365_AUTH_METHOD`	—	`managed_identity` (doporučeno)
`O365_MANAGED_IDENTITY_CLIENT_ID`	MI #5	E-mail přes MI
`AZURE_MANAGED_IDENTITY_CLIENT_ID`	MI #5	Operace na pozadí
`AZURE_TENANT_ID`	—	Tenant ID

Viz Reference proměnných prostředí pro kompletní seznam proměnných.

14. Ověření¶

MazeVault poskytuje vestavěné API endpointy pro ověření Azure oprávnění po nastavení.

Kontrola Managed Identity¶

POST /api/v1/admin/azure/mi-permissions-check
Authorization: Bearer <admin-jwt>

Otestuje přístup Managed Identity ke všem nakonfigurovaným Azure integracím. Vrátí per-integrační stav (success/failed/skipped) s MI Client ID.

Hranice běhu Managed Identity

Managed Identity autentizace funguje pouze v runtime, kde je dostupné Azure IMDS/Workload Identity (například AKS gateway pody). Lokální Docker Primary backend IMDS nemá a selže timeoutem ManagedIdentityCredential.

Proxy fallback

V aktuální verzi běží integrační Test Connection a ruční sync integrace v backendu, který request obslouží. Automatický fallback z lokálního Primary na Azure gateway se pro tyto endpointy neprovádí.

Souhrn OBO oprávnění uživatele¶

GET /api/v1/azure/user-permissions-summary
Authorization: Bearer <user-jwt>

Agreguje Azure subscriptions, Key Vaults a SQL servery viditelné pro přihlášeného uživatele přes OBO. Užitečné pro ověření, že SSO + OBO funguje správně.

Health Check¶

GET /api/v1/health

Vrátí stav jednotlivých komponent včetně připojení k databázi, Redis a Key Vault.

Souvisejíci¶

Nasazení na Azure AKS — Nastavení Kubernetes clusteru
Reference proměnných prostředí — Kompletní seznam proměnných
Autentizace — Konfigurace SSO
Průvodce rotací Entra tokenů — Používání funkce rotace Entra credentials
Helm Charts — Reference Helm values