OAuth/For Developers

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.

For a beginner-oriented introduction, see these slides.

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.
 * 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

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:

Application Approval

 * Wiki administrators will verify that OAuth applications are written by reputable developers, and the developers are intending to use OAuth correctly.
 * See the draft guidelines for apps on meta
 * 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

 * meta:Special:OAuthListConsumers

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= &oauth_consumer_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

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

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

as the redirect in the second leg of the handshake, you can hit

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.

PHP demo cli client with pre-shared secret

 * OAuth Hello World – easy to understand demo application written in PHP

PHP demo cli client with RSA keys
Before Starting:

Golang demo cli client with HMAC
Before you begin:

Python
Libraries:
 * flask-mwoauth, a Flask blueprint to run OAuth against MediaWiki's Extension:OAuth
 * MediaWiki-OAuth (mwoauth), on top of requests-oauthlib

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

Express
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.