Skip to content

Authentication

MazeVault Authentication Methods and SSO Integration

Document Version: 1.0.0
Last Updated: 2026-10-28

1. Supported Authentication Methods

MazeVault supports multiple authentication methods to integrate with enterprise identity infrastructure:

Method Protocol Use Case License Tier
Local Authentication Password (web interface); SRP also available in the API Standalone deployments All
LDAP / Active Directory LDAP v3 On-premise directory integration Enterprise
Azure Entra ID OpenID Connect Azure/Microsoft 365 environments Enterprise
GitHub SSO OAuth 2.0 Development teams Enterprise
GitLab SSO OAuth 2.0 Development teams Enterprise
SAML 2.0 SAML Enterprise identity federations Enterprise
OAuth 2.0 Client Credentials OAuth 2.0 Service-to-service (API) All
Universal Auth API Key CLI tools, automation scripts All
MazeVault Agent Auth mTLS + Bootstrap Token Agent-to-server communication All
API Token Bearer Token Programmatic API access All

2. Local Authentication

The web interface signs local users in with their username and password over HTTPS. The password is sent to the MazeVault server, which verifies it against the stored hash; the server never stores the plaintext password.

SRP

The API also offers the Secure Remote Password (SRP) protocol (POST /api/v1/auth/srp/init and /api/v1/auth/srp/verify) for API clients. The web interface does not use it, so the web sign-in is not a zero-knowledge password proof: the server sees the password during sign-in.

Web Interface Sign-In Flow

sequenceDiagram
    participant U as 🧑‍💻 User
    participant B as 🌐 Browser
    participant F as 🖥️ Web interface server (BFF)
    participant S as ⚙️ MazeVault API

    U->>B: Enter credentials
    B->>F: POST /bff/auth/login
    F->>S: Sign-in + BFF secret
    S-->>F: Server-side session (or pending MFA)
    F-->>B: Cookie __Host-session (no token in the response)
    B->>F: Requests with the cookie
    F->>S: Authorization: Session + X-MazeVault-BFF

Sign-In Methods in the Web Interface

Method How it works
Local Username and password form
LDAP / AD The same form with the LDAP option
Kerberos Shown only when GET /api/v1/auth/sso/spnego/status reports it as available; the browser sends Authorization: Negotiate, which the web interface server relays; cross-site requests are refused
SSO (Entra ID) The browser goes to /api/v1/auth/sso/entra/login, returns to /login with a one-time code, and the page exchanges the code for a session. Failures show one of the fixed errors invalid_state, sso_not_configured, missing_auth_code, missing_code_or_state
MFA When the user has MFA, sign-in ends in a pending state and the /mfa page asks for a TOTP code or a backup code in a single field; success issues a new active session

The web interface shows only the Entra ID SSO button. GitHub, GitLab and SAML sign-in endpoints still exist in the API but have no button in the web interface. After a successful sign-in a user with a forced password change (must_change_passwd) is sent to /change-password and keeps the session.

3. SSO Integration

Azure Entra ID (OpenID Connect)

Configuration parameters required from your Azure tenant:

Parameter Description
Tenant ID Azure AD tenant identifier
Client ID Application registration client ID
Client Secret Application registration secret
Redirect URI Callback URL configured in MazeVault

Supported features:

  • Single Sign-On and Single Log-Out
  • Automatic user provisioning on first login
  • Group-to-role mapping
  • Conditional access policy compatibility

LDAP / Active Directory

