Single Sign-On (SSO)

Dokploy Enterprise supports Single Sign-On (SSO) integration with industry-standard protocols including OpenID Connect (OIDC) and SAML 2.0. Enable your team to authenticate using your organization’s identity provider.

SSO functionality is available with Dokploy Enterprise licenses. Self-hosted instances require a valid enterprise license to enable SSO features.

Supported Protocols

Dokploy supports two SSO protocols:

OIDC (OpenID Connect)

Modern authentication protocol built on OAuth 2.0, ideal for web and mobile apps

SAML 2.0

Enterprise-standard protocol widely used in corporate environments

Supported Identity Providers

Dokploy has been tested with the following identity providers:

Okta (OIDC and SAML)
Auth0 (OIDC)
Azure AD / Microsoft Entra ID (OIDC and SAML)
Google Workspace (OIDC)
Keycloak (OIDC and SAML)
OneLogin (OIDC and SAML)
PingIdentity (SAML)
JumpCloud (SAML)
Any OIDC or SAML 2.0 compliant provider

Prerequisites

Dokploy Enterprise license (self-hosted) or Dokploy Cloud account
Owner role in your Dokploy organization
Access to configure applications in your identity provider
A verified domain for email-based user matching

Configuration Workflow

Step 1: Prepare Trusted Origins

Before configuring SSO, you must add your identity provider’s domain to the trusted origins list:

Navigate to SSO Settings

In Dokploy, go to Settings > Authentication > Single Sign-On

Manage Trusted Origins

Click Manage Origins to view and modify trusted origins

Add Identity Provider Origin

Add your identity provider’s issuer URL:

Okta: https://your-domain.okta.com
Auth0: https://your-domain.auth0.com
Azure AD: https://login.microsoftonline.com

Click Add Origin to save

The issuer URL must exactly match the URL your identity provider uses. Mismatches will cause authentication failures.

Step 2: Configure Your Identity Provider

Create an application in your identity provider with these settings:

OIDC Configuration

Redirect URI / Callback URL:

https://your-dokploy-domain.com/api/auth/callback/oidc/{providerId}

Required Scopes:

openid
email
profile

User Attributes to Map:

id or sub - User unique identifier
email - User email address
email_verified - Email verification status
name or given_name - User display name
picture - Profile image URL (optional)

SAML Configuration

Assertion Consumer Service (ACS) URL:

https://your-dokploy-domain.com/api/auth/callback/saml/{providerId}

Entity ID / Audience:

https://your-dokploy-domain.com

Name ID Format:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Required Attributes:

id or NameID - User unique identifier
email - User email address
name or firstName - User display name

Step 3: Register SSO Provider in Dokploy

OIDC Provider
SAML Provider

Create New SSO Provider

In Dokploy SSO settings, click Add SSO Provider and select OIDC

Basic Configuration

Provider ID: Unique identifier (e.g., okta-production)
Issuer URL: Your identity provider’s issuer URL
Email Domains: Comma-separated domains (e.g., company.com,company.io)

OIDC Configuration

Enter these details from your identity provider:

Client ID: your-client-id
Client Secret: your-client-secret
Authorization Endpoint: https://idp.com/oauth2/authorize
Token Endpoint: https://idp.com/oauth2/token
User Info Endpoint: https://idp.com/oauth2/userinfo
JWKS Endpoint: https://idp.com/oauth2/jwks

If your provider supports OpenID Discovery, you can provide just the Discovery Endpoint and Dokploy will auto-configure the other endpoints.

Authentication Method

Choose the token endpoint authentication method:

client_secret_post (most common)
client_secret_basic

PKCE (Optional)

Enable PKCE (Proof Key for Code Exchange) for enhanced security. Enabled by default.

Attribute Mapping

Map identity provider attributes to Dokploy user fields:

id: sub
email: email
emailVerified: email_verified
name: name
image: picture

Save Configuration

Click Save to register the SSO provider

Create New SSO Provider

In Dokploy SSO settings, click Add SSO Provider and select SAML

Basic Configuration

Provider ID: Unique identifier (e.g., okta-saml)
Issuer URL: Your identity provider’s entity ID
Email Domains: Comma-separated domains (e.g., company.com)

Identity Provider Metadata

Provide your IdP’s metadata using one of these methods:Option 1: Metadata XML

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"...>
  <!-- Full IdP metadata XML -->
</EntityDescriptor>

Option 2: Manual Configuration

Entry Point: https://idp.com/sso/saml
Certificate: -----BEGIN CERTIFICATE-----...
Entity ID: https://idp.com

Service Provider Configuration

Configure Dokploy’s SP settings:

Callback URL: https://your-dokploy.com/api/auth/callback/saml/{providerId}
Entity ID: https://your-dokploy.com

Security Settings

Configure signature and encryption settings:

Want Assertions Signed: Require signed SAML assertions
Sign Authn Requests: Sign authentication requests from Dokploy
Signature Algorithm: sha256 (recommended)
Digest Algorithm: sha256 (recommended)

Attribute Mapping

Map SAML attributes to Dokploy user fields:

