Dify Enterprise SSO with Keycloak

How Dify Enterprise SSO with Keycloak works

If you run Dify Enterprise and already operate, or are planning to operate, Keycloak as your identity provider, the goal is simple: workforce sign-in stays inside your own network and your own identity system. Dify Enterprise's SSO documentation lists OpenID Connect, SAML and OAuth2 as supported protocols, and Keycloak supports OpenID Connect and SAML 2.0. Both sides speak standard protocols, so the connection is built from those standards rather than from a dedicated Keycloak connector for Dify. Keycloak is open source under the Apache 2.0 license, which is separate from Dify's own terms: the Dify Open Source License forbids operating a multi-tenant environment without written authorization, and Dify Enterprise is licensed separately from the Community edition.

Dify Enterprise separates two SSO scopes: one for workspace access, where staff sign in to the Dify console, and one for web app access, where users sign in to published web apps. Each scope needs its own client registration and callback URL in Keycloak, so treat them as two configurations to plan, test and document. Before you build, confirm in the Dify Enterprise SSO documentation for your installed version which protocol, callback paths, claim names and attribute mappings it expects, and whether Keycloak realm settings such as token lifetimes and session limits interact with Dify's session timeout. Do not assume values from another identity provider's guide.

Decide early whether a single Keycloak realm serves both scopes and whether groups or roles from Keycloak will drive workspace membership, since that choice affects later SCIM provisioning and access reviews. Keep Keycloak's own administration, its database and its signing keys inside the same controlled environment as Dify, and confirm that the Dify Enterprise deployment can reach the Keycloak endpoints it needs on your private network. Record the client secrets and certificates in your secrets management process, and plan a test sign-in for each scope, plus a deprovisioning test, before any user depends on the setup.

What you need before connecting Keycloak to Dify Enterprise

Connecting Keycloak to Dify Enterprise depends on three layers being ready first: the Dify Enterprise platform, the Keycloak identity provider, and the names and certificates that users will type into a browser. Work through these cards before any client or protocol settings are created, so that sign-in problems later point to configuration rather than missing foundations.

Dify Enterprise platform baseline

Dify Enterprise runs on Kubernetes, not the single-host Docker Compose setup used for Community. The resources checklist requires Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later, a Qdrant vector database and S3-compatible or cloud object storage. Confirm each version against your own platform standards, and confirm which cluster will host Dify before you plan the SSO work.

Sizing for your user count

The checklist's production example uses six worker nodes with 8 CPUs and 32 GB of RAM each, plus a three-node Qdrant cluster. That example is not a sizing promise for your organization. Ask DeployOpen and the vendor to size workers, database and vector store against your expected named users, workspaces and workflow load before purchasing hardware.

Keycloak release and database

Keycloak's current release is 26.8.1, published October 13, 2026. Keycloak needs a supported production database, and PostgreSQL 14 to 18 is on the supported list. Use a highly available, synchronously replicated database if you plan a clustered Keycloak, and confirm which Keycloak release your team will standardize on and who owns its upgrades.

Keycloak realm and test group

Create a dedicated realm for Dify rather than reusing a realm that serves other applications. Add a small test group and two or three test users with known roles, such as one Dify administrator and one builder. Testing with a controlled group lets you verify workspace and web app access before any production population is synced.

DNS and TLS for both hostnames

Plan separate, stable hostnames for Dify and for Keycloak, each with a certificate trusted by the browsers and servers that will use them. Redirect URIs and the issuer URL depend on these names, so changing them later means re-registering clients. Confirm that Dify and Keycloak can reach each other's endpoints over TLS from inside your network.

Enterprise license and admin owner

Dify Enterprise is a custom-priced, commercial edition. The pricing page lists SSO, multiple workspaces, advanced security and professional support as Enterprise features, so SSO cannot be configured on Community. Before the work starts, confirm the license terms with the vendor, name an owner for the Dify admin account and record who can approve changes to identity settings.

OIDC or SAML for Keycloak: choosing the protocol

OpenID Connect (OIDC) is the protocol to choose when you want a standards-based client that receives identity as tokens. Keycloak acts as the OpenID Provider, and Dify Enterprise registers as a client with its own client ID, secret and redirect URIs. Dify's SSO documentation lists OpenID Connect as a supported protocol, so this path is the most direct route for teams starting from nothing.

