Skip to content

Security

Authentication mechanisms, authorization model, encryption, audit capabilities, and threat considerations for Zitadel.

Authentication Mechanisms

Protocol Support Matrix

Protocol Type Status Use Case
OpenID Connect Standard Certified Web and mobile SSO, API authentication
OAuth 2.0 Standard Full API authorization, machine-to-machine
SAML 2.0 Standard Full Enterprise SSO, legacy application integration
WebAuthn / FIDO2 Standard First-class Passwordless authentication, passkeys
LDAP Standard Supported Active Directory / LDAP integration

OIDC Configuration

Zitadel implements a full OpenID Provider with these endpoints:

Endpoint Path
Discovery /.well-known/openid-configuration
Authorization /oauth/v2/authorize
Token /oauth/v2/token
Userinfo /oauth/v2/userinfo
Keys (JWKS) /oauth/v2/keys
Revocation /oauth/v2/revoke
Device Authorization /oauth/v2/device
End Session /oidc/v1/end_session

Supported grant types: Authorization Code (with PKCE), Implicit, Client Credentials, Device Code, Resource Owner Password, Token Exchange.

Multi-Factor Authentication

Method Type Implementation
TOTP (OTP) Time-based Standard RFC 6238, compatible with Google Authenticator, Authy
WebAuthn (U2F) Hardware key FIDO U2F security keys (YubiKey, etc.)
Email OTP Out-of-band One-time code sent to registered email
SMS OTP Out-of-band One-time code sent via SMS

Passkeys / Passwordless

Zitadel treats FIDO2/WebAuthn as a primary authentication method:

  • Platform authenticators (Touch ID, Windows Hello, Android fingerprint)
  • Roaming authenticators (YubiKey, Titan Key)
  • Cloud-synced passkeys (iCloud Keychain, Google Password Manager)
  • User verification configurable: required, preferred, discouraged
  • Username + passkey login eliminates password entry entirely

External Identity Providers

Pre-built templates for federated authentication:

Category Providers
Social Google, GitHub, GitLab, Apple
Enterprise Azure AD, Generic OIDC, Generic SAML, LDAP
Custom Any OIDC or SAML 2.0 compliant IdP

Machine-to-Machine Authentication

Method Mechanism Use Case
JWT Profile Private key JWT (RSA/EC) Service accounts with signed JWTs
Personal Access Tokens Static Bearer token Developer API access, CI/CD pipelines
Client Credentials Client ID + secret Simple M2M (less secure than JWT Profile)

Authorization Model

Hierarchical RBAC

Zitadel implements multi-tenant RBAC across three levels:

Instance (IAM-level roles)
  └── Organization (org-level roles)
       └── Project (project-level roles)

Permission Resolution

Permissions follow a dual-mode pattern:

Mode Syntax Meaning
Context-scoped project.write:project-123 Permission applies to a specific resource
Global project.write Permission applies to all resources of that type

Resolution flow: 1. Extract user ID from Bearer token 2. Load user's memberships (org, project, IAM level) 3. Expand each membership's roles into permissions 4. Apply context filtering for resource-scoped permissions 5. Deny if no matching permission found

Project Grants (Cross-Org Authorization)

Project grants enable B2B multi-tenant scenarios:

  1. Project owner (Organization A) defines roles on a project
  2. Grant creation — owner selects a subset of roles and grants them to Organization B
  3. Self-management — Organization B's admins assign users to the granted roles
  4. Revocation — owner can revoke the grant at any time, immediately removing access

This is the core mechanism for SaaS providers offering customer-specific access control.

Membership Scopes

Member Type Scope Example
IAM Instance-wide IAM_OWNER, IAM_ORG_MANAGER
ORG Organization ORG_OWNER, ORG_USER_MANAGER
PROJECT Project PROJECT_OWNER, PROJECT_OWNER_VIEWER
PROJECT_GRANT Granted project Self-managed by grantee org

Encryption & Key Management

Data Encryption

Layer Mechanism
At rest PostgreSQL encryption (TDE or disk-level)
In transit TLS 1.2+ for all connections (API, database, LDAP)
Secrets AES-256 encryption for stored secrets using master key
Passwords bcrypt hashing with configurable cost
Master key 32-byte key passed via --masterkey flag or ZITADEL_MASTERKEY env var

JWT Signing Keys

  • RSA and EC key pairs generated automatically
  • Key rotation supported via the Web Key Service API (/v2/webkeys/)
  • JWKS endpoint publishes public keys at /oauth/v2/keys
  • Keys stored encrypted in the eventstore

Audit Trail

Because Zitadel uses event sourcing, every state mutation produces an immutable event:

Capability Detail
Complete audit log Every create, update, delete on any entity is an event
Temporal queries Reconstruct state at any point in time by replaying events
Export Events API for programmatic access; log store senders for SIEM
Non-repudiation Events cannot be modified after creation (append-only)
Actor tracking Each event records which user/service performed the action

SOC/SIEM Integration

Events can be forwarded to external security systems: - Log store senders — configure webhook targets for real-time event streaming - OpenTelemetry — traces and metrics for observability correlation - GCP Error Reporting — via zitadel/sloggcp package

Threat Model

Attack Vectors & Mitigations

Threat Mitigation
Credential theft Passkeys (phishing-resistant), MFA enforcement, token rotation
Token replay Short-lived access tokens, refresh token rotation, token binding
Privilege escalation Hierarchical RBAC, context-scoped permissions, membership auditing
Data exfiltration Encryption at rest, TLS in transit, instance isolation
SQL injection Parameterized queries via Go database/sql, proto-generated API
XSS Login UI is Next.js with CSP headers; admin console is Angular
CSRF OIDC state parameter, PKCE enforcement for public clients
Brute force Rate limiting, account lockout policies, password complexity rules
Phishing FIDO2/WebAuthn as primary auth (phishing-resistant by design)
Insider threat Immutable audit trail, separation of duties via role hierarchy

Security Policies

Administrators can enforce policies at the instance or organization level:

Policy Scope Controls
Login policy Instance / Org Allowed auth methods, MFA requirement, IdP allowlist
Password policy Instance / Org Min length, complexity, expiry, lockout
Privacy policy Instance / Org TOS URL, privacy policy URL, support email
Branding policy Org Logo, colors, font, theme for login UI
Domain policy Instance User login must match org domain, domain verification

SCIM 2.0 User Provisioning

Built-in SCIM 2.0 server for enterprise user lifecycle management:

Operation Method Endpoint
Create user POST /scim/v2/{orgID}/Users
Get user GET /scim/v2/{orgID}/Users/{id}
List users GET /scim/v2/{orgID}/Users
Replace user PUT /scim/v2/{orgID}/Users/{id}
Update user PATCH /scim/v2/{orgID}/Users/{id}
Delete user DELETE /scim/v2/{orgID}/Users/{id}

Permissions are mapped to Zitadel's internal RBAC: User Write, User Read, User Delete.

Sources