id: NameID
email: email
emailVerified: email_verified
name: firstName
firstName: firstName
lastName: lastName

Save Configuration

Click Save to register the SSO provider

Domain-Based Routing

Dokploy automatically routes users to the appropriate SSO provider based on their email domain:

User enters: john@company.com
↓
Dokploy checks domain: company.com
↓
Finds SSO provider configured for company.com
↓
Redirects to that provider's login page

Each domain can only be associated with one SSO provider. If you try to configure multiple providers for the same domain, Dokploy will reject the configuration.

User Provisioning

When a user signs in via SSO for the first time:

User Creation: Dokploy creates a new user account automatically
Organization Membership: The user is added to the organization that owns the SSO provider
Role Assignment: New SSO users are assigned the “member” role by default
Profile Sync: User profile data (name, email, avatar) is synced from the identity provider

Subsequent Logins

On subsequent logins:

User profile is updated with latest data from the identity provider
Organization membership is maintained
Role assignments are preserved (not overwritten by SSO)

SSO users cannot change their email address or password in Dokploy. These must be managed in your identity provider.

Testing SSO Configuration

After configuring SSO:

Open Dokploy Login Page

Navigate to your Dokploy instance login page

Click Sign in with SSO

Click the Sign in with SSO button

Enter Email

Enter an email address from a configured domain

Authenticate with IdP

You’ll be redirected to your identity provider’s login page

Complete Authentication

Enter your credentials and complete any multi-factor authentication

Redirect to Dokploy

After successful authentication, you’ll be redirected back to Dokploy and logged in

Managing SSO Providers

Updating Configuration

Navigate to SSO Settings

Go to Settings > Authentication > Single Sign-On

Select Provider

Click on the SSO provider you want to modify

Update Settings

Modify any configuration values (client secrets, certificates, endpoints, etc.)

Update Issuer (if needed)

If changing the issuer URL, ensure the new URL is in your trusted origins list first

Save Changes

Click Save to apply the changes

Changing the issuer URL requires that the new URL be added to trusted origins before saving. This prevents lockouts during provider migrations.

Removing SSO Provider

Navigate to SSO Settings

Go to Settings > Authentication > Single Sign-On

Select Provider

Click on the SSO provider you want to remove

Delete Provider

Click Delete Provider and confirm the action

Deleting an SSO provider does not delete user accounts. Users who authenticated via SSO will need to set up password-based authentication or use a different SSO provider.

Troubleshooting

Self-hosted without enterprise license

SSO requires a valid Dokploy Enterprise license
Purchase a license or request a trial at dokploy.com/enterprise

Enterprise license not activated

Verify your license is properly activated in Settings > License
Check that enableEnterpriseFeatures and isValidEnterpriseLicense are both true

Authentication Fails

Issuer mismatch

Verify the issuer URL in Dokploy exactly matches your IdP’s issuer
Check that the issuer is in your trusted origins list
Common issue: trailing slash differences (/ vs no /)

Redirect URI mismatch

Verify the callback URL in your IdP matches:
- OIDC: https://your-domain.com/api/auth/callback/oidc/{providerId}
- SAML: https://your-domain.com/api/auth/callback/saml/{providerId}
Provider ID must match exactly (case-sensitive)

Domain not configured

Verify the user’s email domain is listed in the SSO provider configuration
Check for typos in domain names
Ensure there are no extra spaces in the domain list

Certificate issues (SAML)

Verify the IdP certificate is in correct PEM format
Check certificate hasn’t expired
Ensure certificate matches the one in your IdP configuration

Invalid signature (SAML)

Verify signature algorithm matches in both IdP and Dokploy
Check that “Want Assertions Signed” setting matches IdP configuration
Ensure clock skew between servers is minimal (< 5 minutes)

User Profile Not Syncing

Attribute mapping incorrect

Verify attribute names match exactly what your IdP sends
Use your IdP’s test/preview feature to see actual attribute names
Common issue: sub vs user_id vs id for user identifier

Missing scopes (OIDC)

Ensure openid, email, and profile scopes are requested
Check that your IdP application grants these scopes

Missing attributes (SAML)

Verify required attributes are included in SAML assertion
Check attribute name mapping in your IdP

Security Best Practices

Certificate Management

Rotate regularly: Update SAML certificates before expiration
Use strong keys: Minimum 2048-bit RSA keys
Secure storage: Certificates and private keys are encrypted in Dokploy’s database

Client Secret Management

Never commit secrets: Keep client secrets out of version control
Rotate regularly: Update client secrets periodically
Limit permissions: Grant minimal required permissions in IdP

Domain Verification

Verify domain ownership: Only configure domains you control
Be specific: Use exact domains, not wildcards
Monitor configuration: Regularly audit SSO providers and domains

Access Control

Limit SSO admins: Only organization owners can configure SSO
Review user provisioning: Monitor new users created via SSO
Audit sign-ins: Enable logging in your identity provider

OIDC Configuration Schema

