Single Sign-On (SSO) with SAML and OIDC

Single Sign-On lets your entire team authenticate with the identity provider your organization already uses — Okta, Azure AD, Google Workspace, Keycloak, Auth0, and any other SAML 2.0 or OIDC-compliant provider. Once SSO is configured, members can click Sign in with SSO on the Dokploy login page and be redirected to your IdP, eliminating the need to manage separate Dokploy passwords.

Requirements

A valid Dokploy Enterprise license activated on the owner account (see Enterprise Overview).
Dokploy must be reachable at a publicly accessible domain so your identity provider can redirect back after authentication.
The SSO issuer URL must be added to the organization’s trusted origins before a provider can be created or updated.

Supported Protocols

Dokploy supports two SSO protocols via the better-auth SSO integration:

SAML 2.0

Industry-standard XML-based federation. Requires an entry point URL, an X.509 certificate from your IdP, and an SP callback URL.

OpenID Connect (OIDC)

OAuth 2.0-based protocol. Requires a client ID, client secret, and your IdP’s discovery endpoint (well-known URL). PKCE is enabled by default.

Enabling SSO

Activate your Enterprise license

SSO endpoints use enterpriseProcedure, which verifies that the organization’s owner has a valid license. Ensure licenseKey.haveValidLicenseKey returns true before proceeding.

Add a trusted origin

Before registering any provider, add your IdP’s issuer URL as a trusted origin. This prevents unauthorized IdPs from being used to initiate authentication flows.

await trpc.sso.addTrustedOrigin.mutate({
  origin: "https://login.microsoftonline.com/your-tenant-id",
});

Origins are normalized (scheme + host) before storage so https://example.com/path and https://example.com resolve to the same entry.

Call sso.register with your protocol-specific configuration. Each provider requires a unique providerId, the IdP issuer URL, and one or more email domains that will use this provider.

OIDC
SAML

await trpc.sso.register.mutate({
  providerId: "google-workspace",
  issuer: "https://accounts.google.com",
  domains: ["yourcompany.com"],
  oidcConfig: {
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    discoveryEndpoint:
      "https://accounts.google.com/.well-known/openid-configuration",
    pkce: true,
  },
});

await trpc.sso.register.mutate({
  providerId: "okta-saml",
  issuer: "https://your-org.okta.com",
  domains: ["yourcompany.com"],
  samlConfig: {
    entryPoint: "https://your-org.okta.com/app/YOUR_APP_ID/sso/saml",
    cert: "MIIDpDCCAoygAwIBAgIGAX...",
    callbackUrl: "https://dokploy.yourcompany.com/api/auth/sso/callback",
    spMetadata: {
      entityID: "https://dokploy.yourcompany.com",
    },
  },
});

A domain can only be registered with one provider at a time. Attempting to register a domain already claimed by another provider returns a BAD_REQUEST error.

Verify the sign-in button is visible

The sso.showSignInWithSSO public endpoint returns true when at least one provider is configured and the owner’s license is valid. On Dokploy Cloud it always returns true.

// Public — no authentication required
const showButton = await trpc.sso.showSignInWithSSO.query();
// true → "Sign in with SSO" button is displayed on the login page

Test the login flow

Open the Dokploy login page in a private/incognito window. Click Sign in with SSO, enter an email address whose domain matches your configured provider, and complete authentication in your IdP. On success you are redirected back to the Dokploy dashboard.

SSO Enforcement

sso.enforceSSO is a public query that returns true when the web server is configured to require SSO for all logins (password-based login is then blocked). On Dokploy Cloud this always returns false.

const enforced = await trpc.sso.enforceSSO.query();

When enforcement is active, users who attempt to sign in with a password are redirected to the SSO flow instead.

Managing Providers

List Providers — `sso.listProviders`

Returns all providers registered for the active organization, including their providerId, issuer, domain, and protocol-specific config objects.

const providers = await trpc.sso.listProviders.query();
// [{ providerId, issuer, domain, oidcConfig, samlConfig, organizationId }]

Get a Single Provider — `sso.one`

const provider = await trpc.sso.one.query({ providerId: "google-workspace" });

Returns NOT_FOUND if the provider does not belong to the active organization.

Update a Provider — `sso.update`

Accepts the same ssoProviderBodySchema as sso.register. If the issuer URL changes, the new issuer must already exist in the trusted origins list — the update is rejected otherwise.

await trpc.sso.update.mutate({
  providerId: "google-workspace",
  issuer: "https://accounts.google.com",
  domains: ["yourcompany.com", "subsidiary.com"],
  oidcConfig: {
    clientId: "NEW_CLIENT_ID",
    clientSecret: "NEW_CLIENT_SECRET",
    discoveryEndpoint:
      "https://accounts.google.com/.well-known/openid-configuration",
  },
});

Delete a Provider — `sso.deleteProvider`