Token claims carry identity: the ID token and userinfo response return the subject, email and name, and you map additional claims such as groups through a Keycloak client scope or protocol mapper.
Callback per scope: workspace sign-in and web app sign-in each need their own redirect URI, so plan two registrations or two callback paths rather than assuming one covers both.
Client secret handling: store the client secret in your secrets manager, rotate it on a schedule, and remember that Dify's SECRET_KEY is separate from the client secret.
Group claims need a deliberate mapper: confirm that the group claim name and format match what Dify Enterprise expects for role assignment before you test with real users.
Token lifetimes: align Keycloak session and token lifespans with the session timeout you set for Dify so users are not surprised by re-prompts.

Before you commit to OIDC, confirm the exact claim names and redirect URI format for your installed Dify Enterprise version in its SSO documentation.

Configuring Keycloak and Dify Enterprise step by step

This sequence takes a self-hosted Keycloak from production-ready settings to a verified sign-in into Dify Enterprise, with each scope tested before the next one builds on it.

Confirm Keycloak production settings and database
The platform team checks that Keycloak runs in production mode behind TLS, on a supported production database rather than the development file database, and with a database configuration that can be backed up and restored. Keycloak supports PostgreSQL 14 to 18 among other engines, so confirm the version against the database guide before you start. Record the public hostname, because every redirect URI and issuer URL in later steps depends on it. The step is done when Keycloak starts cleanly, its admin console loads over HTTPS, and a database backup has been restored in a test environment.
Create a realm and dedicated clients for each Dify scope
An identity administrator creates a realm for Dify and registers one client for workspace access and a separate client for web app access, because Dify Enterprise treats these as distinct SSO scopes. Use the Keycloak server administration guide for the realm and client steps, and keep the client type and protocol consistent with the option you chose, OIDC or SAML. Keep the client secret or signing certificate out of shared documents. The step is done when both clients appear in the realm and each one lists the protocol you selected.
Set redirect URIs and attribute or claim mappers
The administrator enters the exact callback URLs that the Dify Enterprise SSO documentation gives for each scope, then maps the attributes Dify needs to identify users, such as email, name and group membership. Mismatched redirect URIs are the most common cause of failed sign-in, so copy them character for character, including the scheme and trailing path. For OIDC, confirm the claims appear in the ID token; for SAML, confirm the attribute statement carries the same values. The step is done when a token or SAML assertion captured from a test login shows the expected email and group claims.
Configure Dify Enterprise SSO with the chosen protocol
A Dify Enterprise administrator enters the Keycloak issuer or metadata endpoints, client identifiers and secrets or certificates into the SSO settings for each scope, using the field names in the Dify Enterprise SSO documentation. Keep the workspace and web app configurations separate so that a change to one does not alter the other. Store secrets in your approved secret manager and confirm that the Dify SECRET_KEY was set before deployment, since changing it later logs out all users. The step is done when the settings save without validation errors and the Dify login page offers the Keycloak option for each scope.
Assign a test group in Keycloak
The identity administrator creates a small test group in the Keycloak realm, adds one test account to it, and links the group to the Dify access path so that only members of this group can reach the workspace during validation. Keep this group separate from production groups so that testing does not grant access to real users. Record which group maps to which Dify role so that later access reviews are simple to follow. The step is done when the group membership is visible on the test account and the group claim appears in the token or assertion.
Sign in with a test account and confirm workspace placement
A tester signs in to Dify through Keycloak using the test account and should land in the intended workspace with the expected role. Repeat the sign-in for the web app scope, and confirm that the session follows the protocol timeouts you configured. Inspect the token or assertion once more to confirm that no unexpected attributes are being passed to Dify. The step is done when the user reaches the correct workspace and web app, and the session ends as expected after the configured timeout.
Deny an account outside the test group
A second test account that is not in the group attempts the same sign-in. The expected result is a refusal, either at Keycloak or at Dify, and no workspace data should be visible. Check the Keycloak event log and the Dify audit or access logs to confirm the attempt was recorded. If the account gets in, stop and review the group mapping and the Dify role assignment before any real user is onboarded. The step is done when the outside account is denied and the denial appears in both logs.

How Keycloak identity attributes map to Dify roles and workspaces

This table compares each Keycloak source (user attribute, group, client role or token claim) with the Dify field it feeds, the protocol that carries it and who owns the value. Read it as a checklist for agreeing the mapping before go-live. The main takeaway is that Keycloak supplies identity and group signals, while workspace roles and web app access are assigned inside Dify and must be confirmed against your Dify Enterprise version.

