*TL;DR:* Stuff is changing. If you notice problems with session handling in 1.27.0-wmf.11, file a bug in Phabricator and CC me (Anomie) and Gergő (Tgr).

MediaWiki's authentication layer is getting a major overhaul! This will allow us to do cool stuff like 2-factor authentication without the 2-factor extension having to be redone for LdapAuth/CentralAuth/every-other-auth, third-party login (e.g. Google, Facebook) without hacking around everything with crazy hooks, and supporting more than just one authentication method at a time.

Broadly speaking, this change involves the addition of two new things: SessionManager (already merged, being deployed with 1.27.0-wmf.11) and AuthManager (hopefully coming by the end of February).

- SessionManager replaces the use of PHP's $_SESSION and session_*() functions and the UserLoadFromSession and UserSetCookies hooks with a more extensible mechanism. - AuthManager allows for independent pluggable authentication modules, multiple authentication methods, and removes the assumption that all logins can be handled with a one-page form having "username" and "password" fields. No more needing to adjust every authentication extension to know about every other authentication extension it might have to cooperate with.

However, the changes we're making do mean that various things are going to need updating.

== For users ==

You shouldn't notice any changes due to SessionManager. If you do see problems related to session handling in 1.27.0-wmf.11, file a bug in Phabricator and CC me (Anomie) and Gergő (Tgr).

Once AuthManager comes around, the most visible change will be that the login form will probably be a bit different, and if your browser remembers your login information for you then you might have to re-enter it.

== For bots ==

You shouldn't notice any changes due to SessionManager, but do make sure your code is handling cookies normally instead of using the deprecated return values from action=login to construct cookies manually.[1] If you are handling cookies properly and see problems related to session handling in 1.27.0-wmf.11, file a bug in Phabricator and CC me (Anomie) and Gergő (Tgr).

For AuthManager, the new features mean that unattended login might no longer work since the login flow will now natively support user interaction: the account might have 2-factor enabled, or might need a password reset, or some other thing that requires user interaction. We've created two ways to work around this:

- If possible, switch to OAuth. This week (1.27.0-wmf.10) "owner-only" consumers are being rolled out to make this easier for bot operators: log into your bot account, go to https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration/propose, and create a consumer with the "This consumer is for use only by MyBotName" checkbox checked.The consumer will be approved for use immediately, no waiting or trying to find someone who can approve the consumer for you. Owner-only consumers also don't tag every edit, since all the edits will be from the one account anyway. - If you need to continue using the existing action=login, next week (1.27.0-wmf.11) we're rolling out Bot Passwords. This is something like OAuth-lite, or Google's application passwords: go to Special:BotPasswords, set one up, and then use new bot-password username and password to login as you've always done (no code changes, just update your bot's configuration). It's already live in Beta Labs if you want to test it out.

Login with the "main" account password will continue to work until AuthManager is deployed, and might continue to work after that too (as long as nothing requires user interaction).

For bots that run on third-party wikis, Bot Passwords are in core and are enabled by default, but it's possible a wiki could disable them. OAuth is an extension.

[1]: https://lists.wikimedia.org/pipermail/mediawiki-api-announce/2015-December/0...

== For user scripts and gadgets ==

Since user scripts and gadgets rely on the user already being logged in, you shouldn't notice any changes.

== For core and extension developers ==

There's some other useful stuff that has already been merged, written as part of the groundwork for this project:

- User::newSystemUser(), which replaces directly screwing around with accounts when an extension needs a user for logged actions. - Deprecation or removal of much of the password handling logic from the User class. In particular User::getPassword() no longer works. - CentralIdLookup, a generic mechanism for looking up a "central" ID for cross-wiki features instead of everything needing that functionality having to depend on CentralAuth (and on anything else that might implement global accounts). If you have some sort of cross-wiki login extension that isn't CentralAuth, you'll want to implement this class.

If you're dealing with session data,

- Don't use $_SESSION. Instead, use $request->getSession() or SessionManager::getGlobalSession() to fetch a Session object and access the data through it. Or continue to use the $request->getSessionData() and $request->setSessionData() methods. - Don't use session_id() to test if a session is active. Instead, fetch a Session object as above and call ->isPersistent(). - Don't use wfSetupSession() to make sure a session is active. Instead, fetch a Session object as above and call ->persist(). - Don't use the other PHP session_*() functions either.

If you're implementing the UserLoadFromSession hook to bypass the usual cookie-based session handling (e.g. OAuth, SSLClientAuthentication, or CentralAuth's centralauthtoken), you'll now want to implement a subclass of the new SessionProvider class and add it to $wgSessionProviders. OTOH, if you're using UserLoadFromSession because you're trying to add additional security checks (e.g. SecureSessions), you'll probably want to look into the new SessionMetadata and SessionCheckInfo hooks. And if you're using UserLoadFromSession because you're doing some hack around MediaWiki's existing login form, you'll want to wait for AuthManager. The same goes for UserSetCookies.

If you maintain an authentication-related extension that does a login of some sort, you'll eventually want to be implementing one of AuthManager's AuthenticationProviders. In particular, an extension implementing AuthPlugin now will want to implement a PrimaryAuthenticationProvider in the future. If you're using the hooks that mess with the login form, such as UserCreateForm or UserLoginForm, you'll likely also be wanting to implement an AuthenticationProvider of some sort. Other hooks called from LoginForm might also need attention. You can see the work-in-progress patch at https://gerrit.wikimedia.org/r/#/c/195297/.

A more detailed overview of the new classes is available at https://www.mediawiki.org/wiki/User:Anomie/SessionManager_and_AuthManager. If you have more questions, feel free to ask (email works particularly well).

== For apps that log in ==

Apps shouldn't notice any changes from SessionManager. If you do see problems related to session handling in 1.27.0-wmf.11, file a bug in Phabricator and CC me (Anomie) and Gergő (Tgr).

Once AuthManager comes out, though, you'll need to use the new API action=clientlogin and action=query&meta=authmanagerinfo which will provide the information necessary to construct a fully-functional login UI. More details will be provided once I finish writing the new code ;) but be aware that there's the possibility that you'll have to redirect to a third-party website in there (e.g. if a "login with your Google account" extension happens to be installed).

Do not be tempted to have your app somehow use bot passwords, that's not a supported use case for that feature. A normal (not owner-only) OAuth consumer would be fine.

== For operators of third-party wikis ==

If you're using $wgSessionsInObjectCache = false (which was the default before SessionManager), note that that configuration is no longer supported. Make sure $wgSessionCacheType is set to something that will function well in your environment.

Other than that, things should mostly just work on upgrade with both SessionManager and (in the future) AuthManager. If you use authentication- or session-related extensions that aren't deployed on WMF wikis, however, you may want to check with the maintainers of those extensions.

If you're using the OAuth extension, you should also be aware that its $wgMWOAuthGrantPermissions and $wgMWOAuthGrantPermissionGroups settings are replaced by the new core settings $wgGrantPermissions and $wgGrantPermissionGroups.

Please report bugs related to these changes in Phabricator, and CC me (Anomie) and Gergő (Tgr).