Setting Up OAuth2-Based SSO in Moodle

OAuth2 in Moodle lets you delegate authentication to an external identity provider. This guide covers finding the correct endpoints, configuring the issuer and user field mappings, troubleshooting callback failures and missing user data, and working around Totara’s email verification requirement for custom services.

Finding the correct OAuth2 endpoints

For Moodle’s OAuth2 login to work, you need three endpoints from your identity provider: authorization_endpoint, token_endpoint, and userinfo_endpoint. IdP admins sometimes hand over a metadata URL rather than the individual endpoints. If the URLs you’ve been given don’t work, check whether they point to an OpenID Connect discovery document (a JSON file at a .well-known/openid-configuration path). That document contains all the endpoints you need.

For example, a Keycloak-based IdP might give you a discovery URL like this:

https://account.example.com/auth/realms/business/.well-known/openid-configuration

Fetching that URL returns a JSON document with all the endpoint URLs already filled in:

{
  "issuer": "https://account.example.com/auth/realms/business",
  "authorization_endpoint": "https://account.example.com/auth/realms/business/protocol/openid-connect/auth",
  "token_endpoint": "https://account.example.com/auth/realms/business/protocol/openid-connect/token",
  "userinfo_endpoint": "https://account.example.com/auth/realms/business/protocol/openid-connect/userinfo",
  "end_session_endpoint": "https://account.example.com/auth/realms/business/protocol/openid-connect/logout",
  "jwks_uri": "https://account.example.com/auth/realms/business/protocol/openid-connect/certs"
}

Copy the individual endpoint values into Moodle’s OAuth 2 service configuration. Note that even a correct endpoint set can still fail if the configured scopes don’t cause the IdP to include username and email in the userinfo response — that’s covered in the field mapping section below.

Why /admin/oauth2callback.php throws invalidsesskey

When Moodle redirects back from the identity provider and the user sees an invalidsesskey error, the problem is not with the authorization code itself. In Moodle’s callback flow, the state parameter carries a local return URL that contains a sesskey. Moodle extracts that sesskey and validates it against the current session. If the check fails, Moodle stores invalidsesskey as the login error and sends the user back to the login page.

This means the error is a session-continuity failure at callback time, not a generic OAuth2 problem. Several things can cause it.

Session cookie not sent on the callback. The most common cause is the browser not sending the Moodle session cookie on the cross-site return from the IdP. Check the SameSite attribute on the PHP session cookie. SameSite=Strict is a common culprit: browsers do not send Strict cookies on cross-site top-level navigations, which is exactly what an OAuth2 callback is. SameSite=Lax allows cookies on top-level navigations and is usually the right setting here.

wwwroot mismatch. If $CFG->wwwroot in config.php does not exactly match the URL in the browser address bar, including protocol and any path prefix, session validation can fail. A common variant is wwwroot set to http while the site is served over https.

Reverse proxy configuration. When Moodle sits behind a load balancer or reverse proxy that terminates SSL, the session may be keyed to a different server address than the one the browser sees. Make sure $CFG->reverseproxy and $CFG->sslproxy are set correctly in config.php to reflect the proxy setup.

Multi-node session storage. If the Moodle application runs on more than one node without shared session storage, the node that handles the callback may not have the session that was created when the login flow started. Shared session storage (database or cache) is required for OAuth2 to work reliably across nodes.

Why Moodle reports that the returned user information does not contain a username and email address

After the token exchange, Moodle calls the userinfo endpoint and tries to map the response fields to its internal user attributes. If it cannot find values for username and email, it shows this error. There are two distinct causes.

The IdP is not returning the expected claims. Some providers return email as “mail” or “email_address”. Some return the username equivalent as “preferred_username”, “upn”, “samaccountname”, or a custom attribute. Decode a sample token or inspect the raw userinfo response to see exactly what field names and values the provider is returning.

The Moodle field mappings do not match. Moodle needs to know which field in the userinfo response corresponds to its internal “username” and “email” fields. For OpenID Connect services, these mappings are often created automatically. For custom OAuth2 services they usually need to be added manually. Go to Site administration > Server > OAuth 2 services, open the service, and click “Configure user field mappings”.

A typical mapping table for a Microsoft Entra ID or ADFS provider might look like this:

Internal field name   | External field name (from userinfo response)
----------------------|---------------------------------------------
username              | preferred_username   (or: upn, samaccountname)
email                 | mail                 (or: email)
firstname             | given_name
lastname              | family_name

Mapping firstname and lastname is not required for login, but without them Moodle may force a profile-completion step after the first login.

How to verify the setup before testing login

Moodle includes a built-in test action that is worth using before attempting a full login flow. Go to Site administration > Plugins > Authentication > Manage authentication, find the OAuth 2 row, and click “Test settings”. This checks whether Moodle can reach the configured endpoints and returns the raw userinfo response from the provider.

Use the test output to confirm two things independently: first, that the provider is actually returning username and email claims in its userinfo response; and second, that the field names in those claims match the mappings configured in Moodle. Separating those two checks makes it much easier to diagnose whether a login failure is an endpoint problem, a mapping problem, or a callback session problem.

Issue with Email Verification in OAuth2 for Custom Services in Totara

Description of the Issue

When configuring OAuth2-based SSO in Totara, administrators may encounter an issue where the system enforces email verification for custom OAuth2 providers. Unlike predefined providers such as Google, Microsoft, and Facebook, custom services do not offer the option to disable the "Require email verification" setting in the user interface. This behavior results in user accounts being marked as "pending email confirmation," preventing successful logins.

Observations

• This restriction does not apply to predefined OAuth2 services, where the "Require email verification" setting can be toggled.
• In Moodle 4.5, this limitation has been addressed, allowing custom OAuth2 providers to disable email verification.
• The issue stems from a default database configuration that requires email verification for custom services.

Example Scenario

Upon authentication via a custom OAuth2 provider:

• A record is created in the oauth2_linked_login table with confirmed set to 0.
• Users remain unable to log in until email verification is completed.

Suggested Remedy by Totara

Totara HQ has provided an unsupported workaround involving a direct database query. The query modifies the oauth2_issuer table to disable the email verification requirement for a specific OAuth2 service:

UPDATE [prefix]_oauth2_issuer
SET requireconfirmation = 0
WHERE name = 'name_of_issuer_here';

Important Notes:

• Replace [prefix] with the database prefix used in the Totara installation (e.g., ttr or mdl).
• Ensure that the name_of_issuer_here matches the exact name of the custom OAuth2 service.

Risks and Limitations

• Totara does not support this approach as it bypasses a core security measure.
• Directly modifying the database introduces a risk of unintended consequences and may compromise system security.
• Any issues arising from this change will not be supported by Totara HQ.

Recommendations

• Evaluate whether disabling email verification is essential for the specific use case.
• If email verification must be disabled, proceed with the query cautiously, ensuring a backup of the database before execution.
• Report the requirement to Totara HQ to encourage future support for this feature in the user interface.