How does Keycloak and Moodle SSO integration work?
Keycloak issues the login, and Moodle trusts it and creates or matches the account. When a learner or staff member opens Moodle, Moodle redirects them to Keycloak, which authenticates them and returns a signed response. Moodle checks that response, then either signs the person into an existing account or creates a new one, and starts its own session. Moodle never sees the password, and Keycloak holds no course data. This section covers the integration only: the client registration in Keycloak, the Moodle authentication settings, and the rules that decide how accounts are matched. Installing and hardening Keycloak is separate work and is not described here.
Moodle core includes an OAuth 2 authentication plugin that can be pointed at a custom issuer, so Keycloak's OpenID Connect endpoints can act as the identity source. The alternative is the SAML2 Single sign on plugin (auth_saml2), maintained by Catalyst IT, which provides SAML 2.0 sign-on and creates users using field mapping configured in Moodle. Both paths are documented as core or community options, but the details of custom issuer handling and supported client settings can differ between Moodle versions. Confirm the exact method against the Moodle version you run before designing anything else. The plugin directory listing for auth_saml2 states support for Moodle 2.7 through 5.1, so a site on a later release must verify compatibility before choosing it.
Decide which Keycloak attributes feed Moodle's profile fields before the first test login. At minimum, username, email address, first name and last name must map consistently, because Moodle uses these values to match an incoming login to an existing account. Decide whether Moodle creates accounts on first login or only accepts users who already exist, and what happens when a Keycloak email address matches an account created by hand. Duplicate accounts are a common support problem after go-live, and they often trace back to inconsistent identifiers rather than to the protocol itself. Choose one stable identifier, such as the Keycloak user ID or a verified email address, and document the decision with the people who will answer account requests.
Keycloak groups can represent cohorts or staff roles, but do not assume that either Moodle path synchronizes group membership into cohorts or roles automatically. Confirm whether the chosen method passes group or role claims, and whether Moodle needs a plugin or a scheduled sync to enrol users into cohorts. Plan the mapping as a written table: which Keycloak group grants which Moodle system or course role, who approves changes, who removes access when someone leaves, and who owns the mapping after handover. Test with a learner, a teacher and an administrator account. Also confirm that a user disabled in Keycloak cannot sign in to Moodle once their existing session ends.
What Keycloak and Moodle versions must be in place first
Keycloak and Moodle each have version, database and certificate requirements that must line up before any SSO configuration starts. The cards below cover the Moodle and Keycloak releases, the server stack each one needs, and the access and plugin checks that decide whether the integration can be built and tested.
Moodle target and upgrade starting point
Confirm which Moodle release you are integrating against, 5.1 or 5.3, and whether your current site can reach it directly. Moodle 5.1 requires sites to be on Moodle 4.2.3 or later, and Moodle 5.3 requires Moodle 4.4 or later. An older site needs intermediate upgrades before any SSO work begins, so check the installed version and the upgrade path in the Moodle release notes before you commit to a target.
Moodle PHP and database requirements
Moodle 5.1 requires 64-bit PHP 8.2 or later, with 8.3 and 8.4 supported, and Moodle 5.3 requires 64-bit PHP 8.3 or later, with 8.4 supported. Database minimums also differ between the two releases, including PostgreSQL 15 for 5.1 and PostgreSQL 17 for 5.3. Check the PHP and database versions on the Moodle server and the database host, because an SSO integration cannot be tested on a stack that fails the core install checks.
Keycloak release and production database
Keycloak 26.8.1 is the current release, published October 13, 2026, so plan the identity provider around it or confirm your chosen build. Production deployments need a supported database, and PostgreSQL 14 through 18 is on the supported list. The development file database is for testing only. Confirm the Keycloak version and the database version together, and check the upgrading guide before you pick a version that differs from the current release.
HTTPS with valid certificates on both ends
Keycloak and Moodle both need HTTPS endpoints with certificates that the other side trusts. Browser redirects, token exchanges and metadata downloads fail when a certificate chain is incomplete or self-signed without a trust path. Confirm the hostnames, certificate authority chain and renewal process for each system, and test the chain from the Moodle server itself, not only from a workstation browser.
Reachable realm endpoint and admin account
Moodle's server, not only user browsers, must reach the Keycloak realm endpoint, including the discovery or metadata URL for the realm. Firewalls, proxies and split DNS are common causes of failure here. You also need a Keycloak admin account with rights to create the client, mappers and groups that the integration will use. Ask who holds that account and how its access is audited before the build starts.
auth_saml2 release for the target Moodle version
If you use SAML 2.0, the SAML2 Single sign on plugin (auth_saml2) by Catalyst IT is the common choice, and its plugin directory listing covers Moodle 2.7 through 5.1. Moodle 5.3 falls outside that listed range, so confirm with the plugin maintainer that a release supports 5.3 before you plan around it. Pick the plugin release that matches your Moodle version, and record that decision alongside the Keycloak version.
Choosing OAuth 2 or the SAML2 plugin for Keycloak
The core decision is which protocol Keycloak will speak to Moodle. Moodle's core OAuth 2 authentication lets Keycloak act as an OpenID Connect issuer, and it needs the Keycloak realm metadata, a client ID and secret for the Moodle client, and a redirect URI that matches the Moodle site exactly. The auth_saml2 plugin, the SAML2 Single sign on plugin maintained by Catalyst IT, instead exchanges SAML metadata and consumes attribute assertions. Choose based on what your organization already standardizes on. If your other applications sign in through OpenID Connect, the OAuth 2 path keeps one protocol and one set of Keycloak client conventions. If your identity estate is built on SAML 2.0 service providers, the plugin fits better and avoids creating a second model for Moodle alone.
Protocol preference is rarely the only driver. Check the Moodle version you plan to run before committing. Moodle ships major releases in April and October, and the OAuth 2 issuer options and the plugin's listed compatibility can change between releases. The auth_saml2 plugin's directory listing states support from Moodle 2.7 through 5.1, which is a fact to re-verify against your target release, since the directory does not guarantee support for the version you will run in the future. Confirm with the plugin's listing and your Moodle version's documentation which OAuth 2 issuer types are available as configured services in your target release, and whether a generic custom OpenID Connect issuer is supported without extra work.
Maintenance is the driver teams most often underestimate. Core OAuth 2 authentication is maintained as part of Moodle core, so it moves with each upgrade and needs no third-party code review. The auth_saml2 plugin is a community plugin with its own release cycle, so each Moodle upgrade needs a check that the plugin version matches the new release before the upgrade window opens. Ask who will test the plugin on upgrade, whether that is your team, DeployOpen under a retainer, or the plugin maintainer, and write that owner into your runbook.
Logout and group handling differ, so test both before choosing. Single logout behavior depends on what each side supports and how sessions are configured in Keycloak and Moodle, so confirm whether a Keycloak logout reaches Moodle sessions in your setup, and document the gap if it does not. For group claims, check how each path passes group or role information into Moodle, since mapping Keycloak groups to Moodle cohorts or roles may require a specific claim or attribute to be present in the token or assertion. Build a short test matrix covering sign-in, attribute mapping, group-to-cohort assignment, and logout from both Moodle and Keycloak before you decide.
How to configure the Keycloak to Moodle sign-in in sequence
This sequence takes Moodle from a local login page to Keycloak sign-in in a controlled order. Each step ends with a check you can run, so a failure is caught on a pilot account before every user is affected.
Confirm or create the Keycloak realm
Identity administrators either confirm that an existing Keycloak realm is the right home for Moodle users or create a dedicated realm for the Moodle integration. A dedicated realm keeps Moodle client settings, scopes and test accounts separate from other applications. Create at least one pilot user in the realm with a known email address and a complete name, because those attributes drive the mapping later. The step is done when the pilot user can sign in to the Keycloak account console within that realm.
Register Moodle as a Keycloak client
The Keycloak administrator creates a client for Moodle using the client ID and client authentication settings your team agrees on. Copy the redirect URI exactly from the Moodle OAuth 2 service configuration in your Moodle version, because a single character difference will block sign-in. Restrict the valid redirect URIs to your Moodle site only. The check: a token request made with an unregistered client ID or a mismatched redirect URI should be rejected by Keycloak.
Set client scopes and mappers
Configure the Moodle client so that Keycloak releases the claims Moodle needs: email, given name, family name and a stable username. Map these from Keycloak user attributes into the ID token or userinfo response, and confirm that the claim names match what Moodle expects in its field mapping. Keep the claim set minimal to what Moodle uses. The check: sign in as the pilot user, call the userinfo endpoint or inspect the ID token, and confirm each claim is present with the expected value.
Configure the Moodle authentication plugin
On the Moodle side, the administrator either sets up a custom OAuth 2 issuer that points to the Keycloak realm's discovery document, then enters the client ID and client secret, or installs and configures the SAML2 single sign-on plugin with the Keycloak SAML metadata if your organization uses SAML 2.0. Confirm the plugin's compatibility with your Moodle version before installation. The check: the Moodle login page displays a Keycloak sign-in option, and clicking it redirects to the Keycloak login form.
Set field mapping and account creation rules
Map the Keycloak claims to Moodle profile fields, including username, email, first name and last name, and decide whether Moodle creates an account automatically on first sign-in. Decide how an existing Moodle account with the same email address is matched, and document that rule before pilot testing, since duplicate accounts are hard to clean up later. Keep manual login available for break-glass administrator accounts. The check: the pilot user's first sign-in creates or matches the expected account, and the Moodle profile shows the mapped values.
Test the sign-in with a pilot account
Run a controlled test with a small group of pilot accounts that cover typical cases: a new user, an existing Moodle user, a user with a changed email address and a user who has been disabled in Keycloak. Record the outcome of each case, including the error messages users see. Repeat sign-in after logout and after the Keycloak session expires to confirm the round trip behaves as expected. The check: every pilot case produces the expected result, and the disabled account is refused at Keycloak before Moodle grants access.
Enable sign-in for all users
After the pilot results are reviewed and signed off, the Moodle administrator makes Keycloak the default sign-in method and communicates the change to course staff and learners with support instructions. Keep the break-glass administrator path documented and tested so that a Keycloak outage does not lock everyone out. Monitor Moodle and Keycloak logs for failed logins during the first days after the switch. The check: a sample of ordinary users can sign in through Keycloak, and the failure rate in the logs is reviewed and explained.
Which Keycloak attributes map to which Moodle fields
This table compares each Keycloak claim or attribute with the Moodle user field it feeds, whether the mapping is required, and the rule that governs it. Read each row as a decision you confirm before go-live, because the usable claims depend on the client scopes and mappers configured in your realm. The main takeaway is that identity, email and the stable subject identifier must be settled first, since changing them later creates duplicate or orphaned Moodle accounts.
| Keycloak claim or attribute | Moodle field | Required or optional | Rule |
|---|---|---|---|
| username or preferred_username | Moodle username | Required | Lowercase only, using Moodle's allowed character set. Confirm which claim your client emits and normalize values that Keycloak allows but Moodle rejects. |
| Moodle email | Required | Must be unique per Moodle user. Decide how duplicate addresses are handled before enabling account creation, and confirm the claim is present in the token. | |
| given_name | Moodle firstname | Required | Map from the profile scope. Confirm the claim is released to the client, since missing values can block account creation. |
| family_name | Moodle lastname | Required | Map from the profile scope. Confirm handling for users with a single legal name or no family name. |
| sub (stable subject identifier) | External identity link (issuer and subject pair) | Required | Use as the permanent link to the Moodle account. Do not rely on username or email for matching, because both can change. |
| groups or roles claims | Cohort and role assignment | Optional | Not mapped to profile fields. Assignment logic is covered in the group section of this page. |
How account creation and matching should work for Keycloak users
The first decision is whether Moodle creates an account the first time a Keycloak user signs in, links that sign-in to an account that already exists, or refuses sign-in for anyone without a prepared account. Each path has different consequences. Automatic creation suits a population where every signed-in person should have access, such as all staff. Linking suits sites that already hold manual or LDAP accounts with enrolments and grade history. Blocking new accounts suits sites where enrolment is controlled in another system. Decide the rule for each user group, record it in the written scope before build starts, and treat it as a design input. These rules set how many login problems reach your help desk after go-live.
Matching on email alone is the most common shortcut and the most fragile. Addresses change when people marry, change names or move between institutions, and shared or role mailboxes can appear on several people's records. If Moodle links a sign-in to whichever account holds the same email, a changed address creates a duplicate account, and a shared address can attach one person's grades to another. The safer design is a stable identifier. Keycloak's internal user ID, which appears as the subject claim in OpenID Connect or as the NameID in SAML, can be stored against the Moodle account. Confirm which identifier each Keycloak client sends, whether it stays constant when a user is recreated, and how it behaves for users federated from LDAP.
Existing accounts created before SSO need a deliberate plan. Staff and students who already have manual or LDAP accounts, with enrolments and submissions, should be linked to their Keycloak identity instead of being duplicated. Decide whether linking happens in bulk before cutover or on each user's first sign-in, who owns the exception list, and what happens when no match is found. Test with a sample that includes duplicate names, changed emails, and the same username appearing in two sources. Document how the help desk resolves each exception, so that records are not edited by hand in production.
How to harden the Keycloak to Moodle sign-in path
Signing Moodle users in through Keycloak creates a trust path that both systems must protect. The cards below cover what to configure in Keycloak, what to limit inside Moodle, and what each side should log so that a failure on one side is visible on the other.
Confidential client and exact redirect URIs
Register Moodle in Keycloak as a confidential client that authenticates with a client secret. Store the secret in your secrets manager, set a rotation schedule, and update Keycloak and Moodle together when you rotate it. List each Moodle callback URL exactly, including scheme, host and path, and avoid wildcards and broad web origins. Test that a redirect to any other path is rejected.
TLS and proxy-aware hostname settings
Serve Keycloak and Moodle only over TLS, with certificates that clients trust and no mixed content. For Keycloak in production, set an explicit frontend hostname so the issuer and endpoint URLs in the discovery document match what Moodle is configured to use. Allow forwarded headers only from your load balancer or reverse proxy, then confirm the proxy settings against your deployment, because a mismatch produces wrong issuer or redirect values.
Token lifetimes and session settings
Keep access and ID token lifetimes short, and set Keycloak's SSO session idle and maximum limits on purpose, since a Moodle session can outlast the Keycloak session that created it. Confirm that Keycloak issues session cookies with the Secure attribute, and check that the SameSite setting works with the browser redirects Moodle uses. Test logout in both directions and record the values you chose and the reason for each.
Brute-force protection and MFA in Keycloak
Brute-force detection, account lockout and MFA policy are configured in Keycloak's realm settings and authentication flows, and Moodle does not enforce them. Confirm that users starting from the Moodle sign-in page meet the same MFA requirement as users starting from any other application. Disable or restrict local Moodle password logins for accounts that must use Keycloak, and test a locked account from the Moodle sign-in page.
Scopes, claims and Moodle plugin administrators
Request only the client scopes Moodle needs, and map only the claims that drive account creation, field mapping and cohort or role assignment. Remove mappers that send unused attributes such as internal group paths or personal data, because anything Keycloak sends becomes data Moodle stores. Limit changes to the authentication plugin settings in Moodle to a named administrator group, since a changed issuer, client ID or field mapping can alter who gets in and what they receive.
Authentication event logging on both sides
Enable Keycloak event logging for login, login error, logout and token events, and forward those events to the log platform you already run. On the Moodle side, keep authentication and login logs for the period your review cycle requires. Correlate events by username, timestamp and session identifier so a failed Moodle sign-in can be traced to its Keycloak attempt. Test the chain with a deliberate failed sign-in before go-live.
Why Keycloak Moodle SSO logins fail and how to fix them
This table lists the failures teams most often see when Keycloak and Moodle sign-in stops working, with the likely cause, the fix and the first check to run. Most of these faults show up in one comparison between two values, so start with the check that matches your symptom and work down only if it passes.
| Symptom | Likely cause | Fix | First check to run |
|---|---|---|---|
| Keycloak shows an invalid redirect_uri error after the user signs in | The valid redirect URI on the Keycloak client does not exactly match the callback URL Moodle sends, including scheme, host, path or trailing slash | Copy the callback URL from the Moodle OAuth 2 service page into the client's valid redirect URIs and remove wildcards you do not need | Compare the redirect_uri in the error URL with the valid redirect URIs list on the Keycloak client |
| Moodle returns to the login page with an error after Keycloak authenticates the user | The client secret was regenerated in Keycloak, or the copied value includes extra spaces, so the token request is rejected | Copy the current secret from the client's Credentials tab, paste it into the Moodle service without spaces, save and test | Confirm the client ID and secret in Moodle match the Keycloak client's Credentials tab |
| Moodle logs show certificate verification errors when contacting Keycloak | Keycloak uses an internal or private certificate authority that is missing from the trust store used by Moodle's PHP and web server | Install the CA chain in the Moodle server's trust store, restart the web and PHP services and retest. Do not turn off certificate checks | Test the TLS chain from the Moodle server to the Keycloak discovery URL |
| Logins fail with messages that a token or SAML assertion is not yet valid or has expired | Clocks on the Keycloak, Moodle web and Moodle cron hosts differ enough to fail time-based checks such as issued-at, not-before and expiry | Sync all servers to a reliable time source, correct drift and retest before changing any SSO settings | Compare UTC time on the Keycloak host and each Moodle web and cron host |
| A user signs in and gets a duplicate account, or is told the account cannot be linked | An existing Moodle account or another Keycloak user has the same email address, and the matching rule picks the wrong account or none | Choose a stable matching key, merge or clean duplicate Moodle accounts and enforce unique email addresses in Keycloak where your policy requires it | Search both systems for the email and compare usernames and the external identifier on each account |
| Users sign in, but name, email or group fields are blank or account creation is refused | A client scope or protocol mapper was removed, renamed or not assigned to the Moodle client, so the claim is missing from the token or assertion | Restore the mapper or scope on the client, then set the Moodle field mapping to the exact claim name the token sends | Run Client scopes, Evaluate on the Moodle client for a test user and list the claims returned |
| After upgrading to Moodle 5.1 or later, the site shows directory listings, 404 errors or a broken login page | The web server document root still points to the main Moodle folder instead of the new public directory required from Moodle 5.1 | Point the document root to the public directory, reload the web server and check the login URL and the admin pages | Check the document root in the web server configuration against the public directory in the installation |
| SAML logins suddenly fail with invalid signature errors after a Keycloak certificate renewal | The Moodle SAML2 plugin still holds the previous IdP signing certificate after the realm signing key was renewed | Download the current signing certificate from the Keycloak SAML descriptor, update the certificate in the plugin settings and test a login | Compare the certificate fingerprint in the Keycloak SAML descriptor with the one stored in the Moodle plugin |
What does Keycloak and Moodle SSO integration cost and require?
What does a Keycloak and Moodle SSO integration cost?
There is no list price. The cost follows from a written scope, and DeployOpen does not publish rates. Most of the cost is skilled time for design, configuration, testing and documentation, so the scope sets the total. Items that raise it include the number of identity sources, a group model that must map to Moodle cohorts and roles, existing Moodle accounts that need matching rules, the depth of testing and the upgrade plan. Ask each quote to separate one-time build work from recurring items such as support or upgrades, which are available as retainers. Also ask which Moodle and Keycloak versions the quote assumes, since a version change can change the work.
What drives the effort in a Keycloak and Moodle SSO integration?
The main drivers are the choices that change how much design, configuration and testing is needed.
- Protocol choice: OAuth 2 settings and SAML 2.0 metadata and assertions involve different configuration and different checks.
- Number of identity sources: each additional source multiplies attribute mapping and account creation rules.
- Group model: this decides how Keycloak groups feed Moodle cohorts and roles, and it is often the largest design task.
- Existing accounts: matching rules are needed so the same person is not created twice.
- Testing scope: this covers how many user types and course roles are checked.
- Upgrade plan: this sets how the integration is retested after Moodle and Keycloak releases.
Each driver should appear as a line item in the written scope so you can see what the effort covers.
Can our own team build Keycloak and Moodle SSO without a partner?
Yes, if your team already administers both Keycloak and Moodle and has a test environment. The work touches Keycloak realms and clients, attribute mappings, Moodle authentication settings, account creation rules and cohort or role sync. One or two people need to be comfortable in both admin consoles and able to read Moodle logs when a login fails. A staging Moodle is essential. Without one, testing happens against real user accounts, which is the main avoidable risk. Teams that have strong Keycloak skills but limited Moodle experience often bring in a partner for the group model and the Moodle side only, and keep the rest in-house.
How long does a Keycloak and Moodle SSO integration take?
The duration depends on scope, and no single timeline applies to every integration. A single identity source, one protocol and a simple group model is a smaller job than several sources feeding cohorts and roles across many courses. Testing depth and the upgrade plan add time. Ask for the schedule in the written scope, with milestones tied to staging review and sign-off. Also ask what waits on your side, such as admin access approvals, the availability of test users and the decision on the group model, because delays in those inputs often move the schedule more than the build itself.
What does DeployOpen need from our team before work starts?
Four things are needed to start.
- Keycloak admin access: an administrator account with rights to create and change realms, clients and mappers in the environment that will be used.
- A staging Moodle: a test copy of the Moodle site, close to production in version and configuration, where login and sync can be tested safely.
- A named owner for group rules: one person who can decide which Keycloak groups map to which Moodle cohorts and roles.
- Test users: a set of accounts covering each user type and course role, including people who already have Moodle accounts.
If your organization requires a change window or an approval step for production, confirm it at scoping so it appears in the schedule.
Should we use OAuth 2 or SAML 2.0 for Moodle sign-in?
Moodle core includes OAuth 2 authentication, which can be pointed at a custom issuer such as Keycloak. The community SAML2 Single sign on plugin (auth_saml2), maintained by Catalyst IT, provides SAML 2.0. Choose OAuth 2 when OpenID Connect fits your Keycloak client model and you want fewer third-party components. Choose SAML 2.0 when your organization already runs SAML for other applications or your policy requires it. Confirm the plugin's listed Moodle support against your target version before deciding, since the listed support range ends at Moodle 5.1 at the time of writing, and check it again before any project starts.
How does DeployOpen scope the integration before work starts?
Most engagements are fixed-scope, and the scope, deliverables and timelines are agreed in writing before work begins. The quote follows from that document. Expect it to list the protocol, identity sources, attribute mapping, account creation rules, group-to-cohort and role rules, test cases and the environments involved. Check the exclusions carefully. Items such as additional authentication methods, custom Moodle plugins and post-go-live support may fall outside the build and be offered as a separate retainer. A clear exclusions list makes it easier to compare quotes from different providers.
What changes for SSO when we upgrade Moodle or Keycloak?
Both platforms change, and the integration needs a retest after each change. Moodle major releases list their own PHP and database requirements, and from Moodle 5.1 the web server document root must point to the new /public directory, otherwise the site may show directory listings or errors. Keycloak plans four minor releases a year and says breaking changes in a minor release will be opt-in, but you still need to confirm your configuration after each upgrade. Ask whether the quote includes a test pass on staging for each upgrade, or whether that work is a recurring retainer item.
How DeployOpen scopes and delivers the Keycloak and Moodle SSO integration
DeployOpen plans and delivers the Keycloak and Moodle sign-in path inside infrastructure you control, covering the Keycloak realm, the Moodle authentication method, attribute mapping and group-driven enrolment. Engagements are fixed-scope, so the decisions on protocol, account rules and cohort mapping are agreed in writing before the build starts.
How we scope
- Confirm the Moodle version, PHP and database versions, and the web server document root before choosing an authentication method.
- Choose between Moodle's core OAuth 2 authentication with a custom issuer and the SAML2 plugin, based on your Keycloak client setup and policy.
- Document which Keycloak attributes and groups map to Moodle fields, cohorts and roles, and agree account creation rules in the written scope.
How we build
- Configure the Keycloak realm, clients, protocol mappers and group structure in a non-production environment first.
- Set up the Moodle authentication method, field mapping and account creation rules, then test with sample users from each identity group.
- Test sign-in, logout, account updates and cohort assignment for each role, and record the results against the agreed scope.
How we hand over
- Deliver written configuration records for the Keycloak client, Moodle settings, mappings and group-to-cohort rules.
- Walk your administrators through the runbook covering new groups, certificate or secret rotation and troubleshooting failed logins.
- Provide a checklist for verifying the integration after each Moodle and Keycloak upgrade, including the minimum versions you confirmed.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so the integration can be re-checked as either platform changes.
- Plan re-testing of the Moodle authentication plugin against each Moodle upgrade, since plugin support ranges change by release.
- Plan Keycloak upgrades with a manual approval step for operator updates and confirm the Keycloak release notes before changing claims or clients.