Identity item	Keycloak source and Dify field	Protocol and owner
User identifier	Stable Keycloak user ID or username claim mapped to the Dify account identity, so the account survives email changes	OIDC `sub` or SAML NameID, carried in the token or assertion. Identity team owns the value
Email	Keycloak email attribute mapped to the Dify account email used for notifications and matching existing accounts	OIDC `email` claim or SAML attribute. HR or directory owner maintains accuracy in Keycloak
Display name	Keycloak first and last name mapped to the Dify profile name shown in the console and audit views	OIDC `name` or given and family name claims, or SAML attributes. Identity team owns the value
Group membership	Keycloak group or client role included as a claim, read by Dify as a signal for who may join a workspace. Dify does not infer roles from it alone	Group or roles claim in OIDC or SAML. Identity team publishes groups, Dify admins assign workspace roles
Workspace membership and role	Assigned in Dify Enterprise workspace settings, not taken from a Keycloak role by default. Mapping to Dify roles must be confirmed for your version	Set in Dify by workspace administrators. Dify admins own the role decisions and review them periodically
Web app access group	Keycloak group used for web app access only where your Dify version supports group-based rules. Confirm the scope (workspace or web app) for each SSO setup	Group claim with separate web app SSO scope. Dify app owners and identity team agree the groups
External users	Customers, partners or non-staff users kept in a separate Keycloak realm or group, and not granted workspace membership	Separate identity path or client for external web apps. Application owner and identity team own the boundary

Securing the Keycloak to Dify sign-in path

Sign-in to Dify Enterprise through Keycloak passes through three systems: the browser, Keycloak, and Dify's API and web services. The controls below protect the trust relationships between them, from transport encryption and client credentials to session lifetimes and the Dify settings that change who stays logged in. Review them together, because a weak link in one place undermines the others.

Encrypt every hop with issued certificates

Serve Keycloak and Dify over TLS using certificates your own certificate authority issues, and confirm that the redirect and token endpoints both use HTTPS with the same public hostnames the browser sees. Mismatched hostnames between Keycloak's frontend URL and Dify's public URL are a common source of failed callbacks and tempt teams to disable verification. Check that Keycloak's hostname settings match the production guidance before go-live.

Move client secrets out of config files

The OIDC client secret that Dify uses to exchange codes with Keycloak, and any signing material used in SAML, should live in a secrets manager and be injected at runtime, not stored in .env files committed to source control. Ask who can read the secret, how it is rotated, and whether rotation in Keycloak and in Dify's Enterprise SSO settings can be done in one change window. Log every read of the secret where your platform allows it.

Restrict redirect URIs to exact values

Register each Dify callback URL for workspace sign-in and for web app sign-in as a full, exact value in the Keycloak client. Avoid wildcards and broad path prefixes, because they let an attacker who controls a path under the same host receive authorization codes. Keep separate clients or separate redirect entries for each scope so a change to one does not open the other.

Set session and token lifetimes deliberately

Set Keycloak's SSO session idle and maximum lifetimes, access token lifespan and refresh behavior for the Dify realm or client to match your policy for workspace users. Shorter access tokens reduce exposure of a stolen token but increase load on Keycloak. Align the Dify session expectations with these values and test a forced logout, so you know how quickly a disabled user loses access.

Plan SECRET_KEY changes as outages

Dify's SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so changing it after deployment logs out all users. It also means stored SSO credentials must be handled through the rotation, not replaced casually. Schedule any key change as a maintenance event, communicate the logout to users, and verify SSO sign-in and stored credentials afterward. Confirm the procedure with Dify's environment reference before you rotate.

Require realm sign-in and govern outbound calls

Disable local Dify password sign-in for Enterprise workspaces so that every workspace user authenticates through the Keycloak realm, and remove or restrict any fallback accounts to named administrators. Separately, Dify's SSRF_PROXY settings route its outbound requests through a proxy that blocks internal and private address ranges, which governs the calls Dify makes to Keycloak's metadata or token endpoints. Confirm that Keycloak endpoints are reachable through that path and that the proxy policy has not been widened to make them work.

Keeping Keycloak upgrades and high availability from breaking sign-in