await trpc.sso.deleteProvider.mutate({ providerId: "okta-saml" });
// { success: true }

Trusted Origins

Trusted origins control which identity provider URLs are permitted to initiate SSO flows. All mutations are available only to Enterprise users of the active organization.

Procedure	Type	Description
`sso.getTrustedOrigins`	query	Returns the array of trusted origin strings for the organization.
`sso.addTrustedOrigin`	mutation	Adds a new origin. Input: `{ origin: string }`. No-op if the normalized origin already exists.
`sso.removeTrustedOrigin`	mutation	Removes an origin. Input: `{ origin: string }`.
`sso.updateTrustedOrigin`	mutation	Replaces an existing origin. Input: `{ oldOrigin: string, newOrigin: string }`.

All origins are normalized to scheme://host before storage and comparison, so trailing slashes and paths are stripped automatically.

OIDC Configuration Reference

Field	Required	Description
`clientId`	✅	OAuth 2.0 client ID issued by your IdP.
`clientSecret`	✅	OAuth 2.0 client secret issued by your IdP.
`discoveryEndpoint`	Recommended	URL of the IdP’s `/.well-known/openid-configuration` document. When provided, endpoints are discovered automatically.
`authorizationEndpoint`	Optional	Override the authorization endpoint (used when `skipDiscovery: true`).
`tokenEndpoint`	Optional	Override the token endpoint.
`userInfoEndpoint`	Optional	Override the user info endpoint.
`jwksEndpoint`	Optional	Override the JWKS URI.
`tokenEndpointAuthentication`	Optional	`client_secret_post` or `client_secret_basic`. Defaults to `client_secret_post`.
`scopes`	Optional	Additional OAuth scopes to request (e.g. `["openid", "email", "profile"]`).
`pkce`	Optional	Enable PKCE (Proof Key for Code Exchange). Defaults to `true`.
`mapping`	Optional	Attribute mapping: `{ id, email, name, emailVerified?, image?, extraFields? }`.
`skipDiscovery`	Optional	Set `true` to skip auto-discovery and supply all endpoints manually.

SAML Configuration Reference

Field	Required	Description
`entryPoint`	✅	IdP SSO URL where SAML authentication requests are sent.
`cert`	✅	Public X.509 certificate from your IdP (PEM format, without headers).
`callbackUrl`	✅	Assertion Consumer Service (ACS) URL on your Dokploy instance (e.g. `https://dokploy.yourcompany.com/api/auth/sso/callback`).
`audience`	Optional	Service provider entity ID / audience restriction.
`spMetadata`	✅	Service provider metadata object (may be empty `{}`). Supports `entityID`, `binding`, `privateKey`, and assertion encryption fields.
`idpMetadata`	Optional	Full IdP metadata if available from a federation metadata URL. Overrides individual fields.
`wantAssertionsSigned`	Optional	Require signed assertions (recommended).
`authnRequestsSigned`	Optional	Sign outgoing `AuthnRequest` messages.
`signatureAlgorithm`	Optional	Override the default signature algorithm.
`mapping`	Optional	Attribute mapping: `{ id, email, name, firstName?, lastName?, extraFields? }`.

Always configure trusted origins before registering or updating providers. Failing to do so will cause provider updates that change the issuer URL to be rejected with a BAD_REQUEST error. Trusted origins are scoped to the organization owner — only the owner’s origins are checked.

On Dokploy Cloud, sso.showSignInWithSSO always returns true and SSO is available to all organizations. For self-hosted installations, SSO requires an active Enterprise license.

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Single Sign-On (SSO) with SAML and OIDC — Dokploy

Requirements

Supported Protocols

SAML 2.0

OpenID Connect (OIDC)

Enabling SSO

SSO Enforcement

Managing Providers

List Providers — `sso.listProviders`

Get a Single Provider — `sso.one`

Update a Provider — `sso.update`

Delete a Provider — `sso.deleteProvider`

Trusted Origins

OIDC Configuration Reference

SAML Configuration Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Infrastructure

Integrations

Administration

Enterprise

Documentation Index

​Requirements

​Supported Protocols

SAML 2.0

OpenID Connect (OIDC)

​Enabling SSO

​SSO Enforcement

​Managing Providers

​List Providers — sso.listProviders

​Get a Single Provider — sso.one

​Update a Provider — sso.update

​Delete a Provider — sso.deleteProvider

​Trusted Origins

​OIDC Configuration Reference

​SAML Configuration Reference

Build docs developers (and LLMs) love

Requirements

Supported Protocols

Enabling SSO

SSO Enforcement

Managing Providers

List Providers — `sso.listProviders`

Get a Single Provider — `sso.one`

Update a Provider — `sso.update`

Delete a Provider — `sso.deleteProvider`

Trusted Origins

OIDC Configuration Reference

SAML Configuration Reference