Using OAuth

Info for the experts

So, you're an expert? Perhaps you helped write the spec... this section is for you. Here's the relevant urls:

• To get a request token: https://getsatisfaction.com/api/request_token
• Redirect users to: https://getsatisfaction.com/api/authorize?oauth_token=XXX to authorize a request token
• To exchange an authorized request token to get an access token: https://getsatisfaction.com/api/access_token

A note about using the OAuth Rubygem

You'll notice that the methods we use for granting access to the API are not within the api.getsatisfaction.com domain. The current version (0.2.2) of the OAuth rubygem has bugs in the higher-level features (such as Consumer#get_request_token) that are not compatible with the configuration that we use. Be cautious of this, and rely on things like HttpRequest#oauth! methods to sign your http calls directly. I'm working on a patch to solve this issue but have not yet been able to complete it.

Logging in a user using OAuth

An annoying aspect of using Get Satisfaction for your companies support is the disconnect between your login system and ours. Many users don't understand that they need an account in each place. To facilitate some reduction of confusion, I've implemented a system that will allow you to use OAuth to automatically login users from your application into ours.

Using this system you will be able to craft a special url that will log a user into the appropriate Get Satisfaction account and redirect them on through to their destination. You could, for example, allow users of your system to link their accounts to our accounts so they don't need to login to satisfaction when they want to ask a question about your service.

Overview of the steps

1. Getting an access token: first you need to have your user grant access to act on their behalf. Using the normal OAuth interaction, generate and store an access token/secret in your database.
2. Generating the special url: You will then use this access token/secret to general an authenticated OAuth call to https://getsatisfaction.com/session/from_oauth.
3. Using the special url in a link: Render a link in your page to this special url, and if/when the user clicks on the link, they will be logged into satisfaction if they aren't already.

Getting an access token

Nothing different here than any OAuth token exchange. Get a request token, redirect user to the authorization page, exchange request token for access token. You will want to store this access token in your database, attached to the user account in your system who is currently signed in to your application. This token represents the link between your user accounts and Get Satisfaction's accounts.

Generating a special url

So, you create a url, signed properly with the Access Token retrieved in step 1. The url will be to https://getsatisfaction.com/session/from_oauth, and you will want to sign it as a GET request. Since this url will be embedded into a link, you won't be able to use the Authorization HTTP header method, and so you should use the query string to supply the appropriate OAuth variables (token, nonce, signature, timestamp, signature method, consumer key, etc.).

Care should be taken to not cache this url in your rendered html, since the first person to follow the link will be logged in as the attached user.

To redirect the user into a specific page in satisfaction, you can supply an additional query string parameter. By specifying redirect=blah in the query string, Get Satisfaction will redirect the user on through to the url specified in the parameter after setting all of the appropriate cookies to keep a user logged into satisfaction. Don't forget to include the redirect parameter (if used) when calculating the signature used for OAuth verification.

Please note that at present any cookies set using this method will always be session cookies; the user will be logged out of Get Satisfaction when they close their browser. Enabling persistent cookies is a possible feature, if enough people want it.

An alternative, better method

The method described above is less than ideal since it can interfere with caching strategies, so I propose a slightly more intensive procedure. The "embed a url" method is nice because it requires almost no effort above the initial effort to support being an OAuth consumer in your system.

The alternative is to extend your application to act as a gateway for satisfaction. You will create action on your site that will redirect the user through to the special url described above. Let's use a real world example... iwantsandy.com simply has the "community" link in their application point to their Get Satisfaction community:

If they wanted their users to be automatically logged into their satisfaction accounts when they clicked that link they could:

1. switch that link to https://iwantsandy.com/community
2. https://iwantsandy.com/community would, if the currently logged user has an access token, form the special url using the token and redirect the browser to https://getsatisfaction.com/session/from_oauth?redirect=https://getsatisfaction.com/iwantsandy. If not, it just redirects them into https://getsatisfaction.com/iwantsandy.
3. ??????
4. PROFIT!!

As you can see, this method requires some implementation work over OAuth support. That said, compared to actually supporting OAuth the effort is trivial to implement the redirection gateway. In exchange, you don't actually expose any user specific information in your rendered HTML and can feel more safe in the notion that you aren't compromising your customers trust with allowing you access to their data on Get Satisfaction.