OAuth

OAuth is a protocol that lets applications impersonate users in limited ways, after getting permission from those users. It has two versions, OAuth 1.0 (very old and rarely used, but still popular in the Wikimedia tooling comunity) and OAuth 2.0 (widely used on the internet). The public Wikimedia wikis use both versions (provided by mw:Extension:OAuth), e.g. to allow users to offload editing tasks to external applications (usually, but not always, applications on Toolforge).

For a description of how OAuth works, and how to develop applications that use it, see mw:OAuth/For Developers. For a user manual, see mw:Help:OAuth. This page is focusing on operations concerns. Owner-only OAuth consumers are not discussed here; for the most part those can be thought of as a special kind of password, much like bot passwords.

Edge interactions

OAuth 2 identifies requests with an Authorization: Bearer <token> header; the token is a JWT signed with the key pair configured in $wgOAuth2PrivateKey / $wgOAuth2PublicKey. ATS and the API gateway validate it and use it for higher rate limits.

OAuth1 identifies requests with an Authorization: OAuth <signature> header, but the signature is not decodeable, and does not result in any special behavior in the edge.

Data

The OAuth MediaWiki extension uses three tables: oauth_registered_consumer which stores data about clients (applications using OAuth, more or less; although one application can have several registered clients, mainly as a way of versioning), oauth_accepted_consumer which stores data about the authorizations users give to clients, and oauth2_access_token which stores data about the tokens OAuth 2 uses as credentials. (OAuth 1 credentials are stored in oauth_accepted_consumer.access_token but the process by which they are turned into signatures in the header is more complicated.) See DB schema in gitiles.

The main OAuth installation is on metawiki; clients registered there might be able to access all public Wikimedia wikis (although this might be restricted by the consumer settings). The data tables are also in the metawiki database. Private wikis could in theory have their own OAuth server and their own versions of the tables, but currently none do.

OAuth 2 refresh tokens are stored outside the wiki database, in MainStash (T390000).

Security

OAuth applications need to be registered by the developer, and (unless they have very limited rights) go through manual review by OAuth admins or stewards, which tends to be cursory and mostly just involves checking the permissions the application would have. We almost never approve clients with highly security-sensitive permissions (e.g. Javascript editing), although some exceptions exist. Clients with admin permissions (e.g. page deletion) are generally approved if there is a sound rationale and a trusted community member involved. See m:OAuth app guidelines.

OAuth applications get a client ID / client secret pair (some OAuth 2 apps only use the client ID), which can be exchanged, possibly with user interaction, for an access token (for OAuth 1, an access token / access secret pair) for a specific user. OAuth 1 request signatures require all four values; OAuth 2 only requires the access token. A leaked client secret needs to be reset by the application owner.

Management

Client management happens via m:Special:OAuthManageConsumers (you need to be in the oauthadmin group, or steward or staff). Publicly viewable consumer information is at m:Special:OAuthListConsumers. There is no search functionality but you can follow the link for an arbitrary consumer and replace the client ID in the URL.

In case of a data leak, or an application misbehaving, go to OAuthManageConsumers and set the consumer to disabled. That should prevent any kind of abuse of credentials (reject all API requests made with those credentials), and prevent new users from granting permission to the application. The action can be undone. There's also a "disable and suppress" option in case the registration mechanism itself is abused, e.g. by putting private information in a consumer name.

If a single user is misbehaving and abusing an application, they can simply be blocked on the wiki by name; IP/range blocks don't work though, as the wiki will see the tool IP. Popular tools are expected to provide their own anti-abuse mechanisms - if they don't, and are repeatedly abused, just disable the tool and tell the owner to improve it.

The admin interface only allows disabling/reenabling; most client details can't be changed (the developer needs to create a new consumer). In the case of a leaked client secret, the owner can reset it. Revoking permission from a specific user can only be done by that user, from the "connected applications" link in their preferences. As always, it's best to avoid direct DB manipulation, but it should be reasonably safe if really needed for some reason (short of changing ids/keys).

Many things use OAuth; disabling it on the main cluster is extremely disruptive. If you need to do that anyway, set $wmgUseOAuth = false in that wiki/cluster's config. Alternatively, you can set $wgMWOAuthReadOnly = true (will disallow any changes to OAuth consumers, but not using existing consumers) or $wgMWOauthDisabledApiModules[] = "ApiModuleClassName" (will prevent that API module from being used with any OAuth credentials).

Logging

Consumer state changes (proposal, approval, disabling etc) are logged in the (public) wiki log: m:Special:Log/mwoauthconsumer. They are also logged to the OAuth channel on Logstash. Authorizations (users giving permission to an application) are also logged to the OAuth channel. Authentication (ie. when an API request uses OAuth credentials) is not logged.

Actions performed via OAuth have an OAuth CID: <id> change tag on them. Note this is the consumer ID, not the consumer key. You can find it via the links in m:Special:OAuthListConsumers, or in the database. To get a quick estimate of how important an OAuth tool is, you can look at the change_tag_def.ctd_count table field for that change tag to get the total number of times it was used on the given wiki (there are important tools only doing read actions though).

The OAuth Logstash channel has a dashboard.