26 August 2025, 16:07

Hi everyone,

Recently, we've received a query about the authentication method OpenID Connect. Since it seems that more organisations want to switch to that authentication method instead of using SAML, I'm posting the reply from Robert here so everyone can benefit.

Thank you

Kristina

-----------

Question: How does the mapping in OIDC work with the 'mahara' scope?

Response:

The OIDC authentication instance configuration form has the option  'Use the "mahara" scope'.

When turning this on it allows for the Identity Provider to send through informational keys for 'institution', 'avatar', and  'roles' on the scope 'mahara'. The 'family_name', 'given_name', 'preferred_username', 'email' should come through via the 'profile' scope.

The 'Institution match attribute' and 'Institution match value' fields can be used if you have more than one institution in Mahara using the same Identity Provider and want people to log into the correct institution within Mahara based on information passed back from the Identity Provider.

For example, if you have a Mahara site where there is only the 'mahara' site or one institution set up and everyone logs into the site via the same Identity Provider, then you should not need to fill in those institution fields. Note: We recommend that you always set up an institution and add your account holders in there even if it is the only one because then you have more admin roles available, i.e. institution support admin and institution admin.

But if you have a site with two or more institutions, say Sciences plus Humanities, and both of these institutions connect to the same Identity Provider, then you would need to set these values so that Science students end up in Sciences institution on login.

For example, if the userinfo coming back while logging in from the Identity Provider for an account was like this:

    [sub] => my_username
    [email] => [email protected]
    ...
    [eduPersonAffiliation] => array([0] => sciences)

Then we'd set:
Institution match attribute:  eduPersonAffiliation
Institution match value: sciences

And for the Humanities institution, like so
Institution match attribute:  eduPersonAffiliation
Institution match value: humanities

To check what is being returned from your Identity Provider you can make the following change

diff --git a/htdocs/auth/oidc/lib.php b/htdocs/auth/oidc/lib.php
index b520f93446..b66c966ff5 100644
--- a/htdocs/auth/oidc/lib.php
+++ b/htdocs/auth/oidc/lib.php
@@ -73,7 +73,7 @@ class AuthOidc extends Auth {
     public function request_user_authorise($oidcuniqid, $tokenparams, $idtoken, $user_info) {
         global $USER, $SESSION;
         $this->must_be_ready();
-
+log_debug($user_info);
         $username = $oidcuniqid;
         if (!empty($user_info['preferred_username'])) {
             $username = $user_info['preferred_username'];


And then check you error log when logging into you Identity Provider to see if any information is returned to Mahara that would relate to an 'institution' field so you can find what the 'attribute' and 'value' information will be. And then set your OIDC instance configuration to use those values.

26 August 2025, 18:30

Hello everyone,
does the oidc provider have to be called the same for every institution?
It would of course be convenient not to have to enter the idp provider data for each institution.
The hint says something different about the match attribute. It says that the insittution short name is used as the match attribute. This is a bit confusing because it would make entering the match value obsolete. What is correct?

Best regards
Steffen

29 August 2025, 9:43

Hi Steffen,

Currently if you want to have multiple institutions all use OIDC with the same IdP you will need to set up the OIDC instance in each of the institutions you want to connect with the only differences being the 'Instance name' field to be set to contain the text for the login button on homepage, eg 'student login' vs 'Alumni login' if you had two institutions for that.

"The hint says something different about the match attribute. It says that the institution short name is used as the match attribute."

The hint indicates the best practice of setting the institution value we expect to be sent from the IdP to be the same value we use as shortname for the institution in Mahara to make things clearer/easier to follow.

But it doesn't have to be - if the IdP can't be altered and sends something like 'exstudents' as institution value it allows us to enter 'exstudents' into that field for the OIDC instance in our 'alumni' institution and have them connect up. At the moment it is only required to fill those fields in if the 'attribute' key is not 'institution' and attribute 'value' does not match the institution shortname or if there are more than one institution/instance connecting to the same IdP so that the system can work out what instance to use to complete the login on return from the IdP

Cheers

Robert