Developer’s Guide: Data API Protocol – OAuth for Web Applications

Developer’s Guide: Data API Protocol – OAuth for Web Applications

The OAuth protocol provides a standard way to access protected data on different websites. Whereas the AuthSub and ClientLogin methods are Google-specific, OAuth is an open protocol that can be implemented on other websites. Like AuthSub, OAuth is useful if you are building a web application that will let users link videos, comments, ratings, contacts or other information to their own YouTube accounts. OAuth may be particularly appealing to you if your application also integrates with other APIs besides the YouTube API, and those APIs also support the OAuth protocol. See http://oauth.net to learn more about Oauth.

This page explains how to use the OAuth protocol to submit authenticated YouTube API requests. This page contains the following sections:

Understanding OAuth Tokens

OAuth authentication uses two types of tokens:

  • A request token ensures that an end user authorizes your application to submit API operations on the user’s behalf. YouTube also uses the request token to verify that you have registered your application with Google.
  • An access token enables your application to execute YouTube Data API operations on a particular user’s behalf.

Note: Your application must obtain unique request and access tokens for each user. In addition, your application needs a mechanism to store access tokens for future use.

The authentication process has three stages:

  1. Your application retrieves an unauthorized request token. Google verifies that you have registered your application before returning the token. Request tokens are only valid for one hour.
  2. Your application redirects the user to a Google login page. The redirect URL specifies the unauthorized request token value retrieved in step 1 as well as a callback URL.After the user logs in to her YouTube account, Google displays a page that lets the user choose whether to allow your application to perform YouTube API operations on her behalf. If the user grants your application this access, the unauthorized token will become an authorized token. (The token value does not change.) The user will also be redirected to the callback URL that you specified.
  3. Your application exchanges the authorized request token for an access token. Only authorized tokens can be exchanged, and each request token can only be exchanged one time. The access token is associated with a single user account, and your application should use that token to submit authenticated API requests on that user’s behalf.

Setting up OAuth authentication

You must complete the following steps to enable your web application to authenticate users with the OAuth protocol:

  1. Register your web application with Google.Please see the Registration for Web-Based Applications page for an explanation of the registration process and the requirements for registration.

    Note: All requests to obtain or use an OAuth token must be signed. Google supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.

    • If your application uses the RSA-SHA1 signature algorithm, you will need to upload a security certificate to Google during the registration process.
    • If your application uses the HMAC-SHA1 signature algorithm, leave the certificate field blank when completing your registration. Google will generate an OAuth consumer secret value, which will display on your domain’s registration page after you have completed the registration process. You will then use this value to sign requests.
  2. Set up a mechanism to manage OAuth tokens.After your application obtains an OAuth access token from YouTube, your application will use that token for YouTube API requests it makes on behalf of the user associated with that token. As such, your application will need to store tokens and track the user for whom each token is valid. Your application should not try to retrieve a new access token each time the application needs to interact with YouTube on a particular user’s behalf. In fact, tokens should be treated as securely as any other sensitive user information that your application stores.

Using OAuth

As described in the Understanding OAuth tokens section, the OAuth authentication process has three steps. These steps are explained in the following sections:

Step 1: Obtaining a request token

To obtain a request token, send a signed request to https://www.google.com/accounts/OAuthGetRequestToken. Include the following parameters in your request. Note that the only optional parameter is oauth_version; all other parameters are required.

Parameter Description
oauth_consumer_key This value specifies the domain associated with your application and must be the same as the domain that you registered with Google.
oauth_signature_method This value specifies the signature algorithm used to sign the request. Supported values for this parameter are RSA-SHA1 and HMAC-SHA1.
oauth_signature This value specifies the string (signature) generated using the referenced signature method. See the Signing requests that use OAuth authentication section for more information.
oauth_timestamp This value specifies the time that the request was sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce This value is a random, 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version This value specifies the OAuth version that Google should use to handle your request. The default value is 1.0. If your request includes this parameter, the parameter’s value must be 1.0.
scope This value identifies the service that you are trying to access to make authenticated requests. This parameter is Google-specific and is not defined in the OAuth standards. Set the parameter value to http://gdata.youtube.com.

