This is a very simple "Hello world" program to show how to use OAuth. If you so desire, you may download this file. For a more end-user friendly version, look at enduser.php.

Overview

OAuth is a method for your application to act on behalf of a user on a website, without having to know the user's username and password. First your application is regisetered with the website, then you send the user to a special page on the website where they give your application permission, and then you provide special HTTP headers when accessing the website.

Creating your consumer

To be able to use OAuth in your application, you first need to register it as a consumer. To do this, you visit Special:OAuthConsumerRegistration on the OAuth central wiki. For WMF wikis, this is currently meta.wikimedia.org.

On this page, you will fill out information required by your application. Most of the fields are straightforward. Of the rest:

• OAuth "callback" URL: After the user authorizes the application, their browser will be sent to this URL. It will be given two parameters, oauth_verifier and oauth_token, which your application will need in order to complete the authorization process.
• Applicable wiki: If your app is only for use in one wiki, specify the wiki id here (this may be retrieved from the API with action=query&meta=siteinfo). If your app is for use on all wikis, specify "*" (without the quotes).
• Applicable grants: Check the checkbox for the grants that provide the rights your application needs. Note that "Basic rights" is almost certainly required, and that even if your application specifies advanced rights such as "Delete pages" your application will still not be able to delete pages on behalf of users who don't already have the delete right.
• Usage restrictions (JSON): This can be used to limit usage of your application, e.g. to certain IP addresses. The default value should be fine.
• Public RSA key: OAuth requires that requests be signed; this can be done by using a shared secret, or by using public-key cryptography. If you want to use the latter, provide a public key here.

After submitting your registration request, you will be returned a "consumer token" and a "secret token". In this Hello world program, these go in your ini file as consumerKey and consumerSecret. Note you can later update the Usage restrictions and Public RSA key, and can reset the secret token.

Your application must then be approved by someone with the "mwoauthmanageconsumer" user right.

Authorizing a user

When a new user wishes to use your application, they must first authorize it. You do this by making a call to Special:OAuth/initiate to get a request token, then send the user to Special:OAuth/authorize. If the user authorizes your app, the user will be redirected back to your callback URL with the oauth_verifier parameter set; you then call Special:OAuth/token to fetch the access token.

Deauthorizing a user

A user may revoke the authorization for the application by visiting Special:OAuthManageMyGrants on the OAuth central wiki.

Identifying a user

OAuth itself doesn't provide any way to reliably identify a user to the consumer. The MediaWiki OAuth extension can be queried for a JSON Web Token attesting to the identity of the authorized user.

Try it out!

• Authorize this application
• Post to your talk page
• Verify your identity
• Visit your talk page