{
  providerId: string,              // Unique identifier
  issuer: string,                  // IdP issuer URL
  domains: string[],               // Email domains
  oidcConfig: {
    clientId: string,              // OAuth client ID
    clientSecret: string,          // OAuth client secret
    authorizationEndpoint?: string, // Authorization URL
    tokenEndpoint?: string,        // Token exchange URL
    userInfoEndpoint?: string,     // User info URL
    jwksEndpoint?: string,         // JWKS URL for token verification
    discoveryEndpoint?: string,    // OpenID Discovery URL
    skipDiscovery?: boolean,       // Skip auto-discovery
    tokenEndpointAuthentication?: 'client_secret_post' | 'client_secret_basic',
    scopes?: string[],             // OAuth scopes
    pkce?: boolean,                // Enable PKCE (default: true)
    mapping?: {                    // Attribute mapping
      id: string,
      email: string,
      emailVerified?: string,
      name: string,
      image?: string,
      extraFields?: Record<string, any>
    }
  }
}

SAML Configuration Schema

{
  providerId: string,              // Unique identifier
  issuer: string,                  // IdP entity ID
  domains: string[],               // Email domains
  samlConfig: {
    entryPoint: string,            // IdP SSO URL
    cert: string,                  // IdP certificate (PEM format)
    callbackUrl: string,           // SP ACS URL
    audience?: string,             // SP entity ID
    idpMetadata?: {                // IdP metadata (alternative to manual config)
      metadata?: string,           // Full metadata XML
      entityID?: string,
      cert?: string,
      singleSignOnService?: Array<{
        Binding: string,
        Location: string
      }>
    },
    spMetadata: {                  // Service Provider metadata
      entityID: string,
      binding?: string,
      privateKey?: string,         // SP signing key
      isAssertionEncrypted?: boolean
    },
    wantAssertionsSigned?: boolean,
    authnRequestsSigned?: boolean,
    signatureAlgorithm?: string,   // e.g., 'sha256'
    digestAlgorithm?: string,      // e.g., 'sha256'
    identifierFormat?: string,     // NameID format
    mapping?: {                    // Attribute mapping
      id: string,
      email: string,
      emailVerified?: string,
      name: string,
      firstName?: string,
      lastName?: string,
      extraFields?: Record<string, any>
    }
  }
}

API Integration

const providers = await api.sso.listProviders();

Next Steps

Two-Factor Authentication

Set up 2FA for enhanced security

Notifications

Set up security notifications

API Keys

Generate API keys for automation

Security Settings

Learn about security best practices

Git Providers

Notifications

Authentication

Single Sign-On (SSO)

Supported Protocols

OIDC (OpenID Connect)

SAML 2.0

Supported Identity Providers

Prerequisites

Configuration Workflow

Step 1: Prepare Trusted Origins

Step 2: Configure Your Identity Provider

OIDC Configuration

SAML Configuration

Step 3: Register SSO Provider in Dokploy

Domain-Based Routing

User Provisioning

Subsequent Logins

Testing SSO Configuration

Managing SSO Providers

Updating Configuration

Removing SSO Provider

Troubleshooting

Authentication Fails

User Profile Not Syncing

Security Best Practices

Certificate Management

Client Secret Management

Domain Verification

Access Control

OIDC Configuration Schema

SAML Configuration Schema

API Integration

Next Steps

Two-Factor Authentication

Notifications

API Keys

Security Settings

Build docs developers (and LLMs) love

Git Providers

Notifications

Authentication

​Supported Protocols

OIDC (OpenID Connect)

SAML 2.0

​Supported Identity Providers

​Prerequisites

​Configuration Workflow

​Step 1: Prepare Trusted Origins

​Step 2: Configure Your Identity Provider

​OIDC Configuration

​SAML Configuration

​Step 3: Register SSO Provider in Dokploy

​Domain-Based Routing

​User Provisioning

​Subsequent Logins

​Testing SSO Configuration

​Managing SSO Providers

​Updating Configuration

​Removing SSO Provider

​Troubleshooting

​”Sign in with SSO” Button Not Visible

​Authentication Fails

​User Profile Not Syncing

​Security Best Practices

​Certificate Management

​Client Secret Management

​Domain Verification

​Access Control

​OIDC Configuration Schema

​SAML Configuration Schema

​API Integration

​Next Steps

Two-Factor Authentication

Notifications

API Keys

Security Settings

Build docs developers (and LLMs) love

Supported Protocols

Supported Identity Providers

Prerequisites

Configuration Workflow

Step 1: Prepare Trusted Origins

Step 2: Configure Your Identity Provider

OIDC Configuration

SAML Configuration

Step 3: Register SSO Provider in Dokploy

Domain-Based Routing

User Provisioning

Subsequent Logins

Testing SSO Configuration

Managing SSO Providers

Updating Configuration

Removing SSO Provider

Troubleshooting

”Sign in with SSO” Button Not Visible

Authentication Fails

User Profile Not Syncing

Security Best Practices

Certificate Management

Client Secret Management

Domain Verification

Access Control

OIDC Configuration Schema

SAML Configuration Schema

API Integration

Next Steps