How Keycloak single sign-on works with Open edX
If your organization already runs Keycloak, you probably want learners and staff to reach Open edX without a second password. Open edX third-party authentication can trust Keycloak over SAML 2.0 or OAuth2, and the work is configuration, attribute mapping and testing in infrastructure you control. The integration covers the login flow, the mapping of Keycloak attributes to Open edX account fields, account linking for people who already have a local Open edX account, and the registration choices for first-time sign-ins. It does not cover hosting Keycloak, its realms and clients, or deploying Open edX itself. Those are separate pieces of work with their own owners and decisions.
Open edX third-party authentication supports SAML 2.0 and Shibboleth, LTI, and OAuth2 providers. By default, the OAuth2 list names Google, Facebook, LinkedIn and Azure Active Directory, and it does not name Keycloak. That means the Keycloak connection depends on which backend your Open edX release provides or on a backend you add and maintain yourself. Before design starts, confirm which Keycloak-facing backend fits your Open edX release with your deployment owner and implementation partner. The project supports only its latest named release, which is Verawood at the time of writing, so record the release, the backend and its settings in your design document. A backend that works on one release may need changes after an upgrade.
Four decisions shape the build. First, decide which Keycloak realm and client carry the login and which attributes Keycloak sends to Open edX, such as email, username and name fields. Check what your identity source actually holds before you promise a mapping. Second, decide which Keycloak identifier becomes the key for an Open edX account, because a changed email address or username can otherwise create a duplicate learner. Third, decide whether an existing local account is linked on first SSO login, and how accounts without a verified match are handled. Fourth, decide whether auto-registration creates an account for any valid Keycloak user or only for members of a group or role you select, and who approves that rule. Write these choices down before configuration, because they define what the test plan must prove.
Verification should cover the cases where SSO most often fails: first login for a new user, repeat login, a user with an existing local account, a user disabled in Keycloak, and a session that stays open after sign-out. Run these in a staging LMS with a test realm and test users. Capture the attributes Keycloak sends during each test so that mapping errors appear before go-live. Review the Keycloak production configuration guidance for the realm, clients and administrative access, and give the Open edX login settings a separate review, since the two systems each hold part of the trust decision.
What the Keycloak and Open edX SSO integration needs before setup
Keycloak and Open edX SSO depends on a set of agreed versions, data stores, hostnames and named people before any configuration begins. Each card below names one prerequisite and the check to complete with your team. Confirming them in writing early prevents delays from missing access, mismatched releases or certificates that one side does not trust.
Keycloak release and distribution
Confirm which Keycloak build you will run. The current release is 26.8.1, published October 13, 2026, according to keycloak.org. If your organization needs vendor support, the Red Hat build of Keycloak replaces Red Hat Single Sign-On, and Red Hat's product page showed 26.6 as its latest version, so confirm the current Red Hat build with Red Hat. Since Keycloak 26.0, the project plans four minor releases a year and says breaking changes in minor releases are opt-in, so decide your upgrade approval process now.
Supported production database
Keycloak does not use its default dev-file database in production. The supported production options include PostgreSQL 14 to 18, and the list also covers other engines such as MySQL, MariaDB and Oracle Database. Confirm the database version, backup method and who operates it. If you plan a high availability design, both supported designs require a synchronously replicated database. Also decide whether Keycloak migrates its schema at startup or whether your team applies the SQL manually, which the upgrading guide suggests for large deployments.
Open edX release and Tutor version
Open edX supports only its latest named release, and it cannot support more than one release at a time. Verawood is the current named release, published 30 July 2026. Confirm that your running Open edX is deployed with Tutor and that both the Tutor version and the platform match Verawood before work starts. If your platform is on an earlier release, plan that upgrade first, because the SSO configuration should be built against the release you will keep.
Hostnames, DNS, TLS and callback URLs
Keycloak and Open edX must reach each other by stable hostnames that resolve from both the browser and the back channel. Confirm DNS records for the Keycloak issuer and the Open edX LMS, certificates that both systems trust, and the exact callback URLs that will be registered. Build a test environment that uses the same hostnames as production, because callback URLs and certificates tied to a different name will fail at cutover.
Identity source and attribute access
Identify where your learner and staff accounts live, such as an existing directory, an LDAP or Active Directory store, or users already held in another Keycloak realm. Request a read-only service account for that source and document which attributes will feed Open edX, such as username, email and name. Confirm whether the source is the system of record for account status, because that decides how account linking and auto-registration should behave.
Named owners on both sides
Assign one accountable administrator for the Keycloak realm and one for the Open edX LMS and Tutor deployment. Each owner should be able to approve client configuration, certificate changes and attribute mapping decisions. Also agree who signs off the test results and who can authorize a rollback. Without named owners, changes to redirect URIs or certificates often stall between the identity team and the learning platform team.
Choosing between the SAML 2.0 and OAuth2 paths for Keycloak
The first decision is which Open edX third-party authentication backend your Keycloak connection will use. Open edX documents SAML 2.0 as one of its supported identity provider protocols, and its OAuth2 providers are listed by default for Google, Facebook, LinkedIn and Azure Active Directory. Keycloak speaks OpenID Connect, OAuth 2.0 and SAML 2.0, so both paths are open at the protocol level. What decides the path is whether the Open edX release you run supports the backend you intend to use for a generic identity provider. Confirm that against the Open edX identity provider documentation for your release before build work starts. DeployOpen does not assume a generic OpenID Connect backend is available in your deployment, and your plan should not assume it either.
On the SAML 2.0 path, Keycloak needs a SAML client that represents the Open edX LMS, with its entity ID, assertion consumer endpoint and signing certificate configured. Protocol mappers then place the email address, username and display name into the assertion. Open edX needs a SAML provider entry in third-party authentication that holds the Keycloak metadata and the attribute names it reads. Attribute availability is therefore set on the Keycloak side: a field that is not mapped into the assertion will not reach the LMS, so list every attribute the account flow requires before testing. Single logout depends on both ends honoring SAML logout messages, so test whether ending a Keycloak session also ends the LMS session. Certificate rotation is a two-sided change. The new signing certificate must be in place in Keycloak and the metadata refreshed in Open edX, so plan an overlap window and name an owner for certificate expiry dates.
On the OpenID Connect path, Keycloak needs an OpenID Connect client with the Open edX redirect URI, a confidential client secret and the scopes that return the email and profile claims. Protocol mappers control which claims appear in the ID token or the userinfo response. Open edX needs a provider configuration holding the client ID and secret for whichever backend your release supports. Attribute availability depends on the claim names that backend reads, so the mapper names in Keycloak must match what the backend expects. Verify this with a test learner and a test staff account. Logout behavior is also backend specific, and the team should not assume that a Keycloak logout reaches the LMS session until a test shows it. Secret rotation is simpler to schedule than certificate rotation, but the new secret must be entered in Open edX and the old one retired only after sign-in is confirmed. Operators who rotate it should know where the secret is stored in your Tutor configuration.
Before choosing, confirm from the release documentation which paths are supported, then run a short pilot on each supported path. Record which attributes arrive, whether an existing account is linked by email, whether accounts are created automatically on first sign-in, and how logout behaves from both directions. These observed results matter more than the protocol label. When you request a quote, ask the partner to state which protocol and backend will be built, which release documentation the design was checked against, what the attribute mapping covers, and which rotation runbook will be delivered. A written scope that names these items makes the trade-off visible before the build starts.
Keycloak and Open edX SSO setup sequence, step by step
This sequence takes Keycloak and Open edX from agreed versions to a tested production sign-in, with a check that closes each step. It covers the realm and client setup, the attributes Open edX receives, the provider settings managed in Tutor, and the account linking and logout behavior that learners and staff will see.
Confirm versions and the release plan
Record the Keycloak and Open edX versions each environment will run, and confirm them in writing with the platform owner. Open edX supports only its latest named release, and the current one is Verawood, published 30 July 2026, with the next releases, Willow and Xylon, listed for December 2026 and June 2027. Keycloak's current release is 26.8.1, published October 13, 2026, and the project plans four minor releases a year, so agree which minor version you will pin and who approves each update. Done when a signed version sheet lists both products, their hosting location, and the owner of each upgrade decision.
Create a dedicated realm and naming convention
Create a Keycloak realm for Open edX, separate from realms used by other applications, so its users, clients and login flows can be reviewed on their own. Choose names that show the environment and the hostname, for example an illustrative realm called openedx-staging for a staging environment, and write the convention down before you create any client. Decide whether learners and staff share one realm or use separate realms, because that choice shapes group mapping later. Done when the realm, its naming rules and its owner are recorded in your configuration documentation and the realm exists in the non-production Keycloak environment only.
Create the client with exact redirect URIs
Create one client per environment in the Open edX realm, choosing SAML 2.0 or OpenID Connect to match the protocol you will enable in Open edX third-party authentication. Set the redirect URIs to the exact LMS hostname and callback path that your release expects, including the scheme, because a hostname mismatch is a common cause of failed logins. Confirm the callback path against the documentation for your Open edX release, and decide whether Studio needs its own client. If Keycloak runs on Kubernetes, the Keycloak Operator can manage KeycloakSAMLClient and KeycloakOIDCClient resources, which keeps client definitions in version control and routes changes through review. Done when a test sign-in from the LMS hostname reaches the Keycloak login page without redirect errors.
Define the attributes and claims Open edX needs
List the attributes Open edX must receive: email, username, full name, and any organization or role attribute your policies require. For each one, record its Keycloak source (a built-in user property, a user attribute or a group membership), the claim or SAML attribute name, and whether login depends on it. Agree with the data owner which attributes may leave the Keycloak realm, since each one is personal data that Open edX will store. Add the mappers to the client and confirm the claim names match what your Open edX provider configuration expects. Done when a mapping sheet has one row per attribute and a test user's token or assertion shows every required value populated.
Configure the provider through Tutor
Set up the Keycloak provider in Open edX through Tutor-managed configuration, so the settings survive container rebuilds and upgrades. Tutor is the official Docker-based distribution and supports plugins and hooks, so provider endpoints, credentials and attribute mapping belong in its configuration. Store the client secret or certificate in your secrets system and inject it at deploy time, keeping it out of the repository. Confirm every setting name against the third-party authentication documentation for your Open edX release, because names can change between releases. Done when the Keycloak option appears on the LMS login page in a non-production environment and the Tutor configuration for that environment is committed to version control.
Test login, attributes, logout and session expiry
Sign in as a non-production user for each role you support and check what Open edX received. Confirm that the account has the expected username, email and full name, and that any organization or role value lands in the field your design specifies. Sign out from the LMS and from Keycloak, and confirm the session ends in both places. Then test session expiry by shortening the lifetime in a test realm, and check that the Open edX session behavior and the Keycloak idle and maximum timeouts match your policy. Done when a written test log records each role, the attributes shown on the account, and the logout and expiry results.
Decide account linking and registration behavior
Decide what happens when a Keycloak login matches an existing Open edX account and when it matches none. Account linking connects a federated identity to an account that already exists, which needs a matching rule, such as a verified email address, that the identity owner has approved. Auto-registration creates an account on first login, which should only start after the attribute rules from the mapping sheet are complete and the data collected is justified. Test both paths: a learner with an existing account and a new user with no account. Confirm that no duplicate account appears and that each user receives the intended role. Done when both results are recorded and signed off by the owner of the learner data.
Promote to production with a rollback plan
Promote the tested configuration through the same Tutor project and Keycloak client definitions, with production hostnames and secrets supplied by your deployment process. Before the change, record the previous Keycloak client settings, the Tutor configuration version and the steps that restore the earlier login path, and name who may trigger the rollback. If Keycloak runs on Kubernetes, keep the Operator in manual approval mode, as its documentation strongly recommends, so an update does not start without review. Plan database schema changes explicitly, because Keycloak migrates its schema automatically at startup by default. Done when a pilot group signs in successfully in production and the rollback steps have been confirmed in a non-production environment.
Attribute mapping from Keycloak to Open edX accounts
This table maps the Keycloak claims, user attributes and SAML assertion attributes that Open edX needs to create and match accounts, and the effect of each one missing. Read the first three rows as the minimum for sign-in and the rest as optional profile or cohort data. Field names in the Open edX third-party authentication settings differ by release, so confirm each name against the release you run before configuring anything, and agree with your privacy owner which extra personal data may be sent at all.
| Open edX field | Keycloak source | Required or optional | Failure if missing |
|---|---|---|---|
| Email (login identifier) | Email claim, or the email attribute in the SAML assertion | Required | Account cannot be matched or created, and duplicate accounts appear if the email changes |
| Username | preferred_username claim or username attribute, checked against Open edX username rules | Required | Sign-in fails if the value breaks username rules or collides with an existing account |
| Stable subject identifier | Keycloak user ID (sub claim) or SAML NameID | Required for account linking | Returning users can be linked to the wrong account or left unlinked after an email change |
| Full name | given_name and family_name claims, or a full name attribute | Optional | Profile name is blank, and certificates may show an incomplete or incorrect name |
| Learner or staff indicator | Keycloak realm role, client role or group membership; not mapped by default, so it needs a custom step or manual grant | Optional | Staff may lack Studio access, or learners may receive elevated rights if the mapping is wrong |
| Organization or cohort | Keycloak group path or custom user attribute agreed with the client | Optional | Learners are not placed in the intended cohort or organization |
| Preferred language | locale claim or a custom attribute | Optional | Interface falls back to platform defaults for each learner |
Account linking and auto-registration choices for Keycloak users
The first decision for Keycloak and Open edX SSO is whether a learner's first successful Keycloak login creates a new Open edX account automatically, or whether that login must match an account that already exists. Open edX third-party authentication lets you control this per identity provider, so the Keycloak connection should be designed as a set of explicit rules rather than left at defaults. Document three answers before any configuration starts: whether new accounts are created on first login, whether an existing local account with the same email is linked or blocked, and how accounts that carry elevated Studio or LMS roles are treated. Each answer changes what your support desk, registrar and course teams will see on day one.
Matching on email alone is the most common shortcut and the one that causes the most trouble. Email addresses change when people marry, change employers or rename themselves, and they are sometimes reassigned to a new person after a former learner leaves. If Keycloak asserts an email that already belongs to a different Open edX user, an automatic link attaches the wrong person to someone else's course history. Ask your identity team which attribute is the stable identifier in Keycloak, such as a immutable user ID or an employee number mapped from a federated directory, and confirm whether the Open edX side can key the link on that value. Treat email as a contact detail to be verified, not as the permanent key for the account.
A split identity is the less visible failure. If a learner signs in through Keycloak and receives a new account, their enrollments, grades, certificates and progress stay on the old account. The learner then sees an empty course list, opens a support ticket, and staff may merge records by hand without a clear audit trail. Duplicates also undermine reporting, because completion counts and learner totals no longer match the identity provider. Before go-live, define a documented merge or re-link procedure, decide who may approve it, and record each change. Run a sample of real-world cases from your existing learner list through the rules to see where duplicates would appear.
Pilot auto-registration by limiting it to a known user group, such as one cohort, one business unit or a set of staff from the course operations team, whose Keycloak accounts are provisioned and reviewed in advance. Keep linking to existing accounts manual during the pilot, and send any unmatched or ambiguous login to a holding state where an administrator confirms the match. Expand the group only after you have reviewed duplicate and mismatch reports for a full course run. Staff and users with elevated roles should stay outside automatic registration until role assignment is tied to a Keycloak group that your administrators control.
Confirm the account linking and registration behavior of the Open edX release you plan to run before you finalize these rules, because third-party authentication behavior differs by backend and by release. The current named release is Verawood, and Open edX supports only the latest named release, so plan the Keycloak configuration against the version you will actually operate and recheck it at each upgrade. Ask the implementation team to test the exact SAML 2.0 or OAuth2 path, including first login, repeat login, changed email and a reused email, in a staging environment that mirrors production settings.
Hardening the trust between Keycloak and Open edX
The SSO link between Keycloak and Open edX carries learner and staff identities, so its weakest setting sets the risk for the whole platform. The cards below cover transport, token validation, session and secret lifecycle, access control and logging, in the order a security team would review them. Each one names a decision your team or your implementation partner should record before go-live.
TLS on every hostname
Every hostname in the chain, including the Keycloak endpoint, the Open edX LMS and Studio, and any metadata or discovery URL, should serve valid TLS with a certificate chain your browsers and servers trust. Name one team that owns certificate issuance and renewal, and confirm that renewal alerts reach that team before expiry rather than after a login outage. Check that backchannel calls from Open edX to Keycloak also verify the certificate.
Signed assertions and validated tokens
Require signed SAML assertions or signed OpenID Connect tokens, and confirm that Open edX validates the issuer, audience and signing key on every login. Test with a deliberately wrong audience and a token from a different client to prove the rejection works. Record which certificate or key Open edX trusts, and who approves a change to it.
Short Keycloak session lifetimes
Set session idle and maximum lifetimes in Keycloak's realm settings to match your policy for learners and staff, and use shorter values for administrator and instructor accounts. Confirm how Open edX sessions relate to the Keycloak session, since a long Keycloak session can silently re-authenticate users after the platform believes they have logged out. Document the values and the reason for each.
Secret and certificate rotation schedule
Client secrets, signing keys and SAML certificates each need an owner, an interval and a tested rotation procedure. Write the schedule down, include the Open edX settings that must change in the same window, and rehearse a rotation in a non-production realm. Ask your partner to show how the old and new keys overlap so that logins continue during the change.
Restricted client redirect URIs
Register exact redirect URIs for the Open edX client in Keycloak, with no wildcards and no shared placeholder entries. Each URI should match one Open edX hostname and path. Review the list whenever a domain or environment is added, because a broad redirect pattern lets an attacker send an authorization code to a host you do not control.
MFA policy enforced in Keycloak
Set multi-factor authentication as a Keycloak authentication flow or conditional requirement, so every login through the federated path meets the same policy regardless of entry point. Avoid relying on an Open edX setting for this, because a local login path or a second identity provider could bypass it. Confirm which roles require MFA and test a login from each path.
Admin console access for named operators
Limit Keycloak administrator roles to named individuals, keep the master realm separate from the working realm, and require strong authentication for console access. Review the list of administrators on a fixed schedule and remove accounts when people change roles. Log every change to clients, mappers and authentication flows, because these settings decide who can sign in to Open edX.
Production configuration and metrics
Apply Keycloak's production configuration guidance before go-live, covering hostname settings, proxy headers, the database connection and disabling development-only modes. Enable the metrics endpoint and send login failures, token errors and certificate expiry into your monitoring stack with alerts. Confirm that metrics endpoints are reachable only from monitoring networks.
Review identity logs for personal data
Open edX learner data flows through this trust, so identity and event logs in Keycloak and the LMS can contain names, email addresses and account identifiers. Decide which fields are logged, how long logs are kept, who can read them and how they are deleted. Involve your privacy lead in this review before enabling verbose event logging in production.
Common Keycloak SSO failures in Open edX and how to fix them
This table lists common Keycloak and Open edX SSO failures with their likely cause, first check and the team that should fix each one. Start each investigation with logs from both Keycloak and the LMS plus a fresh test login, so you can see which side rejected the exchange. Most failures trace back to a hostname, certificate, clock, attribute or proxy setting, so check those before changing the integration.
| Failure | Likely cause | First check (both sides) | Owner of the fix |
|---|---|---|---|
| Redirect URI mismatch after hostname change | Keycloak client still lists the old LMS hostname as a valid redirect URI | Compare the redirect URI in the Keycloak client with the callback URL in the LMS log and the browser error | Keycloak administrator, with the platform owner confirming the new hostname |
| Certificate or signature errors after rotation | Open edX holds the old signing certificate or metadata, or the realm signing key changed | Read the SAML or token validation error in the LMS log, then compare certificate fingerprints in both systems | Keycloak administrator for realm keys; Open edX operator for the stored provider settings |
| Clock skew rejects tokens or assertions | Keycloak and LMS hosts drift apart, so issued-at or validity-window checks fail | Compare UTC time on both hosts and search both logs for time validity errors | Infrastructure team that runs the hosts and their time synchronization |
| Missing email attribute blocks registration | Keycloak does not send the email claim or attribute that the Open edX mapping expects | Run a test login and check which attributes arrive at Open edX against the configured mapping | Keycloak administrator for the mapper; Open edX operator for the attribute mapping |
| Duplicate accounts after email changes | A learner changes email in Keycloak, so Open edX creates a new account instead of linking the existing one | Search the LMS for both addresses and compare the account linkage recorded for each | Open edX operator, with support staff deciding any merge under the institution's policy |
| Users locked out after an unexpected Keycloak upgrade | A minor release changed a default, the schema migrated at startup, or a client setting changed | Check Keycloak startup and migration logs, then run a test login for a known user | Keycloak administrator, with the upgrade decision held by the platform owner |
| Login loops behind a proxy | The proxy forwards the wrong scheme or host, so Open edX builds callbacks with the wrong address | Inspect forwarded headers at the proxy and trace the redirect chain in a browser, then check LMS request logs | Network or platform team for the proxy; Open edX operator for site settings |
Keeping Keycloak and Open edX upgrades from breaking sign-in
Sign-in can break from either side, because Keycloak and Open edX move on different release schedules. Keycloak has planned four minor releases a year since version 26.0, and the project says breaking changes in a minor release are opt-in. Open edX supports only its latest named release, which is Verawood, published on 30 July 2026. Treat the two systems as separate upgrade tracks with their own change reviews, and retest the SSO path whenever either track changes. The next Open edX named releases, Willow and Xylon, are listed for December 2026 and June 2027, so the planning cycle will repeat within the year.
On the Keycloak side, two settings decide how much control your team keeps. If you run Keycloak through the Keycloak Operator, keep operator updates in manual approval mode. The Operator documentation strongly recommends this to avoid unintended automatic upgrades. The second setting is database migration. Keycloak migrates its database schema automatically at startup by default. The upgrading guide suggests manual migration for large deployments, where administrators apply the SQL themselves and review it first. Choose the mode before the staging run, because a failed startup migration can block every sign-in path. Take a database backup before each change and confirm in the upgrading guide whether a schema change can be reversed by redeploying the earlier image.
On the Open edX side, plan each upgrade on Tutor as its own project, not as a side effect of the Keycloak change. Each named release carries its own breaking changes, data migrations and deprecations, so read the release notes for the target before you start. Verawood added a new Studio sidebar, a redesigned instructor dashboard and an AI Extensions Framework, and those changes do not sit in the sign-in path. The risk is in the third-party authentication configuration: the SAML 2.0 or OAuth2 provider settings, the redirect addresses, the attribute mapping and the account-linking behavior. Confirm with your Tutor deployment that each of these survives the upgrade, and check the Open edX release notes for any change to the third-party authentication settings.
A practical sequence is to upgrade a staging copy of both systems in a fixed order and test after each step. Upgrade Keycloak first, then run the test login against the unchanged Open edX staging site, so any protocol-level problem appears before the platform changes. Then upgrade Open edX on Tutor and run the full test again. The recorded test login should cover four cases: a learner with an existing linked account, a staff user, a brand-new user who triggers auto-registration, and a user whose attributes changed in Keycloak. Record the date, the Keycloak and Open edX versions, the client identifiers used and the result for each case. Before each step, store the current image tags and database snapshots, and write down the rollback steps and who approves them. Production should not move until the staging record is complete and reviewed.
What buyers ask about Keycloak SSO for Open edX
What drives the cost and effort of a Keycloak SSO integration for Open edX?
The main drivers are the protocol choice, the number of user sources, the attribute and linking rules, how mature your Keycloak setup already is, the testing scope, and whether Keycloak and Open edX are already running. SAML 2.0 and OAuth2 both work with Open edX third-party authentication, but each needs its own client configuration, certificate or secret handling and attribute mapping, so choosing one early avoids rework. Each additional user source, such as a directory federated into Keycloak or a second identity broker, adds mapping rules and test cases. Rules for linking existing Open edX accounts to federated identities, and for auto-registration, decide how many edge cases must be tested. A Keycloak instance that already has realms, clients and logging in place shortens the work, while a first deployment adds hosting and hardening. Ask any provider for a quote that lists each of these items separately, with the environments included and the test scope written out.
Can our team set up Keycloak SSO for Open edX without outside help?
Yes, if your team already has someone who can operate Tutor, administer Keycloak and read identity logs. The work touches the Open edX LMS settings for third-party authentication, the Keycloak realm, clients and mappers, and the network and certificate setup between them. Someone must be comfortable changing Tutor configuration and redeploying the platform, creating clients and mappers in the Keycloak admin console, and tracing a failed login through Keycloak events and LMS logs. Teams without that skill set usually find the hardest part is diagnosing attribute mismatches, which often surface only during a live login attempt. A practical check is to run a short pilot in a non-production environment with one test group before deciding. If the team lacks one of these skills, a fixed-scope engagement can cover the build and hand over documentation that your team can then operate.
What must we provide before an SSO integration with Keycloak starts?
Before work starts, you need to provide access to the identity source and Keycloak, the hostnames for the LMS, Studio and the Keycloak endpoint, the certificates that will be used, a decision on account linking and auto-registration, and a test group of users. Identity source access means an account with rights to read attributes from the directory or existing Keycloak realm, plus the attribute names your organization uses for email, name and any role or program field. Hostnames must be stable, because SAML entity IDs and redirect URIs depend on them. Certificate material and the ownership of its renewal must be agreed in advance. The linking decision says whether learners with existing Open edX accounts are matched by email or must confirm the match, and the auto-registration decision says whether new users are created on first login or pre-provisioned. A test group of users in a non-production environment lets you confirm mappings before production.
How long does a Keycloak SSO integration for Open edX take?
The timeline follows the written scope, so no general duration applies to every organization. Once the protocol, user sources, linking rules and test scope are agreed, the work can be scheduled in phases: environment preparation, Keycloak configuration, Open edX third-party authentication setup, attribute mapping and linking tests, and a pilot with your test group. Each phase depends on the one before it. Delays usually come from waiting on identity source access, certificates or linking decisions more than from the configuration itself. Ask for a written plan that lists each phase, the client inputs each phase needs, and the environments that will be tested before production. Ask who signs off on the pilot results, because your own team's availability for reviews and sign-off is part of the schedule too.
What recurring work follows a Keycloak SSO go-live for Open edX?
Three kinds of work recur: credential rotation, platform and identity upgrades, and user onboarding rules. Client secrets, SAML signing or encryption certificates and service credentials expire or need rotation on a schedule your organization sets. Each rotation touches both Keycloak and the Open edX settings, so it should be planned as a change. Keycloak plans four minor releases a year and a major release every two to three years, and says breaking changes in a minor release will be opt-in, which still requires review before adoption. Open edX supports only its latest named release, so Open edX upgrades follow that cycle. Onboarding rules, such as which groups receive which program access or when accounts are deactivated, also need named owners who review them. Ask any provider whether these items sit inside a support retainer or in a separate handover.
Should we use SAML 2.0 or OAuth2 for Keycloak and Open edX?
Choose based on what your Keycloak clients and your Open edX deployment already support, and on how your directory supplies attributes. Open edX third-party authentication supports SAML 2.0 and OAuth2 providers, and Keycloak supports SAML 2.0 and OpenID Connect along with OAuth 2.0. SAML 2.0 is often the better fit when your organization already runs SAML service providers and wants signed assertions in the browser flow. OAuth2 through OpenID Connect may fit where your other applications already use it. In either case, check which attributes each option delivers for email, name and any program field, because that determines the mapping work. Confirm the Open edX and Tutor versions you run against the current provider documentation before you commit, since the list of supported identity providers is maintained by the Open edX project.
How do we test the Keycloak SSO integration before going live?
Test the full login path in a non-production environment with your test group, covering first login, repeat login, account linking and auto-registration. Include users with missing or changed attributes, users who already have an Open edX account with the same email, a user who is disabled in Keycloak, and a logout followed by a new login. For each case, check the Keycloak event log, the Open edX authentication logs and the resulting account profile. Repeat the tests after any certificate rotation or Tutor upgrade, since those changes often break attribute flows silently. Testing scope is one of the largest cost drivers, so the written scope should list each case, state the environments tested, and say who records and approves the results.
How DeployOpen scopes and delivers the Keycloak SSO integration
DeployOpen plans the Keycloak and Open edX SSO integration as a fixed-scope piece of work agreed in writing before any build starts. The work runs inside your own infrastructure, from the Keycloak realm and client design through the Open edX third-party authentication settings, with documentation and support handed over at the end.
How we scope
- Confirm which Open edX sites, roles and learner or staff groups sign in through Keycloak, and which accounts stay local.
- Agree the protocol choice, SAML 2.0 or OAuth2, against the Open edX provider options and your Keycloak version.
- Record attribute mapping, account linking and auto-registration rules in the written scope before build begins.
How we build
- Configure the Keycloak realm, clients and identity mappers in a non-production environment first, then test the Open edX login flow end to end.
- Set up the Open edX third-party authentication provider settings, with a test plan for linking existing accounts and first-time sign-in.
- Verify failure paths such as expired sessions, missing attributes and disabled Keycloak users before anything reaches production.
How we hand over
- Deliver written configuration records covering realm settings, client definitions, attribute mappings and Open edX provider values.
- Provide runbooks for adding a new identity provider, rotating client secrets and handling account-linking support requests.
- Walk your identity and platform teams through the deployed setup and the acceptance test results before sign-off.
How we support
- Offer ongoing support and Keycloak or Open edX upgrade work as a retainer, scoped separately from the original integration.
- Plan Keycloak upgrade testing around the project's upgrade guidance, including the manual approval mode for operator updates if you use the Operator.
- Confirm with us and your team which Open edX release and Tutor version you run before any SSO change is made in production.