Treat every Keycloak upgrade as a change to Dify's sign-in path. Keycloak plans four minor releases a year and a major release every two to three years, and since Keycloak 26.0 it has said that breaking changes in a minor release will be opt-in, as explained in the Keycloak backwards compatibility notes. That lowers the risk of a minor upgrade, but it does not remove it, because your realm, clients and identity brokering settings still have to match what Dify expects. Keycloak migrates its database schema automatically at startup by default. For large deployments, the upgrading guide suggests applying the schema SQL manually, so a database administrator can review it before the new server starts. Decide which path you will use before your first upgrade, and confirm the choice against the upgrading guide for the target version. Keep the Keycloak Operator in manual approval mode, which the Operator documentation strongly recommends, so that operator updates never move Keycloak to a new version without a planned change window.

Keycloak documents three high availability architectures: a single cluster, optionally spread across availability zones, multi-cluster deployments (v2) without an external Infinispan cluster, and the deprecated multi-cluster v1 that used a separate Infinispan cluster per site. Both supported designs require a synchronously replicated database, so the database tier, not the Keycloak nodes, usually decides whether failover preserves sessions and configuration. Confirm the architecture, the database replication mode and the recovery steps with your database team before you connect Dify to a Keycloak endpoint that users depend on. After every Keycloak upgrade, after any change to Dify's SECRET_KEY (which logs out all users and affects the encryption of OAuth credentials), and after any failover test, sign in to Dify through each configured scope and confirm role mapping and sign-out behavior. Keep Keycloak's metrics endpoint enabled and alert on it, so that failed logins and node health are visible before users report them.

Common sign-in failures and how to fix them

This table lists the sign-in failures teams most often hit when Keycloak fronts Dify Enterprise, with the likely cause and a check you can run for each. Read it by symptom: find the error users report, confirm the cause with the listed check, then apply the fix. Most failures trace back to a URL, claim, clock, certificate or configuration value that differs between Keycloak and Dify.

Symptom	Likely cause	Fix
Keycloak shows an invalid redirect URI error after sign-in	The Dify hostname or scheme changed, so the callback URL registered in the Keycloak client no longer matches the one Dify sends	Compare the callback URL in the Keycloak client with the one shown in Dify's SSO settings, then update both for the new hostname and https scheme
Users authenticate but land with no workspace or see an access denied page	The group or role claim is missing from the token, or its name or values differ from the group names Dify expects	Decode a test token or check the client's mapper output, confirm the claim name and values match the Dify configuration, and confirm test users are members of the mapped groups
SAML login fails with an assertion not yet valid or expired message	Clock skew between the Keycloak host and the Dify API servers, so NotBefore or NotOnOrAfter checks fail	Compare the UTC time on both hosts, enable time synchronization on each, and confirm the assertion lifetime in the Keycloak SAML client settings
Sign-in fails with a TLS or certificate trust error when Dify calls Keycloak	Keycloak is served by a certificate issued by an internal certificate authority that the Dify containers do not trust	Add the internal root certificate to the trust store used by the Dify api and worker containers, then test the discovery URL from inside those containers
Every user is signed out after a configuration change	SECRET_KEY was changed after deployment, which invalidates existing session cookies and JWTs	Restore the previous SECRET_KEY value in the environment file if you need to avoid a forced logout, and plan any future key change as a scheduled sign-out
Sign-in breaks or claims change after a Keycloak upgrade	A newer Keycloak release altered default token contents, mapper behavior or client scopes, so Dify no longer receives the expected attributes	Before upgrading, export a sample token from the current version, repeat the export on a test instance after the upgrade, and diff the claims, then review the Keycloak upgrading guide for the target version
Workspace sign-in works but web app access fails, or the wrong callback is used	A web app SSO scope was configured with the workspace callback URL, so tokens return to the wrong endpoint	Check the SSO scope and its callback URL for each scope separately in Dify Enterprise, and register each callback in its own Keycloak client or redirect list

Questions teams ask before connecting Keycloak to Dify Enterprise

How much effort does a Keycloak to Dify Enterprise SSO integration take?

Effort depends mainly on four things: the protocol you choose, the number of sign-in scopes you configure, how you map Keycloak groups to Dify roles, and how mature your existing Keycloak realm already is. OIDC and SAML both work with Dify Enterprise, and the Enterprise SSO documentation lists OpenID Connect, SAML and OAuth2, so the protocol decision sets which client settings and callback URLs you build. Dify separates SSO for workspace access from SSO for web app access, so each scope you enable adds configuration and testing. A Keycloak realm that already has clean groups, tested client templates and a documented token mapping will move faster than one built ad hoc. Ask any partner to split the estimate by these four drivers in the written scope.

