Extension:OpenID Connect/en

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.

Install Dependencies
Add the line  to the "composer.local.json" file in the root directory of your wiki, e.g. Then run   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 on the provider's domain. This contains most of the settings that are needed to handle authentication. 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.

A simple example of the configuration for a single issuer is as follows: An example of the configuration for multiple issuers is as follows:

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.

Example: Google as an Issuer

 * 1) Using the Google Developer Console create a project.
 * 2) Click on the project, click on the hamburger menu (three horizontal lines in the top left), and click on   on the menu.
 * 3) Click the   button and select  . Fill in the consent screen information and save.
 * 4) Provide the redirect URI in  :
 * 5) Click.
 * 6) Note the   and   that are assigned.

The Google issuer is now configured. Add the corresponding configuration to your LocalSettings.php file, filling in the  and   fields with the values assigned above.

You may also assign other values such as  and.

Example: Using it against Azure Active Directory

 * 1) In the Azure portal, go to 'Active Directory' and then 'App Registrations'
 * 2) Register a new Application
 * 3) Provide a Name
 * 4) Likely specify 'Accounts in this org directory only'
 * 5) Provide redirect URI:
 * 6) In the new app, go to 'Certificates and secrets' and create a new Client secret
 * 7) Using the 'Application (client) ID', Directory (tenant) ID, and Secret from the application, populate your LocalSettings.php:

Important Notes

 * The .well-known/openid-configuration location was derived from the 'OpenID Connect metadata document' endpoint in the app Endpoints.

Example: Using it against Keycloak
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

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 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 plugin is set valid for your keycloak-server under acme -> Clients -> mediawiki -> Settings -> valid redirect uris . For testing purposes you can add a wildcard "*".

Example: Using it with Okta
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: simply add:  (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.

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 settings
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.

Auto-creating users
If you want to take advantage of MediaWiki's user auto-creation (e.g. ), 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 and  in LocalSettings.php.

Gitlab configuration:

 * Login to Gitlab Admin Area
 * Go to Applications -> New Application
 * Name: MediaWiki
 * Redirect URI: &lt;wiki server>/wiki/Special:PluggableAuthLogin
 * Trusted: yes
 * Confidential: yes
 * Scopes: openid, profile, email
 * Submit
 * Copy Application ID and Secret to

MediaWiki Configuration
In "LocalSettings.php" You can find more information to Gitlab's docs at OpenID Connect Provider.

Example: Using it against Amazon Cognito
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

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

Example: Using it against NextCloud
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 &lt;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: SomeWrongURI
 * 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 for myGeneratedID and myGeneratedSecret shown below.

MediaWiki's LocalSettings.php addition:

Now navigate to the Wikipedia page, it will redirect to your nextcloud server. The nextcloud server will state that the landing page is incorrect, and to contact the administrator for this client. Copy the URL of this page, and copy the argument part for "redirect_uri". Use an online site to decode the http URL.

e.g.

URL: https://my.nextcloud.com/apps/oidc/authorize?response_type=code&redirect_uri= https%3A%2F%2Fmy.wiki.com%2Findex.php%2FSpeciaal%3APluggableAuthLogin&client_id=xvLZjUpAvxn

Decoded redirect URI: https://my.wiki.com/index.php/Speciaal:PluggableAuthLogin

Use the found string in Nextcloud OpenID settings for client "wiki", and update the Redirection URI by replacing the previously entered "SomeWrongURI" with the found string.

Release Notes

 * 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
 * Replace ForceLogout (which was broken) with 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 to openid_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

Known issues

 * Wikis that use URLs of the form  (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 form , which can be accomplished by using  or by setting  appropriately.
 * This extension may not work correctly with . In this case you also need to set (see ).
 * 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  maintenance script, both the PluggableAuth and OpenID Connect extensions need to be disabled by commenting out their   calls.