Extension:OpenID Connect/ms
OpenID Connect Release status: stable |
|
---|---|
Implementation | User identity |
Description | Extends the PluggableAuth extension to provide authentication using OpenID Connect |
Author(s) | Cindy Cicalese (cindy.cicalesebincang) |
Latest version | 8.0.3 (2024-04-11) |
Compatibility policy | Snapshots releases along with MediaWiki. Master is not backward compatible. |
MediaWiki | >= 1.36.0 |
Database changes | Yes |
Tables | openid_connect |
License | MIT License |
Download | |
|
|
Translate the OpenID Connect extension if it is available at translatewiki.net | |
Issues | Open tasks · Report a bug |
The OpenID Connect extension extends the PluggableAuth extension to provide authentication using OpenID Connect.
Special thanks to jumbojett for the OpenID Connect PHP library used by this extension.
Installation
Preconditions
Extension
- Download and move the extracted
OpenIDConnect
folder to yourextensions/
directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OpenIDConnect - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'OpenIDConnect' );
- Run the update script which will automatically create the necessary database tables that this extension needs.
- Install dependencies.
- Configure as required.
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Dependencies
The OpenIDConnect extension requires the CURL PHP extension and the OpenID Connect PHP library. If you are following the standard installation procedure and downloaded the archive from mediawiki.org, the dependencies have been bundled and there is no further action required.
If you are following the development/contributor installation procedure using git, add the line "extensions/OpenIDConnect/composer.json"
to the composer.local.json
file in the root directory of your wiki, e.g.
{
"extra": {
"merge-plugin": {
"include": [
"extensions/OpenIDConnect/composer.json"
]
}
}
}
Then run composer update
in the root directory of your wiki.
This will install any dependencies (i.e. the jumbojett OpenID Connect PHP library).
Configuration
Parameters
Most of the configuration for OpenID Connect is handled by a file found at /.well-known/openid-configuration
[1] on the provider's domain.
This contains most of the settings that are needed to handle authentication.
Flag | Default | Description | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
$wgPluggableAuth_Config (see Extension:PluggableAuth#Configuration)
|
[] | A mandatory array of arrays specifying the OpenID Connect issuers and their configuration. The data field of the array contains an array that has the following keys:
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_UseRealNameAsUserName
|
false
|
If a new user is being created in the database and no preferred username was provided by the issuer or preferred_username was set to null or the empty string, a value of true for this flag indicates that the user's real name, if provided by the issuer, should be used as the new user's username. If set to true , and no preferred username was provided by the issuer "User" for the first and starting with the second user "User" followed by a number will be used, e.g., "User", "User1", "User2", etc. The same naming happens if this parameter is set to false .
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_UseEmailNameAsUserName
|
false
|
If a new user is being created in the database, and no preferred username was provided by the issuer or preferred_username was set to null or the empty string, and either no real name was provided by the issuer or $wgOpenIDConnect_UseRealNameAsUserName was undefined or set to false , a value of true for this flag indicates that the name portion of the user's email address, if provided by the issuer, should be used as the new user's username. This parameter cannot be set to true at the same time $wgOpenIDConnect_UseRealNameAsUserName is set to true . In this case this setting will be ignored.
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_MigrateUsersByUserName
|
false
|
If a user already exists in the database with the same user name as the authenticated user and has null values for subject and issuer, use this user, setting the subject and issuer in the database to those of the authenticated user. This is useful when the wiki previously used a different authentication mechanism. If neither this parameter nor $wgOpenIDConnect_MigrateUsersByEmail are set to true the settings for user creation will be used as described above.
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_MigrateUsersByEmail
|
false
|
If a user already exists in the database with the same email address as the authenticated user and has null values for subject and issuer, use this user, setting the subject and issuer in the database to those of the authenticated user. This is useful when the wiki previously used a different authentication mechanism. If neither this parameter nor $wgOpenIDConnect_MigrateUsersByUserName are set to true the settings for user creation will be used as described above.
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_ForceReauth
|
false
|
When the user logs out from the wiki, force reauthentication with the identity provider at next login even if they have not logged out from the identity provider. | ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_SingleLogout
|
false
|
When the user logs out from the wiki, also log out from the identity provider. This is not supported by all identity providers (e.g. Google). | ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_PreferredUsernameProcessor
|
null
|
Callable that takes two parameters (preferred username string and the array of attributes returned from the identity provider) and returns a possibly modified preferred username to use for a new user; this value is only used if no value is provided for preferredUsernameProcessor in the config data section (version 7.2.0+)
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_RealNameProcessor
|
null
|
Callable that takes two parameters (real name string and the array of attributes returned from the identity provider) and returns a possibly modified real name to use for a new user; this value is only used if no value is provided for realnameProcessor in the config data section (version 7.2.0+)
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_EmailProcessor
|
null
|
Callable that takes two parameters (email address string and the array of attributes returned from the identity provider) and returns a possibly modified email address to use for a new user; this value is only used if no value is provided for emailProcessor in the config data section (version 7.2.0+)
| ||||||||||||||||||||||||||||||||||||||||||||
$wgOpenIDConnect_UseRandomUsernames
|
false
|
Boolean to indicate whether to generate a random unique identifier to use for the username of a new user if no preferred username is provided (rather than the default of using User followed by a unique integer) and no value is provided for useRandomUsernames in the config data section (version 8.0.0+)
|
When configuring the identity provider, it will ask for a redirect URL or callback URL. Use the full URL to the Special:PluggableAuthLogin page for that value.
Connecting to a single issuer
A simple example of the $wgPluggableAuth_Config
configuration for a single issuer is as follows:
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://id.mycompany_abc.com/connect/',
'clientID' => '.....',
'clientsecret' => '.....'
]
];
Connecting to a multiple issuers
An example of the $wgPluggableAuth_Config
configuration for multiple issuers is as follows:
$wgPluggableAuth_Config["My Company's Connect Server"] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://id.mycompany_abc.com/connect/',
'clientID' => '.....',
'clientsecret' => '.....'
]
];
$wgPluggableAuth_Config["Partner Company's Connect Server"] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://id.partnercompany_def.com/connect/',
'clientID' => '.....',
'clientsecret' => '.....'
]
];
As of version 7.0.0, group synchronization is possible using the capability provided by the PluggableAuth extension. For information on configurating group synchronization, see the PluggableAuth documentation.
Examples
Issuer configuration
- Using the Google Developer Console create a project.
- Click on the project, click on the hamburger menu (three horizontal lines in the top left), and click on
APIs & Services -> Credentials
on the menu. - Click the
Create credentials -> OAuth client ID
button and selectWeb application
. Fill in the consent screen information and save. - Provide the redirect URI in
Authorized redirect URIs
[2]:https://[URLofWiki]/wiki/Special:PluggableAuthLogin
- Click
Create Client ID
. - Note the
Client ID
andClient Secret
that are assigned.
Extension configuration
The Google issuer is now configured.
Add the corresponding configuration to your LocalSettings.php file, filling in the clientID
and clientsecret
fields with the values assigned above.
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://accounts.google.com',
'clientID' => '.....',
'clientsecret' => '.....',
]
];
You may also assign other values such as proxy
and authparam
.
Azure Active Directory
Azure Active Directory is now Microsoft Entra ID.
Microsoft Entra ID
Entra ID is the new name of the service formerly called "Azure Active Directory."
Issuer configuration
- In the Azure portal, go to 'Active Directory' and then 'App Registrations'
- Register a new Application
- Provide a Name
- Likely specify 'Accounts in this org directory only'
- Provide redirect URI:[2]
https://[URLofWiki]/wiki/Special:PluggableAuthLogin
- In the new app, go to 'Certificates and secrets' and create a new Client secret
Extension configuration
Using the 'Application (client) ID', Directory (tenant) ID, and Secret from the application, populate your "LocalSettings.php" file:
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://login.microsoftonline.com/[tenantID]/v2.0/',
'clientID' => '[Application (Client) ID]',
'clientsecret' => '[Secret from Certs and Secrets]'
]
];
$wgOpenIDConnect_UseRealNameAsUserName = true;
Extension configuration with Group mapping
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
from above example
],
'groupsyncs' => [
[
'type' => 'mapped',
'map' => [
'sysop' => ['groups' => '8d1cc10c-3e95-4637-941d-0c1237352e85'],
'interface-admin' => ['groups' => 'See where to find Object ID below']
]
]
]
];
- In Azure, go to `Manage` -> `Token configuration`. Click `Add group claims`, select "Groups assigned to the application (recommended for large enterprise companies to avoid exceeding the limit on the number of groups a token can emit)".
- Find app in Enterprise applications, and go to `Manage` -> `Users and groups`. Add group.
- You can now click on the group and copy the `Object ID` and paste above.
- You need to relogin to take effect.
Keycloak
Issuer configuration
Assumptions:
- Your Keycloak realm name is acme
- Your Keycloak URL and Port is https://keycloak.local:8080
- Your Keycloak Client ID is set to mediawiki
- Your auto-generated client secret is 12345
Extension configuration
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://keycloak.local:8080/realms/acme',
'clientID' => 'mediawiki',
'clientsecret' => '12345'
]
];
Troubleshooting
- If you're running into trouble, like "The provider {$param} could not be fetched. Make sure your provider has a well known configuration available.", your URI[3] is wrong. You can test the correctness by calling https://keycloak.local:8080/realms/acme/.well-known/openid-configuration in your browser. If you get back a long JSON, the path is correct.
- Another way to verify the 'providerURL' is to check it against the ‘Redirect URI’ at Keycloak>Identity Providers>keycloak-oidc, i.e.: https://keycloak.local:8080/realms/acme/broker/keycloak-oidc/endpoint. For 'providerURL' you need the portion up to one level below realms.
- Make sure the redirect uri provided by this OIDC[4] plugin is set valid for your keycloak-server under acme -> Clients -> mediawiki -> Settings -> valid redirect uris . For testing purposes you can add a wildcard "*".
Okta
Issuer configuration
Okta OIDC app settings
Allowed grant types: (all) Login redirect URIs: the full URL to Special:PluggableAuthLogin, e.g. https://www.example.com/wiki/index.php/Special:PluggableAuthLogin Login flow: "Redirect to app to initiate login (OIDC compliant)" Initiate login URI: the full URL to Special:UserLogin, e.g. https://www.example.com/wiki/index.php/Special:UserLogin
Extension configuration
You must specify the openid, profile, and email scopes to communicate with Okta. If you omit the appropriate scopes, Okta will gladly authenticate your users but will not return any useful claims.
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://your-okta-org.okta.com',
'clientID' => '(paste the client ID Okta assigned your new app here)',
'clientsecret' => '(paste the client secret Okta assigned your new app here)'
]
];
Auto-creating users
If you want to take advantage of MediaWiki's user auto-creation (e.g. $wgGroupPermissions['*']['autocreateaccount'] = true;
), be aware that Okta's preferred_username claims take the format of an email address.
If you do not want your users to have an @ character in their usernames (this is forbidden by MediaWiki by default), you will need to specify an alternative claim to use via the 'preferred_username' key in your $wgPluggableAuth_Config.
Allowing @ in usernames may break your wiki's Interwiki compatibility (if you rely on that).
To allow the use of the @ character, just set $wgInvalidUsernameCharacters = ' ';
and $wgUserrightsInterwikiDelimiter = '#';
in LocalSettings.php.
Notes
Note: As of the date this example was written, a bug exists in the OpenID Connect PHP library which causes stricter OIDC providers like Okta to reject certain requests. This should be resolved in the future when the library is updated to incorporate the change.
The solution is to add a single line of code to $MEDIAWIKI_ROOT/extensions/OpenIDConnect/vendor/jumbojett/openid-connect-php/src/OpenIDConnectClient.php as follows:
right below: unset($token_params['client_secret']);
simply add: unset($token_params['client_id']); # see https://github.com/jumbojett/OpenID-Connect-PHP/pull/208/commits/dd44c1ca7e45d35dcd8f32ea503b545149bc6562
(this was fixed in version 0.9.8)
To authenticate your users against Okta, you must first create a new OIDC app in your Okta org and assign it to the relevant users/groups, etc.
Gitlab
Issuer configuration
- Login to Gitlab Admin Area
- Go to Applications -> New Application
- Name: MediaWiki
- Redirect URI: <wiki server>/wiki/Special:PluggableAuthLogin
- Trusted: yes
- Confidential: yes
- Scopes: openid, profile, email
- Submit
- Copy Application ID and Secret to
LocalSettings.php
Extension configuration
In "LocalSettings.php"
// Extension PluggableAuth
wfLoadExtension( 'PluggableAuth' );
$wgPluggableAuth_EnableLocalLogin = true; // set to false to deactivate local logins if required
// Extension OpenIDConnect
wfLoadExtension( 'OpenIDConnect' );
$wgPluggableAuth_Config['Login with your Gitlab Account'] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => '...', // '''Add your gitlab server here (main page)'''
'clientID' => '...', // '''Insert Gitlab Application ID here!'''
'clientsecret' => '...', // '''Insert Gitlab Secret here!'''
// Alternative 'nickname'
// Alternative 'name'
'preferred_username' => 'nickname'
]
];
You can find more information to Gitlab's docs at OpenID Connect Provider.
Amazon Cognito
Amazon Cognito is a user identity service by AWS[5].
Issuer configuration
Assumptions:
- Your Amazon Cognito user pool ID is us-west-2_XdLg34nAA
- Your AWS region is us-west-2
- Your Client ID is set to mediawiki
- Your auto-generated client secret is 12345
Extension configuration
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://cognito-idp.us-west-2.amazonaws.com/us-west-2_XdLg34nAA',
'clientID' => 'mediawiki',
'clientsecret' => '12345'
]
];
For detailed instructions about how to configure Amazon Cognito for this use case, please refer to https://medium.com/@robert.broeckelmann/openid-connect-authorization-code-flow-with-aws-cognito-246997abd11a
NextCloud
Issuer configuration
Assumptions:
- Running Nextcloud version 24, or Nextcloud All-In-One v3.0.0
- Nextcloud has the App "OIDC Identity Provider v0.2.6" installed. https://github.com/H2CK/oidc
- Your nextcloud runs from domain my.nextcloud.com
- The public url : https://my.nextcloud.com/.well-known/openid-configuration is redirected to <your internal nextcloud server>/index.php/apps/oidc/openid-configuration by e.g. nginx or another reverse proxy.
- Via nextcloud admin account, under Settings > Security > "Open ID Connect clients" you add a client with the following details
- Name: wiki
- Redirection URI: The full URL to
Special:PluggableAuthLogin
, e.g.https://www.example.com/wiki/index.php/Special:PluggableAuthLogin
(Note: if your wiki's default language isn't english,Special
will be different!) - Signing Algorithm: RS256
- Type: confidential When you click "add" it will provide the Client Identifier string and the Secret string. Enter these values into the
LocalSettings.php
formyGeneratedID
andmyGeneratedSecret
shown below.
Extension configuration
wfLoadExtension( 'PluggableAuth' );
$wgGroupPermissions['*']['autocreateaccount'] = true;
$wgPluggableAuth_EnableAutoLogin = true; // Now the user doesn't have the 'login'/'logout' button.
wfLoadExtension( 'OpenIDConnect' );
$wgPluggableAuth_Config[] = [
'plugin' => 'OpenIDConnect',
'data' => [
'providerURL' => 'https://my.nextcloud.com',
'clientID' => 'myGeneratedID',
'clientsecret' => 'myGeneratedSecret'
]
];
Release Notes
- Version 8.0.2
- Use case insensitive email comparison for email migration
- Improved random username generation
- Version 8.0.1
- Reverted back to version 0.9.10 of https://github.com/jumbojett/OpenID-Connect-PHP for stability
- Version 8.0.0
- Allow multiple identity providers to map to a single user (T361877)
- Version 7.2.0
- Add processor functions (T357752) to allow username, real name, and email normalization
- Add random username generator
- Updated to version 1.0.0 of https://github.com/jumbojett/OpenID-Connect-PHP
- Code clean-up (added tests, removed deprecations)
- Version 7.1.0
- Support custom issuer validator (T360249)
- Version 7.0.2
- Use ID token to get claims during authentication (T348931)
- Version 7.0.1
- Allow preferred_username config attribute to be null or blank (T339311)
- Version 7.0.0
- Made compatible with PluggableAuth 7.0.0
- Add optional single logout (
$wgOpenIDConnect_SingleLogout
) - Replace ForceLogout (which was broken) with ForceReauth (
$wgOpenIDConnect_ForceReauth
) - Add function to get access token with refresh token
- Use new PluggableAuth group population framework; supports retrieval of attributes including groups
- Code improvements
- Bug fixes:
- T307353: Query condition in username migration is wrong
- Version 6.2
- Update jumbojett/openid-connect-php library version to 0.9.10
- Replace deprecated User::idFromName
- Version 6.1
- Make sure populate group hook only runs for OpenID Connect plugin instances
- Version 6.0
- Updated to be compatible with PluggableAuth version 6.0
- Version 5.4
- Updated jumbojett/openid-connect-php to version 0.9.1
- Fixed bug while trying to authenticate with Okta where extra parameters are sent in the request making the request fail
- Version 5.3
- Fixed bug with migrated initial lowercase usernames (T249630)
- Version 5.2
- Added optional configuration options for disabling the verification of hostnames and certificates, for use in development environments with self-issued certificates
- Version 5.1
- Added generation of full redirect URL so OpenID Connect PHP library doesn't have to guess, which occasionally it didn't have enough information to do accurately
- Version 5.0
- Moved subject and issuer columns from
user
table toopenid_connect
table (requires database update) - Added support for Postgres
- Version 4.1
- Added namespace for library class
- Version 4.0
- Added optional error message to authenticate()
- Bumped version number to synchronize with PluggableAuth and SimpleSAMLphp extensions
- Version 2.3
- Fixed whitelist implementation
- Changes migration flags to allow migration by email address in addition to migration by user name
- Version 2.2
- Fixes related to PluggableAuth MediaWIki 1.27 upgrade
- Array coding conventions
- Version 2.1
- Update to MediaWiki 1.27 session management
- Added default values for configuration variables to extension.json
- Version 2.0
- Updated extension registration
- Changed configuration variables to use "wg" prefix
- Added composer.json to get OpenID Connect library using composer
- Version 1.2
- Added ability to specify auth params and added support for table prefixes
- Version 1.1
- Added support for Google
- Version 1.0
- Initial version
Hal tertahu
- Wikis that use URLs of the form
https://example.org/w/index.php?title=Page_title
(i.e. having the page title provided as a query parameter) will not be redirected correctly to complete the authentication flow. Instead, URLs must be of the formhttps://example.org/w/index.php/Page_title
, which can be accomplished by using short URLs or by setting$wgArticlePath
appropriately. - This extension may not work correctly with
$wgMainCacheType = CACHE_ACCEL;
. In this case you also need to set$wgSessionCacheType = CACHE_DB;
(see task T147161). - This extension does not work on non-standard ports unless you manually update the underlying Openid connect client, see: jumbojett/OpenID-Connect-PHP issue 58 on GitHub. This issue also applies when connecting to other webserver than IIS.
- When running the
createAndPromote.php
maintenance script, both the PluggableAuth and OpenID Connect extensions need to be disabled by commenting out theirwfLoadExtension()
calls. - This extension does not support custom well-known endpoints. This means Azure Active Directory B2C's OpenID Connect authentication flow is currently not supported.
Notes
- ↑ openid.net: OpenID Provider Configuration Request
- ↑ 2.0 2.1 Note that the link for the authorized redirect URI must be localized, e.g if you set your wiki's instance language to
'de'
($wgLanguageCode = 'de';
) you need to specify "https://[URLofWiki]/wiki/Spezial:PluggableAuthLogin". - ↑ Uniform Resource Identifier (URI)
- ↑ OpenID Connect (OIDC)
- ↑ Amazon Web Services (AWS)
See also
- Extension:PluggableAuth
- Extension:SimpleSAMLphp
- Extension:Email Authorization
- Extension:LDAP Authorization
This extension is included in the following wiki farms/hosts and/or packages: This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm. |
- PluggableAuth plugins/ms
- Stable extensions/ms
- User identity extensions/ms
- MIT licensed extensions/ms
- Extensions in Wikimedia version control/ms
- LoadExtensionSchemaUpdates extensions/ms
- All extensions/ms
- Extensions included in BlueSpice/ms
- Extensions included in Canasta/ms
- Extensions included in MyWikis/ms
- Extensions included in ProWiki/ms
- Extensions included in WikiForge/ms
- Extensions by MITRE/ms