Zitadel SSO with QuFabric Self-Hosted (Advanced)

Zitadel is an open-source identity infrastructure platform designed for cloud-native environments. It provides multi-tenancy, customizable branding, passwordless authentication, and supports protocols like OpenID Connect, OAuth2, SAML2, and LDAP.

Standalone Setup (Advanced)

Use Zitadel as your primary identity provider instead of QuFabric's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Zitadel administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the embedded IdP is the simpler choice — it's built into QuFabric, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the Management Setup (Recommended) section above.

Prerequisites

• Zitadel instance (cloud or self-hosted) with SSL
• Docker and Docker Compose for QuFabric

Step 1: Create and Configure Zitadel Application

1. Navigate to Zitadel console
2. Click Projects at the top menu, then click Create New Project
3. Fill in:
   • Name: NETBIRD

4. Click Projects and select NETBIRD project
5. Click New in Applications section
6. Fill in:
   • Name: qufabric
   • Type of Application: User Agent

7. Click Continue and set:
   • Authentication Method: PKCE

8. Click Continue and configure:
   • Redirect URIs:
     • https://<domain>/auth
     • https://<domain>/silent-auth
     • http://localhost:53000
   • Post Logout URIs: https://<domain>/

9. Click Create and then Close
10. Under Grant Types, select Authorization Code, Device Code, and Refresh Token
11. Click Save

12. Copy Client ID for later use

Step 2: Configure Token Settings

1. Select the qufabric application
2. Click Token Settings in the left menu
3. Configure:
   • Auth Token Type: JWT
   • Check Add user roles to the access token
4. Click Save

Step 3: Configure Redirect Settings (Development Only)

1. Click Redirect Settings in the left menu
2. Toggle Development Mode
3. Click Save

Step 4: Create Service User

1. Click Users in the top menu
2. Select Service Users tab
3. Click New
4. Fill in:
   • User Name: qufabric
   • Name: qufabric
   • Description: QuFabric Service User
   • Access Token Type: JWT
5. Click Create

6. Click Actions in the top right corner
7. Click Generate Client Secret
8. Copy ClientSecret for later use

Step 5: Grant User Manager Role

1. Click Organization in the top menu
2. Click + in the top right corner
3. Search for qufabric service user
4. Check Org User Manager checkbox
5. Click Add

Step 6: Configure QuFabric

Your authority OIDC configuration will be available at:

https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration

Set properties in the setup.env file:

QUFABRIC_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/.well-known/openid-configuration"
QUFABRIC_USE_AUTH0=false
QUFABRIC_AUTH_CLIENT_ID="<CLIENT_ID>"
QUFABRIC_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
QUFABRIC_AUTH_AUDIENCE="<CLIENT_ID>"
QUFABRIC_AUTH_REDIRECT_URI="/auth"
QUFABRIC_AUTH_SILENT_REDIRECT_URI="/silent-auth"

QUFABRIC_AUTH_DEVICE_AUTH_PROVIDER="hosted"
QUFABRIC_AUTH_DEVICE_AUTH_CLIENT_ID="<CLIENT_ID>"
QUFABRIC_AUTH_DEVICE_AUTH_AUDIENCE="<CLIENT_ID>"

QUFABRIC_MGMT_IDP="zitadel"
QUFABRIC_IDP_MGMT_CLIENT_ID="qufabric"
QUFABRIC_IDP_MGMT_CLIENT_SECRET="<CLIENT_SECRET>"
QUFABRIC_IDP_MGMT_EXTRA_MANAGEMENT_ENDPOINT="https://<YOUR_ZITADEL_HOST_AND_PORT>/management/v1"
QUFABRIC_MGMT_IDP_SIGNKEY_REFRESH=true

Step 7: Continue with QuFabric Setup

You've configured all required resources in Zitadel. Continue with the QuFabric Self-hosting Guide.

Migrating from Zitadel Quickstart

If you deployed QuFabric using the previous quickstart script with Zitadel:

Option A - Keep using Zitadel standalone: Continue with your existing setup. No changes needed.

Option B - Add Zitadel as external IdP directly in QuFabric Management Dashboard:

1. Deploy new QuFabric version with embedded IdP
2. Add your existing Zitadel as an external IdP directly in the QuFabric Management Dashboard (follow Management Setup above)
3. Users can continue logging in with Zitadel
4. Optionally create local user accounts as fallback

Option C - Migrate fully to embedded IdP:

1. Export user list from Zitadel
2. Deploy new QuFabric version with embedded IdP
3. Recreate users in QuFabric Dashboard
4. Decommission Zitadel when ready

Troubleshooting

"Token validation failed" error

• Verify the issuer URL is correct
• Ensure User Info inside ID Token is enabled
• Check that the audience matches your client ID

Service user authentication fails

• Verify the client secret was copied correctly
• Ensure the service user has Org User Manager role

Device auth not working

• Ensure Device Code grant type is enabled
• Verify PKCE is configured for the application

Related Resources

• Zitadel Documentation
• Zitadel GitHub
• Embedded IdP Overview
• Migration Guide