Parameter Description
Server URL LDAP server address (ldaps:// recommended)
Bind DN Service account distinguished name
Search Base User search base DN
User Filter LDAP filter for user lookup
Group Search Base Group search base DN (optional)
TLS Required for production (LDAPS or StartTLS)

4. Multi-Factor Authentication (MFA)

MazeVault supports TOTP-based multi-factor authentication:

  • Compatible with Google Authenticator, Microsoft Authenticator, Authy, and other TOTP applications
  • QR code-based enrollment
  • Recovery codes for backup access
  • MFA can be enforced at the organization level (all users) or per-role

MFA Enforcement Matrix

Configuration Description
Disabled MFA optional for all users
Optional Users can self-enable MFA
Required for Admins Mandatory for administrator roles
Required for All Mandatory for all users

5. Session Management

Parameter Default Configurable
Web session, idle timeout 30 minutes (UI_SESSION_IDLE_TIMEOUT) ✅
Web session, absolute lifetime 12 hours (UI_SESSION_ABSOLUTE_TIMEOUT) ✅
Pending MFA step 5 minutes (UI_SESSION_MFA_TIMEOUT) ✅
Session storage (web interface) Server-side, in the database —
Cookie __Host-session: Secure; HttpOnly; SameSite=Strict; Path=/ —

Browser Sessions (BFF)

The web interface keeps sessions on the server. The browser holds only the cookie __Host-session, whose expiry equals the session's end; no token is ever returned to the browser. The web interface server (BFF) exposes POST /bff/auth/login, ldap-login, sso-exchange, mfa-verify, logout and GET /bff/auth/spnego-login; all other calls go through /bff/api/v1/... and /bff/api/v2/... only. The BFF checks the origin of every state-changing request (the Origin header must equal NUXT_PUBLIC_ORIGIN, otherwise 403) and presents the session to the backend as Authorization: Session together with the X-MazeVault-BFF secret (BFF_SHARED_SECRET); without the secret the scheme is disabled. Only a hash of the token is stored. Sign-in endpoints are rate limited.

  • Timeouts: a session ends after 30 minutes idle (UI_SESSION_IDLE_TIMEOUT) or 12 hours in total (UI_SESSION_ABSOLUTE_TIMEOUT); a pending MFA step expires after 5 minutes (UI_SESSION_MFA_TIMEOUT) and allows at most 5 code attempts, the last failure ends the pending sign-in.
  • Expiry: an expired session sends the user to /login?redirect=<page> and back to that page after the next sign-in. If the backend is temporarily unreachable (5xx or network error) the session is kept.
  • Revocation: sign-out, and automatically on password change (all sessions except the calling one), user deletion, role assignment, change or removal, MFA disable, and SSO/LDAP role changes. Administrators can list and revoke a user's sessions with GET/DELETE /api/v1/rbac/users/{id}/sessions.

The CLI, the Terraform provider and other API clients keep using Bearer tokens and API tokens (see below); browser sessions are not an authentication method for integrations.

Token Structure (API Clients and CLI)

API clients and the CLI use JWT (JSON Web Tokens):

  • Algorithm: RS256 (RSA with SHA-256)
  • Token Lifetime: Configurable (default 24 hours)
  • Refresh: Automatic token refresh before expiration
  • Revocation: Immediate revocation via Redis-backed blocklist
  • Claims: User ID, organization, roles, permissions, project access

6. API Authentication

OAuth 2.0 Client Credentials

For service-to-service integrations:

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)

For CLI tools and automation:

POST /api/v1/auth/universal
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>"
}

Bearer Token Usage

All authenticated API requests use the obtained token:

GET /api/v1/secrets
Authorization: Bearer <access-token>

7. Agent Authentication

MazeVault Agents use a bootstrap-then-certificate authentication flow:

sequenceDiagram
    participant A as 🤖 Agent
    participant S as 🖥️ MazeVault API

    rect rgb(235, 245, 251)
    Note over A,S: 🔑 Initial Registration
    A->>S: POST /agents/register (bootstrap_token)
    S-->>A: Agent ID + Client Certificate
    end

    rect rgb(232, 245, 233)
    Note over A,S: 🔒 Ongoing Communication (mTLS)
    A->>S: mTLS connection (client cert)
    S->>S: Validate cert + extract agent ID
    S-->>A: Authorized response
    end