Extension:CentralAuth/authentication

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.

Shared credentials

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.

Configurable via $wgCentralAuthDatabase (the shared DB name; the cluster cannot be configured) and $wgCentralAuthGlobalPasswordPolicies (same as $wgPasswordPolicy in core). Implemented in CentralAuthPrimaryAuthenticationProvider and various hook handlers.

Shared cookies

CentralAuth keeps the authentication cookies used by core, but adds a new set of cookies (centralauth_User, centralauth_Session, 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).

Configurable via $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

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.org for 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.org is configured as the "representative" wiki for Wikipedias, and the edge login sets a cookie on wikipedia.org so the user gets logged in not only on English Wikipedia, but all Wikipedias; en.wiktionary.org represents 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.)
• Autologin: When the user visits a wiki where they are not logged in (because it wasn't covered by edge login, edge login failed for some reason, or the session for that wiki expired), a redirect chain similar to edge login (but via a script tag, not a pixel, if the client supports Javascript) is used to try to log them in in the background. A CentralAuthAnon localStorage 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.

Configurable via $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 and ext.centralauth.centralautologin.clearcookie ResourceLoader modules, and various hooks (mainly BeforePageDisplay and SpecialPageBeforeExecute).

Central auth token

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.

Configurable via $wgCentralAuthTokenCacheType (the cache type for the tokens). Implemented in ApiCentralAuthToken and CentralAuthTokenSessionProvider and its subclasses.