*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/…
== 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).
--
Brad Jorsch (Anomie)
Senior Software Engineer
Wikimedia Foundation