OAuth Ruby Tutorial

From Justin.tv API Wiki

OAuth is a bit tricky to get setup, so here is a tutorial to help explain how to get started using OAuth and Justin.tv.

Contents 1 Advantages of using OAuth 2 Getting Started as a Developer 3 Using Two-Legged OAuth: Making Requests on Behalf of Your Application 4 Using Three-Legged OAuth: Making Requests on Behalf of Users

Advantages of using OAuth

For developers:

• Users are more willing to sign you in if they don't have to give up their username and password
• You will be featured in a directory of applications on Justin.tv (when we come out of beta)

For users:

• Securely allow and revoke permissions from applications

Getting Started as a Developer

First, you'll need to create an application on Justin.tv. Make sure that your Justin.tv user is enabled as a developer (for now, you'll have to ask a Justin.tv Staff Member in the Google Group for that). Once enabled as a developer, you should see a link to Applications on your JTV home page. This page will allow you to admin your applications.

Create a new application. The Application URL should be a URL that explains your app, and you can leave the Support and Callback URLs blank for now.

Once your app is created, you will need two things: your application's Consumer Key and Consumer Secret. The Consumer Key and Consumer Secret are like a username and password for your application to access the REST API with.

Using Two-Legged OAuth: Making Requests on Behalf of Your Application

OAuth is primarily designed to allow 3rd party developers to do actions on behalf of authenticated users. The JTV API also uses Two-Legged OAuth to allow applications to sign requests, basically validating that those requests come from the application. Because this is secure validation, requests made under Two-Legged OAuth (and normal, Three-Legged OAuth, are subject to a higher rate limit).

Signing a request for Two-Legged OAuth just means omitting the user token and secret. Here is an example in ruby on how to use the oauth gem to make a signed request:

require 'rubygems'
require 'oauth'

# make the consumer out of your secret and key
consumer_key = "GZqz7iOeYourKey4mqSyLQ"
consumer_secret = "MZQP66s5YourSecretHereP9n4nA1U"
consumer = OAuth::Consumer.new(consumer_key, consumer_secret,
                               :site => "http://api.justin.tv",
                               :request_token_path => "/oauth/request_token",
                               :authorize_path => "/oauth/authorize",
                               :access_token_path => "/oauth/access_token",
                               :http_method => :get)

# make the access token from your consumer
access_token = OAuth::AccessToken.new consumer

# make a signed request!
access_token.get("/user/show/justin.xml")

This will produce a request with an Authorization header that look like this:

OAuth oauth_nonce="dpEo4uet0kZ3rgMt0IN8sQcUn4M1qxZImMvuv6Mo", oauth_signature_method="HMAC-SHA1", oauth_token="", oauth_timestamp="1241120484", oauth_consumer_key="GZqz7iOeYourKey4mqSyLQ", oauth_signature="xIJPB8JRjjA6WYhztT7mUWVYtz4%3D"

Note that for Two-Legged OAuth the token is an empty string, because the token is provided by an authenticated user, and in this case we're making a request from API Consumer to Justin.tv directly, with no user involved. OAuth signatures in the third party case are created from two pieces of secret information, Consumer Secret and Token Secret, but in this case we only use the Consumer Secret.

For more info, check out this beginner's guide to signing OAuth requests.

Using Three-Legged OAuth: Making Requests on Behalf of Users

Three-Legged, or Normal OAuth, is more complicated. It requires that you get a Request Token and put the user through the step of authenticating you on the Justin.tv site, by way of a redirection on your site. As in the previous example, we will use the ruby oauth gem to walk through the process.

require 'rubygems'
require 'oauth'

# like in the above example, you'll want to create a consumer
consumer_key = "GZqz7iOeYourKey4mqSyLQ"
consumer_secret = "MZQP66s5YourSecretHereP9n4nA1U"
consumer = OAuth::Consumer.new(consumer_key, consumer_secret,
                               :site => "http://api.justin.tv",
                               :request_token_path => "/oauth/request_token",
                               :authorize_path => "/oauth/authorize",
                               :access_token_path => "/oauth/access_token",
                               :http_method => :get)

# then you'll start the process by requesting a request token from Justin.tv
# you'll want to send the user along with an oauth_callback parameter, which will be the url
# that your user will be sent to after they authenticate
request_token = consumer.get_request_token
session[:request_token] = request_token
redirect_to request_token.authorize_url + "&oauth_callback=" + CGI.escape("http://my.url.com")

Here's a demonstration: http://explorer.justin.tv:3000/

Once the user returns after authorizing:

access_token = request_token.get_access_token
# make a GET request
get_results = access_token.get "/api/user/show/justin.xml"
# make a POST request
post_results = access_token.post "/api/user/update.xml", { "name" => "Justin Kan" }

For more info, check out this comprehensive OAuth guide.