OAuth

From VZ Developer Wiki
(Redirected from OAuth Use Cases)
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth


This page is based on http://wiki.opensocial.org/index.php?title=OAuth_Use_Cases

Template:Version

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.

For our OpenSocial REST and RPC API we use the OAuth 1.0 Revision A specification for authorization (see http://oauth.net/core/1.0a/) together with the OAuth Body Hash 1.0 specification (see http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html)

The 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 OpenSocial 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 OpenSocial Client Libraries. For more information on the signing process see http://oauth.net/core/1.0a/#signing_process. 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!

You can obtain a consumer key and consumer secret in our developer sandbox. For a gadget (Two-legged OAuth on REST Api and Signature Verification on Callbacks) a consumer key and secret are generated automatically.

Creating independent keys for a three-legged OAuth access to the REST API is not possible at the moment.

OAuth client libraries

Fortunately there are already client libraries available for several languages. You can find a list of client libraries at http://code.google.com/p/oauth/ or http://oauth.net/code/. Keep in mind, that you may have to activate OAuth Body Hash generation or implement this part yourself, when the library does not support this.

There are also some dedicated OpenSocial Client libraries available that already implement an OAuth library. These are mostly compatible with the OpenSocial implementation of VZ-Netzwerke (see Client_Libraries).

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

Oauth signed.png
  1. A gadget running in a social network wishes to transmit data to a remote server. The gadget is configured to use Data Pipelining, gadgets.io or osapi.http methods to specify a signed request.

  2. The request is sent to the container first, which adds the appropriate social data (e.g. Viewer and OwnerID, 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.

Oauth legend.png


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. This is done when a user installs an application on the social network, they are asked to share their data with the application in form of a special vcard, which would allow the application server to access that user's data via 2-legged OAuth.

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.

Since the user already has the gadget installed he authorized the gadget and its backend to request his data.

From the backend you just have to call the REST API with your Consumer Key, sign it with your Secret and add a xoauth_requestor_id parameter token with the OpenSocial ID on whose behalf you request the data. Note that the OpenSocial ID has to match your Consumer/Gadget.

Request
oauth_consumer_key:The Consumer Key.
oauth_signature_method: The signature method the Consumer used to sign the request.
oauth_signature: The signature
oauth_timestamp: timestamp
oauth_nonce: unique nonce
xoauth_requestor_id: OpenSocial ID on whose behalf you perform the operation

Request Flow

Oauth 2legged 01.png
  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.


Oauth 2legged 02.png
  1. 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.


Oauth 2legged 03.png
  1. 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.

Oauth legend.png



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.

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.

When a user first visits your application, they have not yet been authenticated. To authenticate them, your application performs the following general steps:

  1. Send a request to the social network site to acquire a generic OAuth "request token."
  2. Request
    oauth_consumer_key: The Consumer Key.
    oauth_signature_method: The signature method the Consumer used to sign the request.
    oauth_signature: The signature
    oauth_timestamp: timestamp
    oauth_nonce: unique nonce
    oauth_callback: An absolute URL to which VZ will redirect the User back when the Obtaining User Authorization step is completed.
    Response
    oauth_token: The Request Token.
    oauth_token_secret: The Token Secret.
  3. Send the user to the social network's authorization page so that they can authorize your request for access. After the user authorizes the request, the social network sends the user back to your client, using a URL that you specify. The request token that you acquired in step 1 is now authorized.
  4. Request
    oauth_token: The Request Token.
    fields: optional comma seperated list of fields, that the user should grant permission to retrieve
    message: optional message that will be displayed to the user in the grant permission step
    Response
    oauth_token: The Request Token the User authorized or denied.
    oauth_verifier: The verification code.
  5. Send a request to the social network site to upgrade the authorized request token to an access token.
  6. Request
    oauth_consumer_key: The Consumer Key.
    oauth_signature_method: The signature method the Consumer used to sign the request.
    oauth_signature: The signature
    oauth_timestamp: timestamp
    oauth_nonce: unique nonce
    oauth_token: The Request Token the User authorized or denied.
    oauth_verifier: The verification code.
    Response
    oauth_token: The Access Token.
    oauth_token_secret: The Token Secret.
  7. Store the access token securely, for future use.
  8. Use the access token to perform actions on the user's behalf.
  9. Request
    oauth_consumer_key:The Consumer Key.
    oauth_token:The Access Token.
    oauth_signature_method: The signature method the Consumer used to sign the request.
    oauth_signature: The signature
    oauth_timestamp: timestamp
    oauth_nonce: unique nonce

Request Flow

Oauth 3legged.png
  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.

Oauth legend.png

Endpoints