OAuth app guidelines

These guidelines describe the requirements for OAuth apps (websites and software tools which would like to access Wikimedia wikis via OAuth). They are meant to inform both developers creating such apps and the admins reviewing them.

To allow your app to be used by others via OAuth, you need to register it via Special:OAuthConsumerRegistration/propose. Registrations will be reviewed by OAuth admins. (Feel free to contact one of them if you don't get within a few days.)

Developer guidelines

• The app must respect the intent of the users authorizing it. Any non-obvious use of the permissions granted to the app should be clearly explained in the user interface or the documentation.
• Rights should be limited to what's necessary. If the app will be used on a single project, limit it to that project. Don't ask for grants that the app is not going to use.
  • Rights related to JS editing (editmycssjs, editinterface) or private information of other users (such as viewrestrictedlogs or checkuser) are highly sensitive and apps requesting them are very unlikely to be approved.
• Document how you collect and handle user data. If the app collects any personally identifiable information, provide a privacy policy. Opt for not collecting at all if possible.
• Use HTTPS if possible.
• Consider publishing the source code of the app under an OSI-approved license (such as one of these).
• If the app is hosted in a Wikimedia Cloud VPS project or Toolforge, it must follow the Cloud Services Terms of Use as well.
• The secret key (consumer secret) received at registration must be kept secret, even from users of the app. If that's not possible (e.g. a mobile app or desktop application without a backend component), the app must be registered as an owner-only app.

Review guidelines

Make sure that:

1. The app can be trusted to respect the intent of the users authorizing it. For example,
   • the developer is a respected member of the MediaWiki or Wikimedia community, or
   • the app is managed by a reputable IRL organization (university, NGO etc), or
   • the app source code is public, and it is likely that the website the callback URL points to is really running that code, or
   • the rights that the app is asking for are difficult to abuse ("Authentication only" or "basic rights" only can't really be used for anything abusive).
2. The rights requested by the app are reasonable, the need for them is explained, and the same use case cannot be covered in a different way with less rights.
3. The app is conscious about the privacy of the authorizing users. For example,
   • the app declares that it does not collect user data (and preferably it is open source so it's possible in theory to verify it), or
   • the app is hosted on Wikimedia Toolforge / Cloud VPS (which has a Terms of Use covering user data), or
   • the app has a privacy policy explaining how it handles user data.
4. The app isn't likely to be confused with another app, based on its name or description.
5. The app is likely to protect the secrecy of its secret key (unless OAuth 2 without the "Client is confidential" option is used).
   • The application should use HTTPS for the callback URL (or have a good reason for not doing so), and the URL is specific enough that only the app maintainers have access to it. (For example, https://my-oauth-app.com/ is fine. https://my-oauth-app.com is not fine as it would match https://my-oauth-app.com.evil.net as well. https://tools.wmflabs.org/my-oauth-app/ is fine, https://tools.wmflabs.org/ is too generic. For complex web applications, an exact URL is preferred over a prefix, as such applications might include open-redirect functionally which can be exploited to make the callback URL redirect to a different site.)
   • Apps which do not have any backend component (desktop applications, mobile apps, or "thick" javascript apps) should never be approved.
   • Exceptions can be made for example apps demoing OAuth usage, if they are clearly labeled as such and request very limited rights.

Disabling apps

Edits or other logged actions made by OAuth apps will be tagged. The tag name will be of the form OAuth CID: <number> and the visible name will be the name of the tool.

Apps that are malfunctioning, being abused, causing excessive server load, or otherwise burdening the projects, can be disabled at Special:OAuthManageConsumers/<app ID> (the ID can be found by searching Special:OAuthListConsumers or inspecting the link at Special:Tags). This is a safe action that can be undone later after the problem has been fixed. The user account that registered the app will get a notification but it is good form to send an explanatory message by some other means as well.

Apps not requiring review

Apps which have limited rights and cannot be effectively abused do not require review by OAuth admins but will be tagged and can be disabled like all other apps. Currently apps with the following grants belong to this category:

• "User identity verification only, no ability to read pages or act on a user's behalf"
• "User identity verification only with access to real name and email address, no ability to read pages or act on a user's behalf." (note that Wikimedia wikis do not use real names so there is no access to those)
• "Basic rights"

Apps that are meant to be installed separately for every user (e.g. mobile apps, browser plugins, desktop applications) must be registered individually by each user as owner-only. Apps registered as owner-only will only be able to act in the name of the user who registered them. Such registrations are not subject to review and actions performed by them will not be tagged. It is the responsibility of the user to make sure the app does not have the rights to do anything abusive, or can be trusted not to.