Extension talk:OpenID Connect

When reporting an error, please be sure to include version information for MediaWiki and all relevant extensions as well as configuration information. Also, please turn on debug logging as described at Manual:How to debug#Logging and include the relevant portions of the debug log.

group mapping

I'm trying to map groups, which are sent from my oidc provider in the token. I've found one example so far, and the 93 different ways I've tried to copy it have not worked. I can get general accounts created, as long as someone has a valid login on my IdP, but if I try to limit by group, there's no change.

I've tried multiple variations on

   'groupsyncs' => [
       'grouper' => [
           'type' => 'syncall',
                'groupAttributeName'  => [
                   'path' => ['groups' => 'dev'],
                ]
           ] 
       ]

including using mapping instead of the syncall type, trying to create my own type, and a few others as well. Do you have any other examples? 136.47.196.65 20:20, 28 May 2025 (UTC)

I was able to get account autocreation working. My IdP is MS Entra. In MS Entra, in my case, the roles were set up on the "App Roles" page of the Application registration. Actual Users or Groups were assigned to those roles on the "Enterprise Application" page.

The role names I created in Entra were distinct, but derived from Mediawiki's normal groups, like 'wiki.sysop', and 'wiki.bureaucrat'. In my case, I also created a 'wiki.default' for authenticated read access (a private wiki). MW will see the assigned roles in an OIDC id_token, in the 'roles' array, like this example:

   {
       ... Other OIDC stuff (sub, preferred_name, etc.) ...
       "roles": [ "wiki.default" ]
   }

If you haven't already seen the exact JSON text of the id_token that MW fetches from your IDP, after successful authentication, take a look at it in debug output for your 'pluggableauth' extension.

MS Entra is pretty configurable, so you might choose to include "groups", "roles" or both in the id_token, and then the "groupsyncs" should be set to match whichever ones you choose.

If the groups you want to use for authorization are spelled out in plain language, or shown as GUIDs, etc., you just have to match what your IDP is configured to send (or: reconfigure your IDP; Entra has options for different kinds of group claims). For me, the appeal of "app roles" was that they are succinct in the authN/authZ data, and still easy to configured on the entra side.

So, here is the 'groupsyncs' that uses those roles:

   $wgPluggableAuth_Config[$yourIDP]['groupsyncs'] = [
     /* 'wikiroles' is an arbitrary label for the sync config. */
     'wikiroles' => [
       'type' => 'mapped',
       'map' => [
         'sysop' => [ 'roles' => 'wiki.sysop' ],   
         'bureaucrat' => [ 'roles' => 'wiki.bureaucrat' ],
         'wiki.default' => [ 'roles' => ['wiki.default', 'wiki.sysop', 'wiki.bureaucrat'] ]
         // This didn't quite work. only worked for existing users:
         // '*' => [ 'roles' => ['wiki.default', 'wiki.sysop', 'wiki.bureaucrat' ] ]
       ]
     ]
   ];

The privileged groups like sysop and bureaucrat were just ready to use, like that already. Any additional MW groups will be left alone, unless they are explicitly mapped.

Note: An earlier attempt, I also used Extension:EmailAuthorization, but it didn't go well for autocreated users. The order of events creating a user, adding them to groups, and then using the user's existence as implicit authorization was a kind of paradox. I think that's only a problem for a private wiki, though.

In order to deny read access to unauthorized users, I had to revoke permissions from "*" and from "user", and grant it to the new custom role/group:

   $wgGroupPermissions['*']['read'] = false;
   $wgGroupPermissions['*']['edit'] = false;
   $wgGroupPermissions['user']['read'] = false;
   $wgGroupPermissions['user']['edit'] = false;
   $wgGroupPermissions['wiki.default']['read'] = true;
   $wgGroupPermissions['wiki.default']['edit'] = true;

I'm still unsure whether I ought to have been able to grant or deny authorization based on syncing 'wiki.default' OIDC role to the mediawiki "*" or "user", or if EmailAuthorization should have helped. Syncing it to a custom group works, though, and I left EmailAuthorization out of my final config.

Jackalahg (talk) 19:30, 20 June 2025 (UTC), heavily edited Sep 18 2025.

Purpose of $wgOpenIDConnect_UseRealNameAsUserName?

When setting $wgOpenIDConnect_UseRealNameAsUserName = true; when connecting with Microsoft Entra ID I got the email address as the new username. Only after additionally adding 'preferred_username' => 'name' to 'data' I got the extension to actually use the name as user name. See my configuration:

My config for OpenIDConnect

wfLoadExtension( 'OpenIDConnect' );
$wgOpenIDConnect_UseRealNameAsUserName = true;
$wgOpenIDConnect_MigrateUsersByEmail = true;
$wgPluggableAuth_Config['Microsoft'] = [
    'plugin' => 'OpenIDConnect',
    'buttonLabelMessage' => 'Pt-login-button-microsoft',
    'data' => [
        'providerURL' => 'https://login.microsoftonline.com/.../v2.0/',
        'clientID' => '...',
        'clientsecret' => '...',
    	'preferred_username' => 'name'
    ]
];

Currently I am a bit confused about the purpose of the configuration parameter. If this is a required combo to do the job it should be documented. -- [[kgh]] (talk) 18:23, 2 June 2025 (UTC)

Hmm, it could be that Entra ID does not send the "preferred_username" claim by default meaning that I have to explicitly set it in this case. [[kgh]] (talk) 09:08, 4 June 2025 (UTC)

