diff --git a/apps/docs/content/docs/core/enterprise/sso/index.mdx b/apps/docs/content/docs/core/enterprise/sso/index.mdx index 45a5221..4fa14f8 100644 --- a/apps/docs/content/docs/core/enterprise/sso/index.mdx +++ b/apps/docs/content/docs/core/enterprise/sso/index.mdx @@ -11,6 +11,7 @@ Choose a provider below for step-by-step configuration: - **[Azure AD (Microsoft Entra ID)](/docs/core/enterprise/sso/azure)** — Microsoft's cloud identity platform - **[Okta](/docs/core/enterprise/sso/okta)** — Cloud identity platform - **[Keycloak](/docs/core/enterprise/sso/keycloak)** — Open-source identity and access management +- **[Zitadel](/docs/core/enterprise/sso/zitadel)** — Open-source identity and access management You can also use any other OIDC/SAML provider by configuring the endpoints and flow manually. diff --git a/apps/docs/content/docs/core/enterprise/sso/zitadel.mdx b/apps/docs/content/docs/core/enterprise/sso/zitadel.mdx new file mode 100644 index 0000000..f11f5a1 --- /dev/null +++ b/apps/docs/content/docs/core/enterprise/sso/zitadel.mdx @@ -0,0 +1,61 @@ +--- +title: Zitadel +description: Configure SSO with 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](https://dokploy.com/contact).