There are three ways to specify these parameters:

  • Include them in the Authorization header of a GET or POST request. The sample request below demonstrates how to specify these values in the Authorization header. Note that the scope parameter cannot be specified in the header. The scope can be specified as a query parameter in the request URL or in the body of a POST request.
  • Specify them in the body of a POST request. If you choose this method, you must set the value of the Content-Type request header to application/x-www-form-urlencoded.
  • Include them as query parameters in the request URL of a GET request.

For more details, see the OAuth specification, (section 5.2).

Sample Request

The example asks for a request token to access a user’s Calendar and Picasa accounts.

POST /accounts/OAuthGetRequestToken HTTP/1.1
Host: https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"

scope=http://gdata.youtube.com

About the response

If the request is successful, Google responds with an HTTP 200 message containing a request token and a token secret. Your application needs to parse the token from the response.

If the request is unsuccessful, Google responses with an HTTP 400 message (Bad Request). This response may indicate that the request is poorly formed, meaning it may have an unsupported or missing parameter, unsupported signature method or other error in the request format. This response may also indicate that Google has reason to believe the requester is not acting in good faith.

The following example shows a response to a successful request for a request token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Step 2: Authorizing a request token

After you retrieve a request token, redirect the user to https://www.google.com/accounts/OAuthAuthorizeToken. Add the following query parameters to the URL:

Parameter Description
oauth_token This required parameter specifies the request token obtained from Google.
oauth_callback This optional parameter specifies the URL to which the user will be redirected after granting your application access to the user’s YouTube account. The URL can include query parameters. If you do not specify a callback URL, Google displays a page confirming that the user’s token has been authorized. Note that providing a callback URL may create a more seamless user experience by automatically redirecting the user back to your application after the user completes the login process.

Sample Request

The following example shows a request to authorize an unauthorized token:

https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&oauth_callback=http%3A%2F%2Fwww.example.com

About the response

If Google accepts the request, the user will be redirected to a YouTube login page. After the user logs in, the Authentication service displays a page to inform the user that your application wants to access the user’s YouTube account. The page prompts the user to confirm that your application can access the user’s account.

If the user grants access to your application, she will be redirected to the callback URL specified in your request to authorize the request token. If the user denies access, she will be redirected to a page that displays a link back to your site and a link to YouTube.

The following URL shows the format of a redirect back to the callback URL with an authorized request token. The authorized token has the same value as the unauthorized token sent in the request. The value is a text string, up to 256 bytes.

http://www.example.com/ytapi.html?oauth_token=CKF50YzIHxCT85KMAg

Step 3: Exchanging a request token for an access token

After authorizing the request token for a user, your application can exchange that token for an access token. An access token lets you submit authenticated YouTube API requests on a specific user’s behalf. Access tokens do not expire, effectively functioning like AuthSub session tokens.

To exchange an authorized request token for an access token, send a signed HTTP request to https://www.google.com/accounts/OAuthGetAccessToken with the following query parameters. Note that all of these parameters except for the oauth_token parameter are also used (and used in the same context) in the request to obtain a request token. In addition, the only optional parameter is oauth_version; all other parameters are required.

Parameter Description
oauth_consumer_key This value specifies the domain associated with your application and must be the same as the domain that you registered with Google. This value must be the same as the one provided in the request to obtain the request token.
oauth_token This value specifies the authorized request token.
oauth_signature_method This value specifies the signature algorithm used to sign the request. Supported values for this parameter are RSA-SHA1 and HMAC-SHA1.
oauth_signature This value specifies the string (signature) generated using the referenced signature method.
oauth_timestamp This value specifies the time that the request was sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce This value is a random, 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version This value specifies the OAuth version that Google should use to handle your request. The default value is 1.0. If your request includes this parameter, the parameter’s value must be 1.0.

Your application can use the same three mechanisms to specify these parameters as it can use to specify parameters when obtaining a request token.

Sample Request

The following example exchanges a request token for an access token:

