OAuth use cases

Owned by Mark Halvorson (Deactivated)
Last updated: Nov 16, 2010 by Jonathan Beri (Unlicensed)Version comment

The OAuth protocol was designed to allow secure API authorization and is used by OpenSocial. This page provides a high level overview of the different ways that OAuth and OpenSocial work together.

The http://oauth.net/ OAuth website contains detailed information about implementing OAuth, but most OpenSocial developers will not need to concern themselves with the exact details of implementing OAuth, since the [a:Client Libraries ] are designed to perform most of these actions transparently.

Keys and Certificates

Overview

The OAuth specification says that requests must be signed in a way so that the recipient of the request can verify that the sender is who they claim to be and that the request has not been modified in any way since it was signed.

To sign an OAuth request, all the parameters included in the request are gathered, arranged in a defined way, and cryptographically hashed into a string of random-looking characters. Verifying a signature follows a similar approach.

Consumer Key & Secret

The exact details of the signing process aren't covered here because this is handled automatically by the Client Libraries . To configure the client libraries, however, you will typically need what's known as an OAuth Consumer Key and OAuth Consumer Secret. When making requests, these values identify your application to the social network. For this reason, the consumer secret for your application should not be made public!

To obtain a consumer key and secret, most social networks offer an administration page or tool for verifying the ownership of a gadget. Below is a list of some containers which offer an OAuth consumer key and secret to developers:

Container

OAuth Consumer Key/Secret Location

Google containers (orkut, iGoogle, Gmail)

Use Google's Gadget Verification Tool to find the consumer key and secret for your gadget.

MySpace

Navigate to the My Apps page and click "Edit Details" on the app you wish to obtain the key and secret for.

Public Certificates

In some cases, a container will not support the Consumer Key and Secret, and will sign requests using a public/private key system. To validate such requests, you will need the container's public key certificate. For your convenience, there is a list of public keys for each container available at https://opensocialresources.appspot.com/certificates/ along with links to each certificate. This site is for convenience only and not approved by the containers listed! For the best security, be sure to check your container's documentation to verify the location of the appropriate public key!

OAuth Signed Requests

Overview

OAuth defines a method of signing requests so that a recipient can verify that the request was not tampered with while in transit. While signing is only a small portion of the OAuth specification, OpenSocial uses this approach to allow third party developers to verify that social data passed to their servers was sent from a specific container.

Uses

  • Pass social data from a gadget to an application server.
  • Request data from an application server to display in a gadget.

Request Flow

  1. A gadget running in a social network wishes to transmit data to a remote server. The gadget is configured to use Data Pipelining or osapi.http methods to specify a signed request.
  2. The request is sent to the container first, which adds the appropriate social data (so this data cannot be modified by the gadget) and signs the request using OAuth's signing mechanism.
  3. The application server gets the request and is able to verify that it was not tampered with during transit. The application server can then respond with application data for the gadget to display.

OpenSocial and 2-legged OAuth

Overview

The two "legs" in 2-legged OAuth represent a Social network and an Application server. Using the 2-legged protocol, these two servers are able to securely exchange information through OAuth signed requests. However, there is no authorization step involved in 2-legged OAuth, which means that the application server must already have permission to access the data it is requesting from the social network. In the case of user-specific data, this is usually done in a separate channel. For example, when a user installs an application on a social network, they are asked to share their data with the application, which would allow the application server to access that user's data via 2-legged OAuth.

Some OpenSocial operations like the Invalidation API are application-specific, not user-specific, and therefore don't need special permission from a user. Such operations can usually be made directly through the use of a 2-legged call.

Uses

  • Background processing for a gadget
    • Example: A turn-based game gadget wants to notify a user via a message when it's their turn to play the game.

Request Flow

<ac:macro ac:name="unmigrated-wiki-markup"><ac:plain-text-body><![CDATA[

1. A social application server wants to access data from or post messages to a social network on behalf of a given user. The request is denied because the application does not have permission to perform this action.

]]></ac:plain-text-body></ac:macro>

<ac:macro ac:name="unmigrated-wiki-markup"><ac:plain-text-body><![CDATA[

2. Through other channels, the user becomes aware of the application and installs it on the social network. The network confirms that the user wishes to share their social data with the application.

]]></ac:plain-text-body></ac:macro>

<ac:macro ac:name="unmigrated-wiki-markup"><ac:plain-text-body><![CDATA[

3. Now when the application server attempts to access the user's social data, the social network sees that the user has granted the application permission to access this data, so the request is granted. ]]></ac:plain-text-body></ac:macro>
<ac:macro ac:name="unmigrated-wiki-markup"><ac:plain-text-body><

]]></ac:plain-text-body></ac:macro>

OpenSocial and 3-legged OAuth

Overview

The three "legs" in OpenSocial 3-legged OAuth typically represent a Social network, an Application server, and the Application user. In this model, a website, mobile application, or desktop application wishes to use social data in a context outside of the social network. Because there is no gadget install process involved, 3-legged OAuth provides a method for the user to grant the application access to their data on the social network without sharing the user's username and password for the social network with the application.

Additionally, some OpenSocial containers may implement what is known as an "OAuth Proxy", which allows gadgets running inside of a social network to access OAuth-protected resources. An example of this is the MySpace gadget which runs inside of iGoogle - iGoogle provides an OAuth proxy which accesses MySpace's OAuth-protected APIs. The proxy takes care of storing tokens which should not be stored inside of the gadget itself, and signing the outgoing requests. More information about iGoogle's OAuth Proxy can be found here

Uses

  • Accessing social data from a website.
    • Example: Writing a stand-alone website and want access to a user's friend list, activity stream, or messages on another site to enable social features.
  • Mobile or desktop applications.
    • Example: Writing a mobile or desktop application and want to access a user's friend list, activity stream, or messages from a native mobile or desktop application.
  • Accessing traditional 3-legged OAuth services from within a gadget
    • Example: Writing a JavaScript gadget that needs to securely communicate with a 3rd party web service such as Google Data APIs or MySpace.

Request Flow

  1. A user wishes to use their social network data inside of a third party website or application. The application server contacts the social network, but does not have the user's account information, and does not have permission to access the user's data.
  2. The social network responds with information that the application server uses to redirect the user's web browser to a special login page on the social network's domain.
  3. If the user is logged out of the social network, they input their username and password as if they were normally logging into the site. After they log in, or if they were already logged in (with a cookie), they are asked by the social network to share data with the application.
  4. Once permission has been granted, the social network redirects the user's web browser to a predefined URL on the application server, along with a token that can be used to access the user's information.
  5. Using the token as described in the OAuth specification, the application server is now able to access the user's data on the social network.