Signing Web Service Requests

The Launchpad web service hacking document describes a lot of requests you can send to edge.launchpad.net. But if you send them in the simple form presented in that document, you'll get a response code of 401 ("Unauthorized"). Launchpad's web service only responds to requests that have been digitally signed with a particular Launchpad user's authorization key.

This doesn't have to be your key. You can have a simple script that uses your own Launchpad authorization key, but you can also run a website that gathers its users' authorization keys and makes requests to the web service on their behalf. This is safe because these authorization keys have nothing to do with your Launchpad password. They're a way of delegating a limited set of privileges to some other program. If a program proves untrustworthy, the user only needs to revoke that program's key.

The standard HTTP authentication mechanisms (Basic and Digest) aren't sophisticated enough to handle these cases. That's why Launchpad has adopted the OAuth standard for authentication. It's a little more work to set up than just sending your Launchpad username and password to the web service, but it's more versatile and more secure.

If you're writing a console-based script based on launchpadlib, you don't have to worry much about this. Launchpadlib will automatically open a browser window for your end-user and ask them to hit Return once they've granted your program access.

Otherwise, you'll need to implement a workflow like the one described below to get a set of Launchpad credentials for each of your users. The actual request signing is a mechanical process and there are lots of libraries to help you with it.

Getting credentials

A user can set up an authorization token from within Launchpad, by visiting http://www.launchpad.net/people/+me/+oauth-tokens. It's reasonable to ask your users to set up a token before they use your program, and provide their Launchpad credentials in a config file or as command-line arguments to your script. But you can also create a new set of credentials from within your application.

The basic workflow is always the same, but the details are different if you're writing a standalone application, versus creating a website.

Step 0: Pick a consumer key

The consumer key identifies your application and it should be hard-coded somewhere in your code. Everyone who uses your application will send the same consumer key.

We recommend you choose the name of your program as the consumer key. Don't append the version number unless you want your users to get new application keys for every new version. For this example I'll use the consumer key 'myconsumerkey'.

Step 1: Get a request token

Getting your program's user to create a new credential for the program is a multi-step process. The request token is a unique string that Launchpad uses to keep track of your program between steps.

To obtain a request token, send a POST request to https://edge.launchpad.net/+request-token. (Note: *not* api.edge.launchpad.net!) This is the same kind of POST a web browser does when it submits a form. You should submit the following values in form-URLencoded format.

• oauth_consumer_key: Your consumer key
• signature_method: The string "PLAINTEXT"

• oauth_signature: The string "&".

So the HTTP request might look like this:

    POST /+request-token HTTP/1.1
    Host: edge.launchpad.net
    Content-type: application/x-www-form-urlencoded

    oauth_consumer_key=just+testing&signature_method=PLAINTEXT&oauth_signature=%26

The response should look something like this:

    200 OK

    oauth_token=9kDgVhXlcVn52HGgCWxq&oauth_token_secret=jMth55Zn3pbkPGNht450XHNcHVGTJm9Cqf5ww5HlfxfhEEPKFflMqCXHNVWnj2sWgdPjqDJNRDFlt92f

Save these two pieces of information, oauth_token and oauth_token_secret: you'll need them to sign the request in step 3.

Step 2: Authenticate the user

Now the user needs to 1) log in to Launchpad, and 2) tell Launchpad how much authority they're delegating to your program. You need to get them to visit the following URL in their web browser:

    https://edge.launchpad.net/+authorize-token?oauth_token={oauth_token}

Where oauth_token is the string you got at the end of step 1.

Step 2a: If you're building a website

If your program is a website that your users visit, you can send them an HTTP redirect. Be sure to also specify the oauth_callback field as a URL on your website.

    https://edge.launchpad.net/+authorize-token?oauth_token={oauth_token}&oauth_callback={URL to within your website}

Once the user delegates some of their privileges to your website Launchpad will redirect the user back to that URL, so that they can resume using your site.

Step 2b: If you're writing a stand-alone program