POST /accounts/OAuthGetAccessToken HTTP/1.1
Host:  https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_token="CKF50YzIHxCT85KMAg",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"

About the response

Google responds to a successful request for an access token with an HTTP 200 message that contains an access token and a token secret. The following example shows a sample response containing an OAuth access token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Google may reject a token request if it is poorly formed or if Google has reason to believe the requester is not acting in good faith. If the request is not successful, Google will return an HTTP 400 (Bad Request) response code.

Signing requests that use OAuth authentication

You must sign all API requests that retrieve or use an OAuth token. This requirement applies to calls to obtain a request token or an access token as well as to any YouTube Data API requests that require authentication, such as uploading a video or adding a rating to a video.

The following steps explain how to generate a signature for requests that use OAuth authentication:

  1. Use the oauth_signature_method parameter to specify the signature algorithm that the request uses. Google supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.
  2. Construct a signature base string, which consists of three request elements that are concatenated using ampersand (&) characters. Note that all parameter names and values must be encoded as described in the OAuth Specification (section 5.1).
    • The first element specifies the HTTP request method (GET, POST, etc.).
    • The second element specifies the base URL for the request. The URL must not include any query parameters. For example, if the request URL is http://gdata.youtube.com/feeds/api/videos?q=football&orderby=published&v=2, then the base URL is http://gdata.youtube.com/feeds/api/videos.
    • The third element contains a normalized string of the parameter and parameter values in the request. The string should include any query parameters specified in the request URL as well as all of the OAuth parameters except for the oauth_signature parameter. The OAuth Specification (section 9.1.1), explains how to normalize the string.
  3. Generate an oauth_signature using the specified oauth_signature_method.
    • If you are using RSA-SHA1, generate the signature using the private key that corresponds to the certificate that you uploaded to Google during the registration process.
    • If you are using HMAC-SHA1, generate the signature using the “consumer secret” value generated during the registration process. (The value is displayed on your domain’s registration page.

The OAuth Specification (appendix A.5) provides a sample request that can be used to test HMAC-SHA1 signatures. The example includes a signature base string and HMAC-SHA1 key as well as the generated HMAC-SHA1 digest (signature).

Note: For more detailed information about signing an OAuth request, please see the OAuth Specification (section 9).

Process flow diagram

The following diagram illustrates the steps involved in authenticating a user using the OAuth protocol. Like AuthSub and ClientLogin authentication, OAuth authentication can be used with either direct uploading or browser-based uploading.

The image shows the following steps:

  1. The user clicks a link on your site to perform an API operation that requires authentication.
  2. Your application determines whether you have an OAuth access token stored for the user. If you do have an access token, your application would skip ahead to step 14. If you do not have an access token, your application would proceed to step 3.
  3. Your application submits a signed request to obtain a request token from Google’s OAuth authentication service.
  4. Google responds to your request with an unauthorized request token, which you parse from the response.
  5. Your application redirects the user to the YouTube account authentication service. The redirect URL identifies the unauthorized request token and a callback URL.
  6. The user’s browser handles the redirect by sending a request to YouTube’s account authentication service.
  7. The YouTube account authentication service displays an Access Consent page, prompting the user to log in to a YouTube account and grant or deny the ability for your application to perform API operations for that account.
  8. The user logs in and grants account access to your application.
  9. If the user grants access, YouTube redirects the user back to the callback URL that you included in the URL in step 6. The user could also deny account access, in which case YouTube would display a page with links back to your application and to the YouTube website.
  10. The user’s browser handles the redirect and sends a request to your callback URL. The redirect URL contains the authorized request token value. (The authorized request token has the same value as the unauthorized request token.)
  11. Your application submits a signed request to YouTube’s OAuth authentication service to exchange the request token for an access token.
  12. YouTube responds to your request with an access token.
  13. Your application parses the access token from the response and stores the token value, which is associated with a particular user. In the future, your application will use that same access token to make authenticated requests for the same user.
  14. Your application submits an API request using the access token to authenticate the request.

Leave a Reply

Leave a Reply