Can an in-house team connect Keycloak to Dify Enterprise without outside help?

A team with working Keycloak administration skills and Dify Enterprise access can usually do the core OIDC or SAML setup itself, because the steps are standard protocol configuration. The harder parts are the ones that surprise teams: group-to-role mapping, testing each sign-in scope, handling users who should not reach workspace data, and keeping the Keycloak upgrade path separate from Dify upgrades. Check whether your staff have run Keycloak in production, including its database and high availability design, before deciding. An outside partner is useful when you need a fixed-scope build with written deliverables, documented verification and a handover to your operators.

What does it cost to use Keycloak with Dify Enterprise?

Costs fall into four separate components. Dify Enterprise is custom priced, so confirm the license quote directly with Dify, because the public pricing page does not list an Enterprise price. Keycloak is licensed under Apache 2.0, so the software itself carries no license fee, but you still pay for the infrastructure it runs on, including servers or Kubernetes capacity, a supported production database and backups. The fourth component is staff time, both for the initial build and for ongoing operations such as upgrades and access reviews. If you choose Red Hat build of Keycloak for vendor support, that subscription is an added cost. Ask any implementation partner to separate one-time build fees from recurring support and infrastructure costs in the quote.

What does the team need to provide for the integration?

Plan to provide administrative access to the Keycloak realm and clients, a valid Dify Enterprise license and admin access to the Dify console, and DNS records for both Dify and Keycloak hostnames. You will also need TLS certificates that browsers and both systems trust, because SSO redirects fail when certificates are wrong. Provide a set of test users that cover each role and each sign-in scope, plus named people who can approve group mappings and access decisions. Confirm with your security team how Keycloak's own production configuration and database will be handled, since those sit outside the Dify setup but affect sign-in reliability.

How long does a Keycloak SSO integration with Dify Enterprise take?

Duration depends on scope, so no fixed timeline applies to every organization. The main variables are how many sign-in scopes you enable, how complex your group and role mapping is, whether your Keycloak instance already meets your production standards, and how quickly your team returns test results and approvals. Ask for the timeline to be written into the scope document with milestones for test users, staging sign-in, production cutover and handover. A clear timeline also shows which dependencies, such as certificates or license activation, could hold up the project.

Can Keycloak run on the same Kubernetes cluster as Dify Enterprise?

Technically it can, and many teams run both on one cluster, but the decision should rest on your availability, security and operations needs rather than convenience. Dify Enterprise is designed for Kubernetes and its resources checklist requires Kubernetes 1.24 or later, Helm 3.14 or later, PostgreSQL 14 or later, Redis 6 or later, a Qdrant vector database and S3-compatible or cloud object storage. Keycloak supports PostgreSQL 14 to 18 and needs a synchronously replicated database for its high availability designs. Co-locating means sharing node pools, upgrade windows and failure domains, so an identity outage could affect the whole platform. Many organizations keep the identity provider separate for that reason. Confirm the placement, namespaces and network policies with your platform team before the build starts.

How DeployOpen works on this

DeployOpen plans and implements the Keycloak side and the Dify Enterprise side of sign-in as one written scope, inside your own infrastructure. Engagements are fixed-scope, so the identity provider, protocol, role mapping and test cases are agreed before any configuration starts.

How we scope

Confirm your Dify Enterprise version, Keycloak version and the protocol (OIDC or SAML) before work begins.
Record which Dify scopes need SSO, workspace access, web app access or both, with separate callback URLs for each.
Agree the Keycloak realm, client, group-to-role mapping and session timeout values in a written scope document.

How we build

Deploy or validate the self-hosted Keycloak instance, database and high availability design you have chosen.
Configure the Keycloak client and Dify Enterprise SSO settings, then test sign-in for each scope and each test group.
Verify the full sign-in path stays inside your network, including token endpoints, JWKS and redirect URLs.

How we hand over

Deliver configuration records, callback URL inventory, role mapping tables and the test results used for acceptance.
Document the Keycloak upgrade and operator update approach, including how the Dify SECRET_KEY and sessions are handled.
Walk your identity and platform teams through the runbook for adding clients, rotating secrets and handling failed logins.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after the initial handover.
Retainers can cover Keycloak and Dify version reviews, so SSO settings are re-tested when either product changes.
Ask for a quote built from the written scope, which states the one-time work separately from any recurring support.