OAuth

The HTTP client tools all accept an optional oauth argument which when specified means the HTTP client request will be signed using the OAuth 1.0a standard before being issued.

The oauth argument must be transreptable to a set of OAuth credentials with the following form...

These credentials are all that is required to use OAuth and your service provider may be able to supply these to you without any other steps being necessary.

OAuth Authentication Workflow

If your service provider has an automated workflow for authenticating and generating credentials then a pair of accessors are provided for initiating and performing the retrieval of authenticated OAuth credentials.

The first step is to initiate the OAuth process by issuing an active:oauthPrepare request...

req = context.createRequest("active:oauthPrepare")
req.addArgument("settings", "res:/twitter-panel/resources/oauth/appSettings.xml")
prepareState = context.issueRequest(req)

The settings argument must have the following form...

Your OAuth service provider must provide you with a consumerKey and consumerSecret and also provide you with the locations of the three services required by the OAuth process.

The optional callbackURL is used to specify a callback address with which to send the PIN activation code. If not specified the server is expected to handle the providing the PIN "Out-of-Band" (OOB). This means the user is told it and they must manually cut and paste it.

The response from active:oauthPrepare is a serializable HDS structure containing some transient state. This representation is needed in the second stage but it may be persisted to an intermediate persistence mechanism if required.

Importantly the prepareState contains an HDS node with the path /hds/authorizeURL. This URL is the location to which you must tell the user to go to in order to authenticate themselves and to approve the OAuth connection request. Once approved, the provider will give the user a PIN activation code which is the final state required to complete the authentication process.

At this stage you now have: settings, prepareState and PIN activation code and with these three resources you are able to download the authenticated credentials using the active:oauthPrime accessor...

 
req = context.createRequest("active:oauthPrime")
req.addArgument("settings", "res:/twitter-panel/resources/oauth/appSettings.xml")
req.addArgumentByValue("prepareState", prepareState)
req.addArgumentByValue("validationCode", "THE USERS PIN CODE")
myOAuthCredentials = context.issueRequest(req)

The response from active:oauthPrime is the OAuth credentials as shown in the first section. These credentials should be stored and used to sign all subsequent requests to the service provider. Typically the credentials will be valid until the user deauthorizes them with the service provider - which may mean they are effective for a long time.

Example

A full example application using the OAuth tools to create a simple Twitter client app is available in the apposite repository. Go to apposite and search for "twitter".