This is a short overview for developers of the authentication mechanisms used by CentralAuth.
At the highest level, CentralAuth provides four types of authentication mechanisms: shared credentials, shared cookies, a central session and a central auth token.
For accounts which have not been attached to a central account, the old behavior is kept. Temporary users are handled as normal attached users.
CentralAuth replicates core passwords and temporary passwords (password reset) using a table (
globaluser) shared between all wikis, so the user can log in with the same set of credentials on any wiki. It hooks into the normal login/signup, password reset and password change forms, it doesn't provide any UI of its own. It similarly centralizes emails.
$wgCentralAuthDatabase (the shared DB name; the cluster cannot be configured) and
$wgCentralAuthGlobalPasswordPolicies (same as
$wgPasswordPolicy in core). Implemented in
CentralAuthPrimaryAuthenticationProvider and various hook handlers.
CentralAuth keeps the authentication cookies used by core, but adds a new set of cookies (
centralauth_Token, with similar functionality as their core counterparts) which are set on a shared domain. E.g. for Wikipedia, these cookies are set on the
wikipedia.org domain, so all Wikipedias can access them. The session cookie references a central session (an array of data stored in some object cache, similar to how
SessionBackend stores session metadata in core), the token references
globaluser.gu_auth_token. If the shared cookie is set, but the local cookie isn't set (e.g. the user visits a new language version of Wikipedia), the request still counts as authenticated and the missing cookies will automatically be set.
The session metadata of the local sessions also includes a reference to the central session, and this is validated on every request, so an expiry or deletion of the central session invalidates all linked local sessions. Unlike user tokens in MediaWiki core, a logout resets
globaluser.gu_auth_token, which invalidates the central session(s), which invalidates all local session(s); so a logout action logs the user out across all wikis and all devices (unlike MediaWiki core session handling, where a logout only removes cookies from the device performing the logout).
$wgCentralAuthCookies (the shared cookie domain) and
$wgCentralAuthSessionCacheType (the cache type for the central session). Implemented in
CentralAuthSessionProvider (which also handles sessions for unattached users).
Central session edit
When a central login wiki is configured, CentralAuth will use redirects to make sure the user has a session on that wiki, and use that session to authenticate the user on new wikis and create new local sessions automatically. There are several parts to this:
- Central login: after a successful login, the user is redirected to the central login wiki (e.g.
login.wikimedia.orgfor Wikimedia wikis), session cookies are set there, and the user is redirected back to their previous location. The redirects are immediate so users don't perceive them (other than login taking a few hundred milliseconds longer).
- Edge login: after a successful login and central login, CentralAuth embeds a number of hidden pixels in the next page, one for each "representative" wiki in the wikifarm. Each of these pixels goes through a redirect chain, hopping between the "representative" wiki and the central wiki, verifying the user's identity on the central wiki using the cookies set during central login and then setting cookies on the "representative" wiki for that identity. (The idea here is that together with shared cookies, this can cover most wikis of a wiki farm. E.g. for Wikimedia wikis,
en.wikipedia.orgis configured as the "representative" wiki for Wikipedias, and the edge login sets a cookie on
wikipedia.orgso the user gets logged in not only on English Wikipedia, but all Wikipedias;
en.wiktionary.orgrepresents all Wiktionaries etc. So essentially the user gets logged into most wikis on the farm in the background, right after they log in, without having to visit those wikis at all.)
CentralAuthAnonlocalStorage field or cookie is used to record failures and limit retries. On success, either a notice is shown to the user suggesting them to reload the page, or the personal toolbar is refreshed automatically to a logged-in state, without refreshing the rest of the page.
- Top-level autologin: When the user visits the login page while not logged in, the same autologin process is repeated, but using top-level redirects instead of redirects within a script tag. (This works somewhat more reliably, due to how browsers differentiate between cookie permissions for subresources vs. top-level resources.)
Due to tracking protections in modern browsers, some of these features might not work. As of 2023 October, assuming default browser settings, central login and top-level autologin work in all browsers, but edge login and autologin only work in Chrome and in non-private-mode Edge and Opera.
$wgCentralAuthLoginWiki (the wiki ID of the central login wiki) and
$wgCentralAuthAutoLoginWikis (defines what counts as a "representative" wiki for edge login). The shared cookies configuration also needs to be set for the central session to be enabled. Note that edge login predates the concept of a central login wiki, so setting the edge login wiki list without setting any central login wiki is valid configuration; in that case, the wiki on which the user logged in will be used as an ad hoc "central wiki" for edge login.
Implemented via SpecialCentralLogin (central login), SpecialCentralAutoLogin (edge login, autologin and top-level autologin, differentiated by the
type URL parameter), the
ext.centralauth.centralautologin.clearcookie ResourceLoader modules, and various hooks (mainly
Central auth token edit
The central auth token is a short-lived (10 seconds), single use token that can be used for authenticating in API requests. This provides a mechanism for cross-domain requests that isn't fragile due to session expiry or browser limitations. Tokens can be obtained by making a request to the (local)
action=centralauthtoken API, and passed in the
centralauthtoken GET parameter (which allows validating them during CORS preflight requests) for Action API requests and in the form of an
Authorization: CentralAuthToken <token> header for REST API requests.
$wgCentralAuthTokenCacheType (the cache type for the tokens). Implemented in
CentralAuthTokenSessionProvider and its subclasses.