Skip to main content

Zitadel Setup

This guide walks through setting up Zitadel as the identity provider for OIDC login and SCIM user provisioning in Open Saasframe.

Free tier

Zitadel Cloud offers a free tier with up to 25,000 monthly active users.

1. Create a Zitadel Instance​

  1. Go to https://zitadel.com and sign up for a free account
  2. Create a new instance (or use the default one)
  3. Note your instance domain: https://<instance>.zitadel.cloud

2. Create Test Users​

  1. In the Zitadel Console, go to Users -> + New
  2. Fill in:
    • Username: e.g., testuser@yourdomain.com
    • First name / Last name
    • Email: the user's email address
    • Password: set an initial password
  3. Click Create
  4. Repeat for 2-3 test users

3. Register the OIDC Application​

  1. In the Zitadel Console, go to Projects -> + New
  2. Name the project Open Saasframe and click Continue
  3. Click + New Application
  4. Configure:
FieldValue
NameOpen Saasframe
TypeWeb
Authentication MethodCode (PKCE)
Redirect URIshttp://localhost:3000/api/sso/callback/oidc
Post-Logout URIshttp://localhost:3000/login
  1. Click Create
  2. On the application overview, note:
    • Client ID
    • Client Secret (generate one if using Code flow)

OIDC Credentials Summary​

CredentialWhere to find itValue
Issuer URLInstance domainhttps://<instance>.zitadel.cloud
Client IDApplication -> GeneralCopy from console
Client SecretApplication -> General -> GenerateCopy immediately
Redirect URIYou configured thishttp://localhost:3000/api/sso/callback/oidc

Configure Token Claims​

Zitadel includes email, given_name, family_name, and email_verified in ID tokens by default when the openid, profile, and email scopes are requested. No additional configuration is needed.

Assign Users​

By default, all users in the organization can access the application. To restrict access:

  1. Go to your Project -> Authorizations -> + New
  2. Select specific users or grant roles
  3. Enable "Require authorization" on the project settings if you want to restrict access

4. Create the SSO Config in Open Saasframe​

  1. Log into Open Saasframe as admin
  2. Go to Settings -> Single Sign-On -> Create New
  3. Select OIDC as the protocol
  4. Enter:
    • Name: Zitadel
    • Issuer URL: https://<instance>.zitadel.cloud
    • Client ID: (paste from Zitadel)
    • Client Secret: (paste from Zitadel)
  5. Add allowed email domains (e.g., yourdomain.com)
  6. Test the connection (Verify Discovery)
  7. Activate the config

Verify OIDC Login​

  1. Open a private/incognito browser window
  2. Go to the Open Saasframe login page
  3. Enter an email address belonging to one of your test users
  4. The HRD check should detect SSO and redirect to Zitadel login
  5. Authenticate at Zitadel
  6. You should be redirected back to Open Saasframe and logged in

5. Configure SCIM Provisioning​

Prerequisite

Generate a SCIM bearer token from Open Saasframe via the admin UI (SSO config -> Provisioning tab -> Generate Token).

Zitadel SCIM Support​

Zitadel supports outbound SCIM provisioning through its Actions feature (custom workflows). Zitadel also offers a native SCIM provisioning option:

  1. Go to your Project -> Open Saasframe application
  2. Navigate to Provisioning or Actions
  3. Configure SCIM outbound provisioning:
FieldValue
SCIM Base URLhttp://localhost:3000/api/sso/scim/v2 (dev) or https://<your-domain>/api/sso/scim/v2 (prod)
Bearer TokenPaste the SCIM token from Open Saasframe
  1. Test the connection

Alternative: Manual/API-Based Provisioning​

If Zitadel's native SCIM outbound is not available in your version, use the Zitadel Management API to sync users:

  1. Create a Service User in Zitadel with Management API access
  2. Use the Zitadel Management API to list users
  3. Push user changes to Open Saasframe's SCIM endpoint

6. Test the Full Flow​

Test OIDC Login​

  1. Navigate to Open Saasframe login
  2. Enter a test user's email
  3. Expected: Redirect to Zitadel -> authenticate -> redirect back to Open Saasframe
  4. Verify the user appears in the Open Saasframe admin panel

Test JIT Provisioning​

If SCIM is not configured and JIT is enabled:

  1. Log in as a new user via OIDC
  2. Expected: User is automatically created in Open Saasframe with provisioningMethod: jit
  3. Verify user profile (name, email) matches Zitadel

Test SCIM Provisioning (if configured)​

  1. Create a new user in Zitadel
  2. Wait for provisioning cycle (or trigger manually)
  3. Expected: User appears in Open Saasframe with provisioningMethod: scim
  4. Update the user in Zitadel -> verify changes propagate
  5. Deactivate the user in Zitadel -> verify deactivation in Open Saasframe

Zitadel SCIM Quirks​

QuirkDescriptionHow to handle
Standard-compliantZitadel follows SCIM 2.0 spec closelyStandard parsing works
email_verified claimAlways included in ID tokensNo special handling needed
Group claimsAvailable via project rolesConfigure role mappings if needed
PKCE supportNatively supports S256 PKCEAutomatically used by Open Saasframe

Troubleshooting​

OIDC login redirects but fails​

  • Verify the Redirect URI matches exactly: http://localhost:3000/api/sso/callback/oidc
  • Check that the Issuer URL matches your instance: https://<instance>.zitadel.cloud
  • Verify Client ID and Client Secret
  • Check the Zitadel Console -> Events for error details

"redirect_uri_mismatch" error​

  • Ensure the redirect URI registered in Zitadel matches exactly (including protocol and port)
  • No trailing slash differences
  • For production, use HTTPS

Users can't log in​

  • Check that users exist in the same Zitadel organization
  • If "Require authorization" is enabled on the project, ensure users have project grants
  • Check that the email domain matches the allowed domains in Open Saasframe SSO config

SCIM connection fails​

  • For local dev, Zitadel needs to reach your server over the internet
  • Use ngrok: ngrok http 3000
  • Update the SCIM Base URL to the ngrok URL

Reference​