OAuth/For Developers

From MediaWiki.org
Jump to: navigation, search

If you are developing a bot or similar application where the same consumer is always used with the same user account, you might prefer the simpler OAuth/Owner-only_consumers.

OAuth Security Provisions

  • MediaWiki users can allow other websites to edit and perform other actions using the MediaWiki api on their behalf.
  • The attached website does not share the user's password, instead they are issued a unique token and secret to make calls on behalf of the user.
  • The access is limited to explicit sets of permissions (“grants”) for the application.[1]
  • Users can revoke their authorization of an attached application at any time.
  • Administrators can reject entire applications at any time.

MediaWiki Specific Provisions

  • Extension:OAuth implements an /identify function to allow the attached application to identify the authorizing user[2]

Signatures and TLS

  • For OAuth 1.0a, all interactions between MediaWiki and the attached application are signed with either a shared secret (using HMAC-SHA1), or RSA signature.
  • If shared secrets are used, the attached application must use TLS when negotiating the shared secret.
  • If RSA is used, TLS is not required (except for the initial registration)

Intended Users

  • Websites that want to take actions on MediaWiki on behalf of their users
  • Bots
  • Websites that want to use MediaWiki as an identity provider for authentication (using the extension's /identity method, which is not standard OAuth)
  • But not...
    • Desktop applications (the Consumer Secret needs to be secret!). Some alternatives are being considered. See past discussions: [1] [2]

Application Approval

  • Wiki administrators will verify that OAuth applications are written by reputable developers, and the developers are intending to use OAuth correctly.
  • Application developers must apply to have their application (Consumer) approved at meta:Special:OAuthConsumerRegistration/propose
  • A user with the oauth-admin right must approve the application (currently users in the oauthadmin group)
  • Your MediaWiki user can authorize your app while waiting for approval, so as a developer, you can start integrating your app immediately, without waiting for approval (you'll just have to get approval before other users can authorize your app)

Browse approved and proposed applications

The Protocol Flow


Attached Application Responsibility

  • Establish user's session
  • Special:OAuth/initiate - get a temporary (request) token
  • Redirect the user's browser to Special:Oauth/authorize?oauth_token=<temp token>&oauth_consumer_key=<your app's key>
  • The user will be redirected back the the url you registered
  • Special:OAuth/token – get the authorized (access) token for this user
  • Set an Authorization: header when calling api.php with oauth_version, oauth_nonce, oauth_timestamp, oauth_consumer_key, oauth_token, oauth_signature_method, oauth_signature


OAuth is now available in your MediaWiki-Vagrant development environment. Add the oauth role, and your wiki will be able to authorize OAuth apps.

$ vagrant roles enable oauth
$ vagrant provision

Avoid repetitive login prompts

If your application doesn't persist sessions on the user-end, you might be repetitively prompting them to go through the OAuth approval screen. There's a better way! Instead of hitting

/w/index.php?title=Special:OAuth/authorize as the redirect in the second leg of the handshake, you can hit /w/index.php?title=Special:OAuth/authenticate

instead. This won't prompt the user to approve your application but instead just directly reach your callback url after a redirect.

Note: This only works when:

  • The user has already authorized your application at least once before.
    • If the application has not been authorized previously the normal dialog will be seen.
  • Your tool has access to either "Authentication only with access to real name and email address via Special:OAuth/identify, no API access." or "Authentication only, no API access." grants.

Demo Time!

PHP demo cli client with pre-shared secret

PHP demo cli client with RSA keys

Before Starting:

$ openssl genrsa -out appkey.pem 4096
$ openssl rsa -in appkey.pem -pubout > appkey.pub

Golang demo cli client with HMAC

Before you begin:

$ go get github.com/mrjones/oauth



Ruby: OmniAuth strategy

For Ruby, you can use this MediaWiki strategy for OmniAuth (available under the MIT License): https://github.com/timwaters/omniauth-mediawiki also available as a gem: https://rubygems.org/gems/omniauth-mediawiki



If you're using Express JS using OAuth is pretty straightforward thanks to the npm modules passport-mediawiki-oauth and oauth-fetch-json . The former will help you effortlessly add login via MediaWiki to your application whereas the latter will allow you to make authenticated requests to the API.

Weekipedia, A full scale React.js port of the Wikipedia mobile site uses both.


  1. "Separation of Concerns", wikitech-l, June 2013
  2. https://gerrit.wikimedia.org/r/#/c/93859/ , Add OAuth identify method, November 2013