Autentizace¶
Metody autentizace MazeVault a integrace SSO
Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-10-28
1. Podporované metody autentizace¶
MazeVault podporuje více metod autentizace pro integraci s podnikovou identitní infrastrukturou:
| Metoda | Protokol | Případy použití | Licenční úroveň |
|---|---|---|---|
| Lokální autentizace | Heslo (webové rozhraní); v API je k dispozici i SRP | Samostatná nasazení | Všechny |
| LDAP / Active Directory | LDAP v3 | Integrace s on-premise adresářem | Enterprise |
| Azure Entra ID | OpenID Connect | Prostředí Azure/Microsoft 365 | Enterprise |
| GitHub SSO | OAuth 2.0 | Vývojové týmy | Enterprise |
| GitLab SSO | OAuth 2.0 | Vývojové týmy | Enterprise |
| SAML 2.0 | SAML | Podnikové federace identit | Enterprise |
| OAuth 2.0 Client Credentials | OAuth 2.0 | Komunikace služba-služba (API) | Všechny |
| Universal Auth | API Key | Nástroje CLI, automatizační skripty | Všechny |
| MazeVault Agent Auth | mTLS + Bootstrap Token | Komunikace agent-server | Všechny |
| API Token | Bearer Token | Programatický přístup k API | Všechny |
2. Lokální autentizace¶
Webové rozhraní přihlašuje lokální uživatele uživatelským jménem a heslem přes HTTPS. Heslo se odešle serveru MazeVault, který ho ověří proti uloženému hashi; server heslo v nešifrované podobě neukládá.
SRP
API navíc nabízí protokol Secure Remote Password (SRP) (POST /api/v1/auth/srp/init a /api/v1/auth/srp/verify) pro klienty API. Webové rozhraní ho nepoužívá, takže přihlášení přes web není zero-knowledge důkaz hesla: server heslo při přihlášení vidí.
Průběh přihlášení ve webovém rozhraní¶
sequenceDiagram
participant U as 🧑💻 Uživatel
participant B as 🌐 Prohlížeč
participant F as 🖥️ Server webového rozhraní (BFF)
participant S as ⚙️ MazeVault API
U->>B: Zadat přihlašovací údaje
B->>F: POST /bff/auth/login
F->>S: Přihlášení + tajemství BFF
S-->>F: Serverová relace (nebo čekající MFA)
F-->>B: Cookie __Host-session (bez tokenu v odpovědi)
B->>F: Požadavky s cookie
F->>S: Authorization: Session + X-MazeVault-BFFMetody přihlášení ve webovém rozhraní¶
| Metoda | Jak funguje |
|---|---|
| Lokální | Formulář s uživatelským jménem a heslem |
| LDAP / AD | Stejný formulář s volbou LDAP |
| Kerberos | Zobrazí se jen tehdy, když GET /api/v1/auth/sso/spnego/status hlásí dostupnost; prohlížeč pošle Authorization: Negotiate, který server webového rozhraní předá dál; požadavky z jiných webů se odmítají |
| SSO (Entra ID) | Prohlížeč přejde na /api/v1/auth/sso/entra/login, vrátí se na /login s jednorázovým kódem a stránka kód vymění za relaci. Chyby zobrazí jeden z pevných kódů invalid_state, sso_not_configured, missing_auth_code, missing_code_or_state |
| MFA | Pokud má uživatel MFA, přihlášení skončí v čekajícím stavu a stránka /mfa požádá o kód TOTP nebo záložní kód v jednom poli; úspěch vydá novou aktivní relaci |
Webové rozhraní zobrazuje jen tlačítko SSO Entra ID. Endpointy přihlášení přes GitHub, GitLab a SAML v API stále existují, ale ve webovém rozhraní pro ně tlačítko není. Po úspěšném přihlášení je uživatel s vynucenou změnou hesla (must_change_passwd) přesměrován na /change-password a relaci si ponechá.
3. Integrace SSO¶
Azure Entra ID (OpenID Connect)¶
Konfigurační parametry vyžadované od vašeho tenanta Azure:
| Parametr | Popis |
|---|---|
| Tenant ID | Identifikátor tenanta Azure AD |
| Client ID | ID klienta registrace aplikace |
| Client Secret | Tajný klíč registrace aplikace |
| Redirect URI | Callback URL nakonfigurovaná v MazeVault |
Podporované funkce:
- Single Sign-On a Single Log-Out
- Automatické vytváření uživatelů při prvním přihlášení
- Mapování skupin na role
- Kompatibilita s politikami podmíněného přístupu
LDAP / Active Directory¶
| Parametr | Popis |
|---|---|
| Server URL | Adresa LDAP serveru (doporučeno ldaps://) |
| Bind DN | Distinguished name servisního účtu |
| Search Base | Základní DN pro vyhledávání uživatelů |
| User Filter | LDAP filtr pro vyhledávání uživatelů |
| Group Search Base | Základní DN pro vyhledávání skupin (volitelné) |
| TLS | Vyžadováno pro produkci (LDAPS nebo StartTLS) |
4. Vícefaktorová autentizace (MFA)¶
MazeVault podporuje vícefaktorovou autentizaci založenou na TOTP:
- Kompatibilní s Google Authenticator, Microsoft Authenticator, Authy a dalšími TOTP aplikacemi
- Registrace prostřednictvím QR kódu
- Záložní přístupové kódy (recovery codes)
- MFA lze vynutit na úrovni organizace (všichni uživatelé) nebo podle role
Matice vynucení MFA¶
| Konfigurace | Popis |
|---|---|
| Zakázáno | MFA volitelné pro všechny uživatele |
| Volitelné | Uživatelé si mohou MFA sami aktivovat |
| Povinné pro administrátory | Povinné pro role administrátorů |
| Povinné pro všechny | Povinné pro všechny uživatele |
5. Správa relací¶
| Parametr | Výchozí hodnota | Konfigurovatelné |
|---|---|---|
| Relace webu, časový limit nečinnosti | 30 minut (UI_SESSION_IDLE_TIMEOUT) |
✅ |
| Relace webu, absolutní životnost | 12 hodin (UI_SESSION_ABSOLUTE_TIMEOUT) |
✅ |
| Čekající krok MFA | 5 minut (UI_SESSION_MFA_TIMEOUT) |
✅ |
| Úložiště relací (webové rozhraní) | Na serveru, v databázi | — |
| Cookie | __Host-session: Secure; HttpOnly; SameSite=Strict; Path=/ |
— |
Relace prohlížeče (BFF)¶
Webové rozhraní drží relace na serveru. Prohlížeč má pouze cookie __Host-session, jejíž platnost odpovídá konci relace; token se do prohlížeče nikdy nevrací. Server webového rozhraní (BFF) nabízí POST /bff/auth/login, ldap-login, sso-exchange, mfa-verify, logout a GET /bff/auth/spnego-login; všechna ostatní volání jdou jen přes /bff/api/v1/... a /bff/api/v2/.... BFF kontroluje původ každého požadavku měnícího stav (hlavička Origin se musí rovnat NUXT_PUBLIC_ORIGIN, jinak 403) a backendu předkládá relaci jako Authorization: Session spolu s tajemstvím X-MazeVault-BFF (BFF_SHARED_SECRET); bez tajemství je schéma vypnuté. Ukládá se pouze hash tokenu. Endpointy přihlášení mají rate limit.
- Časové limity: relace končí po 30 minutách nečinnosti (
UI_SESSION_IDLE_TIMEOUT) nebo celkem po 12 hodinách (UI_SESSION_ABSOLUTE_TIMEOUT); čekající krok MFA vyprší po 5 minutách (UI_SESSION_MFA_TIMEOUT) a povolí nejvýše 5 pokusů o kód, poslední neúspěch čekající přihlášení ukončí. - Vypršení: vypršená relace pošle uživatele na
/login?redirect=<stránka>a po dalším přihlášení zpět na tuto stránku. Pokud je backend dočasně nedostupný (5xx nebo chyba sítě), relace se zachová. - Odvolání: odhlášení a automaticky při změně hesla (všechny relace kromě volající), smazání uživatele, přiřazení, změně nebo odebrání role, vypnutí MFA a změně rolí přes SSO/LDAP. Administrátoři mohou relace uživatele vypsat a zrušit přes
GET/DELETE /api/v1/rbac/users/{id}/sessions.
CLI, poskytovatel Terraform a další klienti API dál používají tokeny Bearer a API tokeny (viz níže); relace prohlížeče nejsou autentizační metodou pro integrace.
Struktura tokenů (klienti API a CLI)¶
Klienti API a CLI používají JWT (JSON Web Tokens):
- Algoritmus: RS256 (RSA s SHA-256)
- Životnost tokenu: Konfigurovatelná (výchozí 24 hodin)
- Obnovení: Automatické obnovení tokenu před vypršením
- Odvolání: Okamžité odvolání prostřednictvím blokového seznamu podporovaného Redis
- Claimy: ID uživatele, organizace, role, oprávnění, přístup k projektům
6. Autentizace API¶
OAuth 2.0 Client Credentials¶
Pro integrace služba-služba:
POST /api/v1/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>
Universal Auth (API Key)¶
Pro nástroje CLI a automatizaci:
POST /api/v1/auth/universal
Content-Type: application/json
{
"client_id": "<your-client-id>",
"client_secret": "<your-client-secret>"
}
Použití Bearer tokenu¶
Všechny autentizované API požadavky používají získaný token:
7. Autentizace agentů¶
Agenti MazeVault používají dvoufázový autentizační postup — nejprve bootstrap, poté certifikát:
sequenceDiagram
participant A as 🤖 Agent
participant S as 🖥️ MazeVault API
rect rgb(235, 245, 251)
Note over A,S: 🔑 Počáteční registrace
A->>S: POST /agents/register (bootstrap_token)
S-->>A: ID agenta + Klientský certifikát
end
rect rgb(232, 245, 233)
Note over A,S: 🔒 Průběžná komunikace (mTLS)
A->>S: mTLS spojení (klientský certifikát)
S->>S: Validovat certifikát + extrahovat ID agenta
S-->>A: Autorizovaná odpověď
endSouvisející¶
- Přehled bezpečnosti — Bezpečnostní architektura
- Šifrování — Kryptografické standardy
- Začínáme s API — Příklady autentizace API