Update SSO documentation for Auth0, Azure AD, Keycloak, and Okta to clarify domain usage and enhance troubleshooting sections for OIDC and SAML configurations.

2026-06-15 20:25:25 +02:00 · 2026-02-01 19:07:16 -06:00
parent 5a7a9d1564
commit ab1c76987d
4 changed files with 86 additions and 9 deletions
--- a/apps/docs/content/docs/core/enterprise/sso/auth0.mdx
+++ b/apps/docs/content/docs/core/enterprise/sso/auth0.mdx
@@ -18,7 +18,7 @@ description: Configure SSO with Auth0
 3. Enter:
   - **Provider**: myorg-name-auth0 (Unique)
   - **Issuer URL**: `https://YOUR_AUTH0_DOMAIN/` (Make sure add the trailing slash)
-   - **Domain**: `your-domain.com` (Your domain)
+   - **Domain**: the domain users use to authenticate via Auth0 (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
   - **Client ID**: from Auth0 application
   - **Client Secret**: from Auth0 application
   - **Scopes**: openid email profile
--- a/apps/docs/content/docs/core/enterprise/sso/azure.mdx
+++ b/apps/docs/content/docs/core/enterprise/sso/azure.mdx
@@ -1,8 +1,10 @@
 ---
 title: Azure AD (Microsoft Entra ID)
-description: Configure SSO with Azure AD / Microsoft Entra ID
+description: Configure SSO with Azure AD / Microsoft Entra ID (OIDC or SAML)
 ---

+<Tabs items={['SSO (OIDC)', 'SAML']}>
+<Tab value="SSO (OIDC)">

 ## 1. Register an application in Azure

@@ -20,7 +22,7 @@ description: Configure SSO with Azure AD / Microsoft Entra ID
 3. Enter:
   - **Provider**: myorg-name-azure (unique name for this provider)
   - **Issuer URL**: `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` (use your Directory (tenant) ID; add a trailing slash if required for discovery)
-   - **Domain**: `your-domain.com`
+   - **Domain**: the domain users use to authenticate via Azure AD (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
   - **Client ID**: the Application (client) ID from Azure
   - **Client Secret**: the client secret value from Certificates & secrets
   - **Scopes**: openid email profile
@@ -36,11 +38,51 @@ description: Configure SSO with Azure AD / Microsoft Entra ID
 4. Go to **Token Configuration** and add optional claim, select **email**, **preferred_username** and **upn** from the list of claims.
 5. Save.

-## Troubleshooting
+## Troubleshooting (OIDC)

 - **Redirect URI mismatch** — Ensure the callback URL in Dokploy matches exactly what is configured in Azure (including protocol and path). Use the same **Provider** value in the path (e.g. `.../api/auth/callback/myorg-name-azure`).
 - **Invalid client** — Double-check Application (client) ID and client secret. Confirm the secret has not expired under **Certificates & secrets**.
 - **Tenant** — Use the correct Directory (tenant) ID in the Issuer URL. For multi-tenant apps, you may use `common` instead of the tenant ID (e.g. `https://login.microsoftonline.com/common/v2.0`).
 - **Scopes** — Ensure the app registration has the right API permissions (e.g. **OpenID permissions**, **User.Read**) if required for `openid`, `email`, and `profile`.

+</Tab>
+<Tab value="SAML">
+
+## 1. Create an Enterprise Application (SAML) in Azure
+
+1. Log in to the [Azure Portal](https://portal.azure.com/).
+2. Go to **Microsoft Entra ID** → **Enterprise applications** → **New application** → **Create your own application** (or **Non-gallery application**).
+3. Enter a **Name** (e.g. Dokploy) and create.
+4. Go to **Single sign-on** → **SAML**.
+5. Note the **Identifier (Entity ID)** and **Login URL** (SSO URL). Under **SAML Certificates**, download or copy the **Certificate (Base64)** (x509) and download the **Federation Metadata XML** file.
+
+## 2. Configure Dokploy
+
+1. In Dokploy, go to **Settings** (or **Organization** / **Security** in Enterprise).
+2. Enable **SSO** and choose **SAML**.
+3. Enter:
+   - **Provider**: myorg-name-azure-saml (unique name for this provider)
+   - **Entity ID**: the Azure SAML Entity ID (Identifier) from the Enterprise application (eg. `https://sts.windows.net/YOUR_TENANT_ID/`).
+   - **SSO URL**: the Azure Login URL (Single Sign-On URL) (eg. `https://login.microsoftonline.com/YOUR_TENANT_ID/saml2`)
+   - **Certificate**: the IdP signing certificate (x509 Base64) from Azure
+   - **Federation Metadata XML**: the Federation Metadata XML file from Azure
+   - **Domain**: the domain users use to authenticate via Azure AD (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
+4. Save.
+
+## 3. Configure Azure (SAML)
+
+1. In your Enterprise application, go to **Single sign-on** → **SAML**.
+2. Under **Basic SAML Configuration**, set **Identifier (Entity ID)** if required (SP Entity ID from Dokploy) (eg. `https://your-dokploy-instance.com`).
+3. Set **Reply URL (Assertion Consumer Service URL)** to your Dokploy SAML ACS URL (eg. `https://your-dokploy-instance.com/api/auth/sso/saml2/callback/myorg-name-azure-saml`).
+3. Save.
+
+## Troubleshooting (SAML)
+
+- **ACS URL mismatch** — Ensure the Reply URL (ACS) in Azure matches exactly what Dokploy provides (including protocol and path).
+- **Certificate** — Use the Certificate (Base64) from Azure; paste as-is or convert to PEM if Dokploy expects PEM.
+- **Entity ID** — The Entity ID in Dokploy must match the Identifier (Entity ID) of the Azure Enterprise application.
+
+</Tab>
+</Tabs>
+
 For help with your setup, [contact us](https://dokploy.com/contact).
--- a/apps/docs/content/docs/core/enterprise/sso/keycloak.mdx
+++ b/apps/docs/content/docs/core/enterprise/sso/keycloak.mdx
@@ -21,7 +21,7 @@ description: Configure SSO with Keycloak
 3. Enter:
   - **Provider**: my-client-id (Unique)
   - **Issuer URL**: your Keycloak realm URL (e.g. `https://keycloak.example.com/realms/your-realm`)
-   - **Domain**: `your-domain.com`
+   - **Domain**: the domain users use to authenticate via Keycloak (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
   - **Client ID**: my-client-id
   - **Client Secret**: the secret from the Keycloak client Credentials tab
   - **Scopes**: openid email profile
--- a/apps/docs/content/docs/core/enterprise/sso/okta.mdx
+++ b/apps/docs/content/docs/core/enterprise/sso/okta.mdx
@@ -1,8 +1,10 @@
 ---
 title: Okta
-description: Configure SSO with Okta
+description: Configure SSO with Okta (OIDC or SAML)
 ---

+<Tabs items={['SSO (OIDC)', 'SAML']}>
+<Tab value="SSO (OIDC)">

 ## 1. Create an application in Okta

@@ -18,8 +20,8 @@ description: Configure SSO with Okta
 2. Enable **SSO** and choose **OpenID Connect**.
 3. Enter:
   - **Provider**: myorg-name-okta (unique name for this provider)
-   - **Issuer URL**: your Okta issuer URL (e.g. `https://your-domain.okta.com` )
-   - **Domain**: `your-domain.com` (your Dokploy domain)
+   - **Issuer URL**: your Okta issuer URL (e.g. `https://your-domain.okta.com`)
+   - **Domain**: the domain users use to authenticate via Okta (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
   - **Client ID**: from the Okta application
   - **Client Secret**: from the Okta application
   - **Scopes**: openid email profile
@@ -35,11 +37,44 @@ description: Configure SSO with Okta
 4. Under **Trusted Origins**, add your Dokploy URL as an origin (e.g. `https://your-dokploy-domain.com`) if required for CORS.
 5. Save.

-## Troubleshooting
+## Troubleshooting (OIDC)

 - **Redirect URI mismatch** — Ensure the callback URL in Dokploy matches exactly what is configured in Okta (including protocol and path). Use the same **Provider** value in the path (e.g. `.../api/auth/callback/myorg-name-okta`).
 - **Invalid client** — Double-check Client ID and Client Secret, and that the application is a Web Application with the correct grant types (e.g. Authorization Code).
 - **Issuer URL** — Use the full issuer URL for your authorization server (e.g. `https://your-domain.okta.com`).
 - **Scopes** — Ensure the Okta authorization server is configured to allow `openid`, and if needed `email` and `profile`.

+</Tab>
+<Tab value="SAML">
+
+## 1. Create a SAML application in Okta
+
+1. Log in to the [Okta Admin Console](https://login.okta.com/) (or your Okta domain).
+2. Go to **Applications** → **Applications** → **Create App Integration**.
+3. Choose **SAML 2.0** and create it.
+4. Enter an **App name** (e.g. Dokploy). Under **Configure SAML**,  in the Single sign-on URL field, set the SAML ACS URL (eg. `https://your-dokploy-instance.com/api/auth/sso/saml2/callback/myorg-name-okta-saml`) and in the Audience URI (SP Entity ID) field, set the SP Entity ID (eg. `https://your-dokploy-instance.com`).
+5. Next & Save.
+
+## 2. Configure Dokploy
+
+1. In Dokploy, go to **Settings** (or **Organization** / **Security** in Enterprise).
+2. Enable **SSO** and choose **SAML**.
+3. Enter:
+   - **Provider**: myorg-name-okta-saml (unique name for this provider)
+   - **Entity ID**: the Okta Identity Provider issuer (Entity ID) located in `Sign On` tab called `Issuer` (eg. `http://www.okta.com/exkzq3acyuEtIuNrW697`)
+   - **SSO URL**: the Okta Identity Provider single sign-on URL located in `Sign On` tab called `Single sign-on URL` (eg. `https://trial-2804699.okta.com/app/trial-2802699_something/exkzqi3cyuEtIuNrW697/sso/saml`)
+   - **Certificate**: go to `Signing Certificate` tab and download the certificate active (x509) and paste it in the `Certificate` field.
+   - **Federation Metadata XML**: copy the idp metadata XML from the certificate active and paste it in the `Metadata XML` field.
+   - **Domain**: the domain users use to authenticate via Okta (e.g. your organization domain like `acme.com`), not the Dokploy instance URL
+4. Save.
+
+## Troubleshooting (SAML)
+
+- **ACS URL mismatch** — Ensure the Single sign-on URL (ACS) in Okta matches exactly what Dokploy provides (including protocol and path).
+- **Certificate** — Use the x509 certificate from Okta’s IdP metadata (PEM or Base64); ensure it is the one used to sign assertions.
+- **Entity ID** — The Entity ID in Dokploy must match the Identity Provider issuer in Okta.
+
+</Tab>
+</Tabs>
+
 For help with your setup, [contact us](https://dokploy.com/contact).