When does GitHub OAuth2 SSO fit Dify Enterprise?
Yes, GitHub OAuth2 is a documented sign-in option for Dify Enterprise, and it fits best for a developer-facing deployment where the people building and testing apps already hold GitHub accounts and the organization is comfortable tying Dify access to those accounts. The Dify Enterprise SSO documentation lists OpenID Connect, SAML and OAuth2 as supported protocols, and GitHub appears among the named identity providers alongside Microsoft Entra ID and Okta. The same documentation separates SSO for workspace access from SSO for web app access, so you should decide which of those scopes GitHub will cover before you register anything.
The main question for a platform team is whether GitHub is the system of record for who should be inside Dify. GitHub can confirm that a person controls an account, but it is usually not the source for employment status, role changes or offboarding. Your enterprise identity provider normally holds those signals, and it can drive SCIM provisioning and group-based access, which the Dify SCIM and role documentation covers in more depth. Before committing, confirm with Dify how GitHub sign-in interacts with workspace membership, whether group membership from GitHub can be used for access decisions, and what happens to a Dify account when a developer leaves the organization. Treat a GitHub-only setup as an acceptable choice for a smaller, developer-led group, and ask for a written comparison if auditors or security reviewers expect central deprovisioning.
Deciding between GitHub and an enterprise identity provider
GitHub sign-in can be a reasonable fit for a developer-facing Dify Enterprise deployment, but it answers a narrower question than an enterprise identity provider does. The factors below show where the two diverge, so you can confirm each one against your own identity policy before the OAuth2 app is registered.
Who signs in
GitHub accounts belong to developers, contractors and open-source contributors, which may not match the population that needs Dify access. Business users, customer success staff and external partners often have no GitHub identity at all. Count the people who need a workspace or web app login and check how many already hold an account in your organization's GitHub. The gap between those two numbers is the first decision input.
Offboarding through group membership
When an employee leaves, access should end in one place. Confirm whether your GitHub organization membership is tied to your HR lifecycle and whether removing someone from the organization or a team immediately removes their Dify access. Also confirm who owns that process, since a developer's personal GitHub account may sit outside your control.
MFA and conditional access ownership
Your enterprise identity provider likely enforces multi-factor authentication and device or location conditions centrally. Decide whether GitHub's sign-in controls meet the same policy, and who is accountable for them. If GitHub is the sign-in path, Dify inherits the strength of that account, so check the two-factor settings your GitHub organization requires.
Audit and session control
Security teams need to see who signed in, when, and how sessions end. Confirm which sign-in events your identity provider records and forwards to your logging platform, and whether GitHub's audit log covers the events you need. Session lifetime is set by Dify and the identity provider together, so test how a revoked account ends existing sessions.
Multi-workspace role mapping
Dify Enterprise supports multiple workspaces, and each needs access that matches a role. Enterprise identity providers commonly send group claims or SCIM-provisioned groups that map to workspace roles. Confirm whether GitHub teams can carry the group information you need and how your team will map a GitHub team to each workspace role, including who may grant or remove those mappings.
Web app access for non-developers
Dify web apps can be shared with people who never work in source control. If those users need access, a GitHub-based login pushes them toward accounts they may not want to create. Check which web app audiences you plan to serve, and whether they can be served through a separate identity provider scope instead of workspace sign-in.
How to register the GitHub OAuth app and connect it to Dify Enterprise
This sequence produces a working GitHub sign-in for one chosen Dify Enterprise scope, with the OAuth app, its credentials and the callback values all matched to that scope and checked against a non-admin test account.
Confirm the Enterprise version and target SSO scope
The platform owner confirms the Dify Enterprise version in use and decides whether GitHub sign-in is for workspace access (builders signing into the Dify console) or web app access (users of published apps). Dify Enterprise documents separate SSO scopes for these two uses, and each scope has its own callback value, so decide this before registering anything. Record the chosen scope and the Enterprise version in the change ticket. The step is complete when the owner can name the scope and the version, and the Enterprise SSO documentation for that version has been opened alongside this sequence.
Decide whether GitHub fits the user population
Before registration, the identity owner checks that GitHub accounts are the right sign-in for these users. GitHub suits developer-facing deployments where most users already hold personal or organization GitHub accounts. It is a weaker fit for broad staff populations, because account lifecycle, MFA enforcement and offboarding are controlled by GitHub organization settings rather than the enterprise directory. Confirm with the security team whether leavers will be removed in time, and whether an enterprise identity provider with SCIM provisioning is required instead. The step is complete when the owner has written down who signs in with GitHub and who is excluded.
Register the GitHub OAuth app with the scope callback
A GitHub organization owner or an account with rights to create OAuth apps registers a new OAuth application in GitHub developer settings. The application homepage and authorization callback fields must use the exact callback URL that Dify Enterprise provides for the chosen scope. Copy the callback path format from the Enterprise SSO documentation for your version rather than building it from memory, because the path differs by scope and by release. Use a name that identifies the Dify environment so the app is easy to find during audits. The step is complete when the GitHub app shows the callback URL for the chosen scope and the owner has saved it.
Record the client ID and client secret
After registration, GitHub shows the client ID and lets the owner generate a client secret. The owner copies both values into the password manager or secrets store approved for this environment, and restricts access to the people who administer Dify Enterprise SSO. The client secret is shown only once in most cases, so generate a new one if it is lost and rotate it through the same process. Do not paste the secret into tickets, chat or configuration files kept in source control. The step is complete when both values are stored in the approved location and the owner can retrieve them without relying on one person's workstation.
Enter the credentials and scope settings in Dify Enterprise
A Dify Enterprise administrator opens the SSO settings for the chosen scope and enters the GitHub client ID and client secret. Set the callback values for that scope exactly as the Enterprise SSO documentation specifies, and keep the workspace and web app scopes separate if both are being enabled. Confirm that the GitHub OAuth app and the Dify settings point to the same environment, because a callback mismatch is a common cause of failed sign-in. Save the configuration and record who made the change and when. The step is complete when the settings save without errors and the scope shows GitHub as an enabled provider.
Test sign-in with a non-admin account
The tester signs out fully, then signs in through GitHub using a regular account that holds no Dify administrator rights and is a member of the GitHub organization or group allowed to use the app. Test from a clean browser session, and repeat the test for the web app scope if that scope is enabled. Record the outcome, including any error text from GitHub or Dify. Testing with an administrator account can hide permission gaps, so use this account only for this test. The step is complete when the non-admin account reaches the intended Dify surface and the result is documented.
Verify workspace role assignment after sign-in
After the test sign-in, an administrator checks the workspace membership and role that the test account received. Confirm the account landed in the intended workspace with the intended role, and that it cannot reach apps or settings beyond that role. Compare the result with the role model agreed for the environment. If a user arrives with no role or with a role that is too broad, correct the mapping before onboarding real users. The step is complete when the administrator has signed off the role and access result in writing, and the same check is repeated after any later change to the OAuth app or the Dify SSO settings.
What GitHub identity data maps to Dify users and roles
This table compares each identity attribute GitHub can supply during OAuth2 sign-in with what an administrator must still configure in Dify. Read the last column as the open items to check against the Dify Enterprise SSO documentation and your own test tenant before you rely on any automatic mapping. The main takeaway is that GitHub confirms who signed in, while workspace membership and roles stay a Dify administration task.
| GitHub attribute | What GitHub provides | What you set manually in Dify | What to confirm with vendor docs |
|---|---|---|---|
| Numeric user ID | A stable account identifier that does not change when the username changes | Nothing known to be required | Which GitHub value Dify stores as the linked identity key, and whether it is kept on re-login |
| Username (login) | A handle the user can rename, so it may change over time | Display name or account name, if your policy requires a specific format | Whether Dify refreshes the username on each sign-in or keeps the first value |
| Verified primary email | An email only when the OAuth app requests email access and the user has a verified address | Account email if GitHub returns none or a private address | Whether Dify requires an email to create an account and how it matches existing accounts |
| Organization membership | Org membership only when the app requests organization read access and the org approves the app | Workspace membership for each user, since no org-to-workspace sync is documented | Whether Dify reads organization membership at all, and if not, what it treats as authorization |
| Team membership | Team membership only under the organization read scope, if the org grants it | Mapping teams to workspace roles, if you need it, by hand | Whether any team-based role assignment exists in your Dify Enterprise version |
| Workspace role | Nothing; GitHub does not define Dify roles | The role for each user in each workspace, set by an administrator | The exact role names available and who may change them |
| Offboarding signal | A removed org member loses org membership, but the change does not reach Dify | Disable or remove the Dify account when someone leaves | Whether SCIM or any sync exists for GitHub, since the documented SCIM examples cover Okta and Entra ID |
Where GitHub OAuth2 falls short of an enterprise identity provider
GitHub OAuth2 gives you sign-in, not a joiner-mover-leaver lifecycle. Access in Dify follows whoever can complete the GitHub login and is still in the right place for the workspace or web app. Nothing in the OAuth2 flow creates a Dify account before first sign-in, moves a person between teams when their role changes, or removes access automatically when they leave. Closing that gap requires provisioning from a directory, which is covered in the SCIM topic. Okta and Microsoft Entra ID are designed as the source of truth for identity, so SCIM from either one can create, update and deactivate Dify users and groups from HR-driven changes. GitHub organization membership is not a substitute for that, because it reflects GitHub administration rather than your employment records. Confirm in the current Dify Enterprise SSO documentation exactly which user attributes and group mappings GitHub sign-in supplies, and whether any of them can be used to assign workspace roles.
Your access decisions depend on GitHub's policies, not only Dify's. Who can sign in depends on the GitHub organization membership you choose to trust, and on the MFA and session rules that GitHub applies to those accounts. If a developer's GitHub account is compromised or loses its second factor, Dify has no independent control to stop it unless the sign-in path enforces additional checks. Enterprise identity providers such as Okta and Entra ID let you set authentication policy, conditional access and session lifetime in one console that also covers the rest of your applications. Ask the GitHub organization owners who will manage membership, whether SAML single sign-on is enforced on the organization, and how a removed member is cut off from Dify sessions that may still be active.
Session lifetime and revocation are split across two systems. Token validity for the GitHub grant is controlled by GitHub, while the Dify session cookie lifetime and any session timeout are set in Dify. Changing SECRET_KEY logs out all users, but that is a blunt instrument and not a per-user revocation method. Where GitHub is the only identity source, there is no single place to disable a non-GitHub user, such as an external reviewer, because those accounts do not exist in GitHub at all. Plan a revocation runbook that names the owner for each path: removing a GitHub membership, disabling the Dify account, and rotating shared secrets. Test it on a staging instance before you rely on it. The SCIM topic and the Okta and Entra ID sibling topics describe how an enterprise directory consolidates these steps.
Securing the GitHub SSO path in Dify
GitHub sign-in puts a developer identity provider in front of your Dify Enterprise instance, so the controls below decide who can get in and what a leaked credential can reach. Most of them sit in three places: the GitHub OAuth app, the Dify environment file, and the outbound network path. Check each one before the sign-in path goes into use.
Restrict the OAuth app to your organization
A GitHub OAuth app registered under a personal account, or one that accepts any GitHub user, lets people outside your company reach the sign-in path. Register the app under your organization and confirm that only members of approved organizations can authorize it. Review third-party application access on the organization side at least as often as you review team membership, because a removed employee can keep an authorized session until that access is revoked. Ask Dify's team to confirm which GitHub account or organization checks Enterprise applies at sign-in.
Protect the client secret and SECRET_KEY
The OAuth client secret is a credential that GitHub trusts, so store it in a secrets manager and keep it out of .env files committed to source control. Dify's environment reference says SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so the same key protects the stored GitHub secret. Generate it with enough entropy, restrict read access to the host and its backups, and record who holds a copy. Changing SECRET_KEY after deployment logs out all users, so plan that change as a scheduled maintenance event.
Keep callback URLs exact for each scope
Dify Enterprise uses separate SSO scopes for workspace access and web app access, so each scope needs its own callback URL registered with the OAuth app. Register only the exact URLs your deployment uses, with the same scheme, host and path, and avoid wildcard or extra entries that an attacker could redirect a sign-in to. When you change the public domain, update the callback in GitHub and in Dify together, or sign-in will fail for every user. Test each scope separately after any DNS or TLS change.
Route outbound calls through the SSRF proxy
Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges. Confirm that the Enterprise deployment sends its calls to GitHub through that path and that no other egress rule opens internal addresses to the identity exchange. Also review the Squid proxy isolation that Dify 1.16.1 added for agent sandboxes, because the sandbox network policy is separate from the SSO path. Test the proxy with a request to an internal address and confirm it is refused.
Plan secret rotation before go-live
Rotate the GitHub OAuth client secret on a fixed schedule and document the steps: generate the new secret in GitHub, update the stored value in Dify, verify sign-in, then revoke the old secret. Rehearse this in a staging instance first, because a failed rotation blocks every developer at once. Ask Dify and your own change process to confirm whether a SECRET_KEY rotation can be scheduled separately from the OAuth secret, since the two affect different sessions and credentials.
Separate developer sign-in from web app access
A GitHub account that can sign in to the Dify console should not automatically be able to use every published web app. Decide which people need builder access, which need only web app access, and which should use a different identity provider entirely, such as an enterprise directory for staff or a separate path for external users. Keep GitHub sign-in limited to the developer group, and assign web app access through the access levels Dify provides so that a developer account never becomes a general-purpose application login.
Common GitHub sign-in failures and their fixes
This table lists the sign-in failures most often tied to the GitHub OAuth2 configuration model, with the likely cause and the first fix to try for each. Use it to narrow a problem before reading logs, and confirm exact error messages against the Dify Enterprise SSO documentation and your own logs.
| Failure | Likely cause | Fix |
|---|---|---|
| Callback mismatch after sign-in to GitHub | The callback URL registered in the GitHub OAuth app does not match the URL Dify sends, often because the scheme, host or path differs between environments or the URL was copied from a different scope. | Register the exact callback URL shown in the Dify SSO configuration for each scope and environment, then retest the sign-in path from a clean browser session. |
| Client secret errors after rotation | The client secret was regenerated in GitHub, but the new value was not saved in Dify, or an old value remains in a deployment configuration or secret store. | Update the client secret in Dify with the new value, remove the old one from any other store, and restart the services that read the configuration. |
| User signs in but has no workspace role | GitHub authentication succeeded, but no Dify workspace membership or role was granted to that account, so access depends on the role assignment rather than the sign-in itself. | Assign the user to the workspace with the intended role, then ask them to sign out and sign back in so the new permissions take effect. |
| Sign-in blocked for members outside the GitHub organization | Access policy in the GitHub OAuth app or in the Dify configuration limits sign-in to members of a named organization, so accounts outside that organization are refused. | Confirm the organization restriction matches the intended population, and add an exception or a separate identity path for partners or contractors who need access. |
| Sessions end after SECRET_KEY changes | SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, so changing it invalidates existing sessions and makes stored OAuth credentials unreadable. | Keep SECRET_KEY fixed in your secret store, plan any change as a maintenance event with users notified, and re-enter OAuth credentials if they fail to decrypt after the change. |
| Sign-in fails with a generic error after a configuration change | Several settings changed at once, such as the callback URL, client ID, client secret or environment variables, so the cause is unclear. | Revert one change at a time, check Dify service logs and the GitHub OAuth app settings, and confirm exact messages in the vendor documentation before making further edits. |
Questions buyers ask before setting up GitHub SSO for Dify
Does Dify Enterprise support GitHub OAuth2 for single sign-on?
Yes. The Dify Enterprise SSO documentation lists OAuth2 among its supported protocols and names GitHub among the identity providers it covers. Confirm the exact configuration steps against the documentation for the Enterprise version you run, because the SSO pages are versioned. The documentation also separates SSO for workspace access from SSO for web app access, so you need to decide how GitHub sign-in applies to each scope. GitHub proves who the person is. Workspace membership and roles are still assigned inside Dify, so the design work sits in both systems.
What makes a GitHub SSO setup take more or less effort?
The main drivers are the number of workspaces, the SSO scopes you enable, and how roles are designed. Each workspace needs its own membership and role mapping, so a deployment with several workspaces carries more design and testing than one workspace. Enabling both workspace access and web app access adds a second sign-in path to configure and verify. Role design matters too: deciding which GitHub organization or team maps to which Dify role takes longer when many groups need different permissions. Separate staging and production instances each need their own registration and callback settings. The Community edition is limited to a single workspace, while the Enterprise edition adds multiple workspaces, so the Enterprise scope is what most often expands the work.
What does our team need to provide for a GitHub SSO project?
Three inputs decide whether the project can start without delays:
- GitHub organization owner access, so the OAuth app can be registered and team membership can be read for role mapping.
- Dify admin access on the Enterprise instance, plus the public hostname and TLS setup that the callback URLs will use.
- An identity policy decision: who may sign in (members of your organization only, or outside collaborators too), which GitHub teams map to which roles, how long sessions last, and what happens to access when someone leaves the organization.
The policy decision is the one most often left open. Settle it before configuration starts, because each choice changes the role and workspace setup that gets tested afterward.
Can our own team set up GitHub SSO for Dify without a partner?
Yes, a team with admin access to both GitHub and Dify Enterprise can register the OAuth app and enter the configuration. The harder work is the design and testing: deciding scopes and roles, mapping teams, and confirming that a user from each group lands in the right workspace with the right permissions. Teams that have run OAuth2 integrations before usually find the configuration step straightforward and the access design more demanding. A partner engagement is fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts. Whichever path you take, ask your team to document the mapping decisions so that operators can maintain them later.
How long does GitHub SSO for Dify take to set up?
No duration is published for this work, so the answer depends on scope. The main variables are the number of workspaces, the SSO scopes in use, the number of environments, and how many roles and GitHub teams need mapping. A single workspace with one scope and a small role model is a much smaller job than several workspaces across staging and production. DeployOpen does not publish a price list. Enterprise pricing is custom and follows the written scope, so the timeline arrives with the quote. Ask for the timeline, the testing steps and the handover items to be listed in that written scope. You can compare the Community and Enterprise editions on the Dify pricing page to confirm which edition covers your scope.
What changes if we move from GitHub to Okta or Entra ID later?
The role model and workspace design can carry over, but the identity layer changes. You register a new application in the new provider, update the callback URLs for each SSO scope, and rebuild the group mapping from the new provider's groups instead of GitHub teams. User identifiers also differ between providers, so existing accounts must be matched to the new identities and tested before cutover. Provisioning is a separate decision: user and group sync through SCIM is covered on its own, so plan it as a second project. The Dify Enterprise SSO documentation lists Okta and Entra ID alongside GitHub, so confirm the steps for your version before you choose GitHub as a short-term option.
How to test the GitHub SSO path before users depend on it
Test the GitHub sign-in path in a staging Dify Enterprise environment before any developer depends on it, and keep that staging instance on the same Enterprise version as production. A version mismatch can change how SSO callbacks, role mapping and session handling behave, so the test results would not describe what users see. Before any upgrade used for testing, take a backup and follow the upgrade guide for the target version on the Dify releases page, as the Docker Compose documentation advises for self-hosted deployments. Confirm the exact Enterprise version and its SSO configuration steps with your DeployOpen or Dify contact, since the Enterprise documentation for your version governs the settings.
Build the test with at least two GitHub accounts inside a test GitHub organization or team: one account that should be allowed and one that should be refused. Sign in with each and record the outcome, including the screen shown to the refused user. Then confirm the role each allowed account receives in Dify, since a user who signs in successfully may still land with more or fewer permissions than intended. Repeat the check for each workspace role your design uses. Do the same for a web app access check if external users will reach any published app through GitHub, because workspace sign-in and web app sign-in are separate SSO scopes.
Run the failure and rotation tests before go-live. After a refused sign-in, check the Enterprise logs for the attempt, so your team knows what a denied developer looks like in an investigation. Then rehearse rotation in staging: change the GitHub OAuth client secret, update it in Dify, and confirm sign-in still works. Test a SECRET_KEY change in staging as well, because the environment reference says changing it logs out all users and affects how OAuth credentials are encrypted, so plan a maintenance window and a re-login message. Write each test, its expected result, the actual result and the tester into a dated record, and keep it with your access review evidence.
How DeployOpen scopes and delivers Dify SSO work
DeployOpen plans, implements, tests and documents Dify Enterprise SSO with GitHub OAuth2 inside your own infrastructure, as a fixed-scope engagement agreed in writing before work starts. The scope covers the OAuth2 app registration, the SSO configuration for workspace and web app access, and the controls around the sign-in path.
How we scope
- Written scope names the Dify Enterprise version, hosting model and GitHub organization or account that will sign users in.
- Scope lists which SSO scopes apply, workspace access, web app access or both, and which users must still be covered by another method.
- Scope records the accounts, callback URLs and secrets that your team must provide or approve before configuration begins.
How we build
- We register the GitHub OAuth2 app, configure the Dify Enterprise SSO settings and test each sign-in path in a non-production environment first.
- We set and document how the SECRET_KEY and OAuth credentials are stored and rotated, so the configuration stays under your control.
- We test sign-in for allowed members, denied accounts and users who leave the GitHub organization, and record the results.
How we hand over
- You receive a configuration record with callback URLs, scopes, owners and the steps to rotate the OAuth2 client secret.
- Runbooks explain how to add or remove users, what GitHub does not cover, and when an enterprise identity provider should replace GitHub.
- Handover includes a walkthrough with your identity, platform and security staff so they can operate and audit the setup.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the initial engagement.
- Support covers re-testing sign-in after Dify upgrades, since release notes and environment variables can change between versions.
- Quotes follow from the written scope. Ask us to confirm what a retainer includes for your Dify version and your GitHub setup.
