Moodle SSO with MojoAuth

Connect your Moodle site to MojoAuth using SAML 2.0 and the community SAML2 authentication plugin (auth_saml2). MojoAuth acts as the Identity Provider (IdP); Moodle acts as the Service Provider (SP). Once configured, Moodle shows an SSO login button alongside (or instead of) its normal manual login form, and users can sign in via SP-initiated login (from Moodle) or IdP-initiated login (from your MojoAuth-hosted login page).

How it works

Prerequisites

• A MojoAuth project (test or live) with admin access to Developers → Applications.
• A Moodle site (self-hosted or Moodle Cloud) with Site administration access, and permission to install plugins (self-hosted) or request them (Moodle Cloud/hosted environments).
• The SAML2 authentication plugin (auth_saml2) installed — it is not part of Moodle core and does not ship enabled by default.
• Decide which Moodle field will match incoming users — email or username — and confirm existing Moodle accounts populate that field consistently.

Step 1 — Create the MojoAuth SAML connection

1. In the MojoAuth dashboard, go to Developers → Applications → New Application → SAML 2.0 SSO.
2. Enter a connection name (e.g. Moodle – Production) and click Create connection. This creates a draft connection and auto-issues a signing certificate.
3. Leave this tab open — you'll come back to copy the IdP metadata URL and, later, paste Moodle's SP details.

See SAML SSO Connections for the full concept walkthrough.

Step 2 — Install and configure the SAML2 plugin in Moodle

{BASE}/saml/{projectId}/sps/{spId}/metadata

https://<moodle>/auth/saml2/sp/metadata.php

Step 3 — Give Moodle's SP details back to MojoAuth

Back on the MojoAuth SAML connection page:

1. Use Import from metadata and paste Moodle's SP metadata URL:

   https://<moodle>/auth/saml2/sp/metadata.php
   MojoAuth fetches it and auto-fills the SP Entity ID and ACS URL.
2. If your Moodle server isn't reachable from MojoAuth, choose Manual configuration instead and enter:
   • SP Entity ID: https://<moodle>/auth/saml2/sp/metadata.php (or the custom entity ID shown on the SAML2 settings page, if you set one)
   • ACS URL: https://<moodle>/auth/saml2/sp/saml2-acs.php/<moodle>
3. Set NameID format to emailAddress if Moodle will match users on email, or unspecified/ persistent if matching on username — this must agree with the field/attribute used to match users you configure in Moodle (Step 4).
4. Click Save.

Step 4 — Attribute mapping and user matching

The SAML2 plugin settings page has a "Mapping IdP to Moodle" section where you map incoming SAML attributes to Moodle profile fields, plus a setting for which field identifies the user (matched against the SAML NameID or a mapped attribute) — typically email or username.

Configure on the MojoAuth connection's Attribute mappings section, and in Moodle:

• On the SAML2 settings page, set the "Field/attribute used to match users" (or equivalent user matching setting) to email, and set the connection's NameID format to emailAddress with source: email mapped to the subject — this is the simplest setup for most sites.
• If matching on username instead, map source: identifier (or userId, depending on your directory) to the NameID, and set NameID format to unspecified or persistent.
• Add the email, firstname, lastname attribute rows above and map them in the "Mapping IdP to Moodle" section so Moodle can populate (and, on later logins, refresh) the profile.
• To let Moodle create accounts automatically for first-time SSO users, enable the plugin's auto-create users setting (JIT provisioning). Without it, a matching Moodle account must already exist before SSO login will succeed.

Step 5 — Enable the auth method and test

1. Back on Site administration → Plugins → Authentication → Manage authentication, find SAML2 in the list and click the eye icon to enable it. Confirm it's enabled and, if desired, drag it above Manual accounts and other methods in the display order.
2. Visit your Moodle login page — you should now see an SSO button (commonly labelled with your IdP name or "Log in via SAML2") in addition to the manual username/password form.
3. Use the plugin's built-in "Test settings" tool (on the SAML2 settings page) to run an SP-initiated test SAML exchange against MojoAuth and confirm the metadata, endpoints, and certificate are wired up correctly before testing with a live user.
4. From the MojoAuth connection page, use Test SSO to run an IdP-initiated login and confirm a valid signed assertion reaches Moodle's ACS URL.
5. Test an end-to-end login with a non-admin test account in a private/incognito browser window, keeping your own admin session on manual login until you've confirmed the flow works.

Troubleshooting

Metadata import fails or shows stale values The SAML2 plugin caches metadata it fetches from the IdP metadata URL. If you rotate MojoAuth's signing certificate or change endpoints, return to Site administration → Plugins → Authentication → SAML2 and re-save (or re-enter) the "IdP metadata xml OR public xml URL" field to force a refresh — Moodle does not always poll automatically.

"User not found" / account not matched on login The field/attribute used to match users on the SAML2 settings page doesn't line up with what MojoAuth sends in the NameID or mapped attribute. Confirm the connection's NameID format and mapped source (Step 4) correspond to a real, populated value (email or username) on an existing Moodle user, or enable auto-create users if you want new accounts provisioned automatically.

Duplicate/conflicting email errors during account matching Moodle enforces unique emails per account by default. If two Moodle users share (or would share) an email address, matching fails or creates a conflict. Check allowaccountssameemail under Site administration → Users → Permissions → User policies, and clean up duplicate accounts before enabling SSO broadly.

Certificate / signature validation errors The X.509 certificate Moodle has on file for MojoAuth is stale (certificates rotate periodically) or was entered incorrectly. Re-import the IdP metadata URL to refresh it automatically, or re-copy the PEM from Copy PEM on the MojoAuth connection page and paste it into the manual certificate field.

ACS URL / Entity ID mismatch ("Invalid Destination" or audience errors) The SP Entity ID or ACS URL saved on the MojoAuth connection doesn't exactly match what https://<moodle>/auth/saml2/sp/metadata.php publishes. Re-import Moodle's SP metadata URL on the MojoAuth connection page rather than typing the values by hand, since the ACS path includes your site's exact hostname.

"Test settings" tool reports a failure Run the SAML2 plugin's Test settings link (on the settings page) first — it reports specific mismatches (missing certificate, unreachable metadata URL, endpoint errors) before you attempt a real login, which is faster to debug than reading raw SSO failures from an end user's browser.

SSO button appears but manual login is gone (or vice versa) Whether both login options appear depends on the plugin's display-name and ordering settings on Manage authentication, and on whether Manual accounts is still enabled. If you need to keep a fallback for admins, ensure Manual accounts stays enabled and ordered alongside SAML2 rather than disabling it.

Attributes (name, email) not updating on repeat logins Confirm the mapping rows in "Mapping IdP to Moodle" (Step 4) exist for every field you expect to sync, and that the MojoAuth connection's attribute mappings send them on every login, not just first login — some Moodle configurations only update profile fields during account creation unless updates are explicitly allowed.

Related docs

• SAML SSO Connections
• Managing Applications
• Integration Guides overview