Zitadel

1. Create an application in Zitadel

1. Log in to your Zitadel instance and open your Project.
2. Go to Applications → New Application.
3. Give it a name (e.g. dokploy) and click Next.
4. Select Web as the application type and click Next.
5. Choose CODE as the authentication method (Authorization Code with client_secret_basic).
6. Add the following Redirect URI:
   • https://your-dokploy-domain.com/api/auth/sso/callback/{providerId} Replace {providerId} with the unique identifier you will use in Dokploy (e.g. zitadel).
7. Add the Post Logout URI:
   • https://your-dokploy-domain.com
8. Click Create.
9. Copy the Client ID and generate + copy the Client Secret before closing the dialog.

2. Get your Issuer URL

Your Zitadel issuer URL is the base domain of your instance, for example:

• Cloud: https://your-instance.zitadel.cloud
• Self-hosted: https://zitadel.yourdomain.com

Dokploy will automatically fetch the OpenID Connect discovery document from {issuer}/.well-known/openid-configuration.

3. Configure Dokploy

1. In Dokploy, go to Settings → SSO → Register OIDC Provider.
2. Enter:
   • Provider ID: zitadel (must match the {providerId} used in the Redirect URI above)
   • Issuer URL: your Zitadel base URL (e.g. https://your-instance.zitadel.cloud)
   • Domains: email domain(s) of your users (e.g. acme.com)
   • Client ID: the Client ID from Zitadel
   • Client Secret: the Client Secret from Zitadel
   • Scopes: leave empty (defaults to openid email profile)
3. Note the Callback URL shown by Dokploy (e.g. https://your-dokploy-domain.com/api/auth/sso/callback/zitadel).
4. Save.

4. Verify the Redirect URI in Zitadel

Make sure the Redirect URI configured in your Zitadel application matches exactly the Callback URL shown in Dokploy:

https://your-dokploy-domain.com/api/auth/sso/callback/zitadel

If they differ, update the Redirect URI in the Zitadel application settings.

Troubleshooting

• Redirect URI mismatch — The Redirect URI in Zitadel must match the Callback URL in Dokploy exactly, including the {providerId} path segment.
• Invalid client — Verify the Client ID and Client Secret are correct and that the application is active in Zitadel.
• Authentication method — Zitadel must be set to CODE (Authentication Method: Basic). PKCE is not supported for server-side applications.
• HTTPS required — Zitadel requires HTTPS for Redirect URIs in production. Enable Development Mode in your Zitadel instance only if testing with HTTP.
• User not found — Ensure the user exists in the Zitadel project and that the email scope is included.

For help with your setup, contact us.