sMash, Twitter and OAuth

Here’s a little example sMash app showing how to authenticate with Twitter using OAuth. If you’re not familiar with OAuth, here’s a good introduction (part II is especially useful).

This example uses the signpost OAuth library. The code is based on this simple signpost example.

Note: This sample won’t work out of the box on z/OS CICS due to what seems to be a minor issue in the signpost library. To work around this, for now you’ll need patched versions of the signpost classes in the app’s /classes directory. Let me know if you need a hand with this.

Getting the sample app

Add the soal.org repo to your modulegroup and create a new app from the sample app:

 zero modulegroup addurl http://soal.org/sMash/repo
 zero create myTwitterOAuth from soal:twitterOAuth

Alternatively, just download the zipped app. The code is also on GitHub.

Before you start it up

Authenticated applications access data directly from twitter.com on behalf of a Twitter user. In other words, a user tells Twitter that they grant the app the right to access their Twitter account. For this reason, apps must be individually registered with Twitter.

You can register apps on dev.twitter.com. For each app you register, you get an OAuth key and security token, which the app must use to identify itself with Twitter. You should register your instance of this app with Twitter to get your own tokens and replace the existing ones in config/zero.config.

This app illustrates both the PIN and the callback approach to OAuth verification. With the callback approach, the User is redirected back to a URI in the app after they have granted the app permission to access their account on twitter.com. Twitter does some basic sanity checks on the URIs it’s dealing with, so the callback mechanism will only work if the domain on which the app is running matches the domain of the callback URI registered with twitter. If you’re running the app from your workstation, you might want to register a callback URI off of 127.0.0.1. Note that Twitter doesn’t access the callback URI directly – it’s a location to which the user’s browser is redirected.

How it works

This simple example allows the app to access a single twitter account at a time. It consists of 4 scripts in /public. Here’s an overview of how they work together. Steps 1-3 only need to be done once.

    1. index.groovy checks to see whether the app is already authorised to access a twitter account. Initially this isn’t the case, so you get a choice of trying out the PIN or the callback mechanism to authorize the app.
    2. Depending on your choice, either usePIN.groovy or useCallback.groovy obtains a “Request Token” from Twitter, which it uses to initiate the authentication process on twitter.com. Both scripts then lead to verify.groovy – usePIN.groovy does so via a form submission and useCallback.groovy does so via a redirect from twitter.com.
    3. At this point, the user has authorised the app to access Twitter using their account. The last step is for the app to retrieve an “Access Token” from twitter.com, which it uses to perform operations on twitter.com the user’s behalf. verify.groovy does this and persists the Access Token the application’s global context Storage zone.
    4. If you follow the link back to index.groovy, it now displays the raw mentions data for the authorised account, using the tokens that were stored in the Storage zone in step 3. If you like, you can clear out this data and start again from step 1 by following the link to index.groovy?refresh=true.

Leave a comment