Skip to main content
Integrate Zitadel as your Single Sign-On (SSO) provider for kombify Cloud and Stack.

​
Overview

Zitadel is an open-source identity and access management platform that provides:
  • OAuth 2.0 and OpenID Connect (OIDC)
  • Multi-factor authentication (MFA)
  • User management
  • Role-based access control (RBAC)
kombify Cloud uses Zitadel by default for enterprise SSO.

​
Prerequisites

Zitadel instance

Self-hosted or cloud instance

Admin access

Access to Zitadel admin console

​
Setup for kombify Cloud

​
Step 1: Create OIDC application

1

Access Zitadel console

Log in to your Zitadel instance at https://your-zitadel.com
2

Create new project

Navigate to Projects → Create New Project
  • Name: kombify Cloud
  • Description: SSO for kombify platform
3

Add application

In your project, click New Application:
  • Name: kombify-Cloud
  • Type: Web
  • Authentication method: PKCE
4

Configure redirect URIs

Add these redirect URIs:
https://app.kombify.io/auth/callback
https://app.kombify.io/auth/refresh
For self-hosted:
https://your-Cloud-domain.com/auth/callback
https://your-Cloud-domain.com/auth/refresh
5

Save credentials

Copy these values:
  • Client ID
  • Client Secret (if not using PKCE)
  • Issuer URL

​
Step 2: Configure kombify Cloud

Contact support to configure your Zitadel instance:
support@kombify.dev
Provide:
  • Zitadel issuer URL
  • Client ID
  • Client secret (encrypted)

​
Setup for kombify TechStack (self-hosted)

​
Step 1: Create separate OIDC application

Follow the same process as above, but use:
  • Name: kombify-stack
  • Redirect URIs: 
    http://localhost:5261/auth/callback
https://your-stack-domain.com/auth/callback

​
Step 2: Configure Stack

Update Stack’s .env:
.env
# Enable OIDC
KOMBISTACK_AUTH_PROVIDER=zitadel

# Zitadel configuration
ZITADEL_ISSUER=https://your-zitadel.com
ZITADEL_CLIENT_ID=your-stack-client-id
ZITADEL_CLIENT_SECRET=your-stack-client-secret
ZITADEL_REDIRECT_URI=http://localhost:5261/auth/callback
Restart Stack: 
docker compose restart kombistack

​
User management

​
Create users in Zitadel

1

Add user

In Zitadel console: Users → Create New User
2

Assign to project

Navigate to your kombify project → Authorizations → Add User
3

Assign roles

Available roles:
  • kombify.admin — Full access
  • kombify.manager — Team management
  • kombify.user — Basic access

​
Map roles to kombify

In your kombify configuration: 
auth:
  provider: zitadel
  role_mapping:
    kombify.admin: admin
    kombify.manager: manager
    kombify.user: user

​
Advanced configuration

​
Custom claims

Add custom claims in Zitadel: 
{
  "kombify_team": "engineering",
  "kombify_tier": "enterprise"
}
Access in kombify: 
auth:
  custom_claims:
    - kombify_team
    - kombify_tier

​
Multi-factor authentication

Enable MFA in Zitadel:
  1. Organization Settings → Login Policy
  2. Enable Multi-Factor Authentication
  3. Choose methods: TOTP, WebAuthn, SMS
Users will be prompted for MFA on first login.

​
Troubleshooting

Ensure the redirect URI in Zitadel exactly matches your configuration:
# Check current configuration
echo $ZITADEL_REDIRECT_URI

# Must match Zitadel console
Verify issuer URL is correct:
curl https://your-zitadel.com/.well-known/openid-configuration
Check that issuer field matches your ZITADEL_ISSUER.
Ensure user is:
  1. Added to the kombify project in Zitadel
  2. Assigned appropriate roles
  3. Account is active (not locked)

​
Next steps

Coolify integration

Deploy kombify with Coolify

Proxmox integration

Manage Proxmox VMs

Security concepts

Learn about kombify security

Quick start

Get started with kombify