That is true, in my experience. Adding the preferred_username to the id token claims has always been useful, to me. In my case, "preferred_username" is in fact what I want: the UPN (UserPrincipalName), although I do modify it with an anonymous PHP function assigned to the "preferredUsernameProcessor". Jackalahg (talk) 16:00, 24 June 2025 (UTC)

Error on login: "Return value must be of type ?string, array returned"

Hello there, I use Nextcloud 31 with OIDC App v1.8.3 as OIDC provider. I can't check the wiki version because I can't login & the wiki is set to private, but it should be the latest stable. After I updated both to the latest version I get the following error when trying to login:

[687523fc0e580ec7d3dd45af] /index.php/Spezial:PluggableAuthLogin?state=some-random-string TypeError: MediaWiki\Extension\OpenIDConnect\OpenIDConnect::refreshAccessToken(): Return value must be of type ?string, array returned
Backtrace:
from /var/www/html/extensions/OpenIDConnect/includes/OpenIDConnect.php(647)

# 0 /var/www/html/extensions/OpenIDConnect/includes/OpenIDConnect.php(617): MediaWiki\Extension\OpenIDConnect\OpenIDConnect->refreshAccessToken()
# 1 /var/www/html/extensions/OpenIDConnect/includes/OpenIDConnect.php(474): MediaWiki\Extension\OpenIDConnect\OpenIDConnect->getAccessToken()
# 2 /var/www/html/extensions/PluggableAuth/includes/Group/GroupProcessorRunner.php(51): MediaWiki\Extension\OpenIDConnect\OpenIDConnect->getAttributes(MediaWiki\User\UserIdentityValue)
# 3 /var/www/html/extensions/PluggableAuth/includes/PluggableAuthLogin.php(131): MediaWiki\Extension\PluggableAuth\Group\GroupProcessorRunner->run(MediaWiki\User\UserIdentityValue, MediaWiki\Extension\OpenIDConnect\OpenIDConnect)
# 4 /var/www/html/includes/specialpage/SpecialPage.php(734): MediaWiki\Extension\PluggableAuth\PluggableAuthLogin->execute(null)
# 5 /var/www/html/includes/specialpage/SpecialPageFactory.php(1731): MediaWiki\SpecialPage\SpecialPage->run(null)
# 6 /var/www/html/includes/actions/ActionEntryPoint.php(499): MediaWiki\SpecialPage\SpecialPageFactory->executePath(string, MediaWiki\Context\RequestContext)
# 7 /var/www/html/includes/actions/ActionEntryPoint.php(143): MediaWiki\Actions\ActionEntryPoint->performRequest()
# 8 /var/www/html/includes/MediaWikiEntryPoint.php(202): MediaWiki\Actions\ActionEntryPoint->execute()
# 9 /var/www/html/index.php(58): MediaWiki\MediaWikiEntryPoint->run()
# 10 {main}

And here is the relevant part of my LocalSettings.php:

$wgShowExceptionDetails = true;

# SSO Setup

wfLoadExtension('PluggableAuth');
$wgGroupPermissions['*']['autocreateaccount'] = true
$wgPluggableAuth_EnableAutoLogin = false;
$wgPluggableAuth_EnableLocalLogin = false;

wfLoadExtension('OpenIDConnect');

# Setup Nextcloud OIDC

$wgPluggableAuth_Config["Nextcloud"] = [
  'plugin' => 'OpenIDConnect',
  'data' => [
    'providerURL' => 'https://example.cloud/index.php/',
    'clientID' => 'censored',
    'clientsecret' => 'censored',
    'scope' => 'openid profile email',
    'preferred_username' => 'preferred_username',
  ],
  'groupsyncs' => [
    [
      'type' => 'mapped',
      'map' => [
        'sysop' => ['groups' => 'admin'],
        'bureaucrat' => [ 'groups' => 'admin' ],
      ]
    ]
  ]
];

wfLoadExtension('UserMerge');
$wgGroupPermissions['bureaucrat']['usermerge'] = true;
$wgGroupPermissions['sysop']['usermerge'] = true;
$wgUserMergeProtectedGroups = ['sysop'];
$wgOpenIDConnect_MigrateUsersByEmail = true;

My configuration worked fine just until recently. Any help would be appreciated! Balduraan (talk) 08:05, 31 July 2025 (UTC)

I didn't knew what else to do so I modified the php code as a hotfix myself to return an array.

Maybe you could improve error handling to catch things like this? Balduraan (talk) 12:04, 31 July 2025 (UTC)

Info: Extension:ShowOIDCIdentity lists user's OIDC identities in Special:Settings

Two years ago, I wrote a small extension to show the OIDC identites in an extra tab in user Special:Settings. Yesterday I updated my extension for MediaWiki 1.42+ (I run and tested the extension with mw-1.44) wherein the deprecated wfGet() is replaced with the new method:

https://github.com/Wikinaut/MediaWiki-Extension-ShowOIDCIdentity

Remark: Yesterday I asked the maintainer of the OpenID Connect extension (Cindy) to integrate my small code into the OIDC extension, because I regard this as very useful (as a user) to see and be able to check the identities with which I as user are connected to my accout. Very useful, I you have more than one OIDC identity connected, which is possible since October 2023. Wikinaut (talk) 07:42, 24 September 2025 (UTC)