If your program runs on the clients' computer rather than through their web browser, you don't have to worry about redirecting back to your web page. But you do have to worry about opening the Launchpad page in their web browser in the first place. Take a look at the open_url_in_browser() function defined in launchpadlib's launchpad.py; it works well on most Linux systems. Just open up their web browser to the +authorize-token page.

If your program isn't running in the web browser, how are you supposed to know when the user is done with the +authorize-token page? There's no 'oauth_callback' equivalent that Launchpad can use to send a signal to your client-side program. What you need to do is have the end-user themselves tell you when they're done with the +authorize-token page.

The launchpadlib library prints an explanatory message after it opens +authorize-token in your web browser. It waits for the end-user to authorize access through their web browser, and then switch back to the launchpadlib window and hit return. If you're writing a GUI program, you can have the end-user click a button once they're done authorizing your program to talk to Launchpad on their behalf.

For an example of good interface design around these constraints, look at F-Spot's Flickr integration. The first time you export a photo to Flickr you need to click an "Authorize" button. This opens up a web browser to a page on Flickr. You log in to Flickr and authorize F-Spot to access the Flickr web service on your behalf. Then you go back to F-Spot and click a "Complete Authorization" button. After that point, F-Spot can talk to Flickr with your credentials.

(Flickr doesn't use OAuth, but its system has the same architecture as OAuth, so the user interface can work the same way.)

Step 3: Exchange the request token for an access token

The oauth_token and oauth_token_secret you got in Step 1 are real OAuth keys that can be used to sign requests, but you're only going to use them once. Their only purpose is to remind Launchpad who you are; remember, it hasn't heard from you since step 1. Once the user has delegated some of their authority to you, you need to exchange these temporary credentials for permanent credentials that has the end-user's permissions associated with them.

If you're writing a website, you'll know you're ready when Launchpad redirects your user back to the URL you specified as oauth_callback. If you're writing a client-side program, you'll know when your user clicks the "Complete Authorization" button or hits enter or whatever it was you told them to do when they were done on the Launchpad side.

Now you make a POST request to https://edge.launchpad.net/+access-token. The body should be a set of form-encoded parameters, as in Step 1. You need to provide the following parameters:

• oauth_token: The same as oauth_token from step 1

• oauth_consumer_key: The same as in step 1
• oauth_signature_method: The string "PLAINTEXT"

• oauth_signature: The OAuth signature, calculated using the PLAINTEXT algorithm and the oauth_token_secret' from step 1

The last one is the tricky one. The OAuth standard has the details, but basically you take the string '&' and stick the oauth_token_secret you got at the end of step 1 onto the end. (The reason you start with the string '&' is that Launchpad doesn't use OAuth Consumer Secrets.)

So your POST request should look like this:

    POST /+access_token
    Host: edge.launchpad.net
    Content-type: application/x-www-form-urlencoded

    oauth_signature=%26jMth55Zn3pbkPGNht450XHNcHVGTJm9Cqf5ww5HlfxfhEEPKFflMqCXHNVWnj2sWgdPjqDJNRDFlt92f&oauth_consumer_key=just+testing&oauth_token=9kDgVhXlcVn52HGgCWxq&oauth_signature_method=PLAINTEXT

    200 OK
    oauth_token=PsK9cpbll1KwehhRDckr&oauth_token_secret=M2hsnmsfEIAjS3bTWg6t8X2GKhlm152PRDjLLmtQdr9C8KFZWPl9c8QbLfWddE0qpz5L56pMKKFKEfv1&lp.context=None

Put those two pieces of information, oauth_token' and oauth_token_secret, in some persistent storage. You'll need them as part of every request you make to Launchpad's web service.

Using the credentials

Now that you've got an access token and a secret for a particular Launchpad user, you won't have to go through that again for that user. But there's still the matter of digitally signing your requests with that token.

Unlike the process of getting credentials, which is pretty specific to Launchpad, the process of digitally signing a request is completely mechanical. The mechanics are covered in detail in the OAuth standard, and there are also OAuth libraries in most popular programming languages that can sign an HTTP request given an access token and secret. So I'm not going to go into much detail on how to actually sign a request. It's a general problem and there are plenty of places to go if you need help, and lots of sample code to look at.