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[edit]

  • 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[edit]

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

Signatures and TLS[edit]

  • 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[edit]

  • 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[edit]

  • 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[edit]

The Protocol Flow[edit]


Attached Application Responsibility[edit]

  • 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[edit]

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![edit]

PHP demo cli client with pre-shared secret[edit]

PHP demo cli client with RSA keys[edit]

Before Starting:

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

Golang demo cli client with HMAC[edit]

Before you begin:

$ go get github.com/mrjones/oauth



Ruby: OmniAuth strategy[edit]

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