This guide is written by the team that builds Casdoor and describes the standards as published (listed under Sources), with notes on how Casdoor implements them as of November 2, 2026. Spotted a mistake? Tell us.
Moodle has an OAuth 2 authentication plugin that lets users sign in through an external identity provider. It works with Casdoor, Keycloak, Microsoft Entra ID, Google and any other provider that exposes standard OAuth 2 / OpenID Connect endpoints.
For schools and universities, this is the difference between a separate Moodle password for every course site and one account that also works for email, the library and the rest of the campus systems.
What you need
- A Moodle site where you can reach Site administration.
- An identity provider application with a client ID and secret.
- HTTPS on both sides; the callback carries an authorization code, and providers should reject an HTTP redirect.
Step 1: create the application in the IdP
Create an application for Moodle and add the callback URL:
https://<moodle-host>/admin/oauth2callback.php
Copy the client ID and client secret. If the provider asks for a scope, request at least openid, profile and email. The profile and email claims are what Moodle uses to fill in the user's name and address.
Step 2: create the OAuth 2 service in Moodle
In Moodle, open Site administration → Server → OAuth 2 services and create a new service.
Fill in:
- Name. A label users will recognize, such as the campus IdP or Casdoor.
- Client ID and client secret. From the application you created.
- Service base URL. The issuer URL, for example https://door.example.com.
- Endpoints. The authorization, token and userinfo URLs. Many Moodle versions can read them from the discovery document; if not, copy them from /.well-known/openid-configuration.
- Scopes. openid profile email, unless the provider requires a different set.
Save the service. Moodle now knows how to talk to the provider, but it does not yet create users from it.
Step 3: map the user fields
Still in the OAuth 2 service, open the user field mapping. Moodle maps claims from the provider to its own user fields:
| Moodle field | Typical claim | Notes |
|---|---|---|
| Username | preferred_username or name | Must be unique in Moodle |
| Moodle requires an email address | ||
| First name | given_name or name | Depends on the provider's claims |
| Last name | family_name | Can be left blank if the provider has no separate family name |
| City, country, language | locale, address or custom claims | Optional |
The exact claim names depend on the provider. With Casdoor's default JWT token format, the ID token carries name (the username), displayName and email; map the name fields to those claims. With JWT-Standard, the standard claims preferred_username, given_name and family_name are available.
If the provider's claims do not line up, change the mapping, not the provider. Moodle will happily create a user with a blank first name if the claim is missing.
Lock the fields you own
If the identity provider is the source of truth, lock the email and name fields in the mapping. Otherwise a user can change their Moodle email to something that no longer matches the IdP, and the next sign-in may create a duplicate account or fail.
Step 4: enable the plugin
Go to Site administration → Plugins → Authentication → Manage authentication and enable OAuth 2. The Moodle login page should now show the provider as a sign-in option.
If you want OAuth 2 to be the primary method, disable or restrict the manual account login, but keep at least one local administrator account as a fallback. Locking every administrator out of Moodle is a common self-inflicted outage.
Step 5: test
Open Moodle in a private window, choose the OAuth 2 provider, sign in at the identity provider, and confirm that:
- Moodle created or matched the user.
- The username, email and name are correct.
- The user lands in the expected course or dashboard.
If the user is created but has no courses, that is an enrolment issue, not an SSO issue. SSO authenticates the user; Moodle's enrolment methods decide what they can see.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Redirect URI mismatch | The application's redirect URL must be exactly https:// |
| Moodle says the email is missing | The provider did not release the email claim, or the mapping points at the wrong claim. |
| A duplicate account is created | The username or email claim changed, or the fields are not locked. |
| Login loops | The service base URL or issuer does not match; check the discovery document. |
| The provider does not appear on the login page | The OAuth 2 plugin is not enabled, or the service is not available to the user's context. |
| Users sign in but see no courses | SSO worked; check enrolment methods and cohort sync. |
FAQ
Does Moodle support SAML? Moodle has SAML plugins, but OAuth 2 / OIDC is the simpler path if your provider supports it. If the provider only speaks SAML, use a SAML plugin or a broker that exposes OIDC.
Can Moodle create users automatically? Yes. The OAuth 2 plugin creates a user on first sign-in if the account does not exist. Review the settings for self-registration and email confirmation before enabling it for a large audience.
Can I restrict sign-in to one email domain? Moodle's OAuth 2 settings and the provider's application policy can both restrict access. The cleanest place is the identity provider: only issue tokens to users who should have Moodle access.
Does Moodle sync groups from the IdP? Not through the OAuth 2 plugin alone. Use cohorts, enrolment plugins or a separate sync for group membership. SSO answers "who is this user", not "which courses are they in".
If you need one identity provider for Moodle and the rest of a school's systems, Casdoor supports OIDC, SAML, CAS, LDAP and SCIM. Casdoor Cloud starts at $6.67/month billed yearly for a dedicated instance. See the Casdoor Moodle guide for the exact fields.
Sources
- Moodle OAuth 2 authentication
- Moodle OAuth 2 services
- Casdoor Moodle integration
- OpenID Connect Core 1.0
Product names are trademarks of their respective owners.