Background

A security problem was recently identified in version 1.0 of the OAuth spec. As you know, Yammer uses OAuth to authenticate API clients to access data on behalf of Yammer users. The security advisory is available here: http://oauth.net/advisories/2009-1 and Yammer's security bulletin was posted here: https://www.yammer.com/company/yammer_and_oauth

Temporary Change to Yammer API

As an immediate fix to mitigate the problem presented by this vulnerability, we have added a step to the three-legged OAuth authentication flow. This extra step ensures that Yammer is not vulnerable to the problem, but it deviates from the OAuth standard slightly and is subject to change when an official revision to the OAuth spec is released in the coming weeks.

Full details of the security problem are available at the links provided, but in short, the session fixation problem allowed an attacker to trick a victim into authorizing a request token known to the attacker, which could then be exchanged by the attacker for a valid access token tied to the victim's account. Properly exploited, an attacker simply needed to convince a victim to follow a link to the middle of the authentication flow and press the "Authorize" button. Yammer is adding a verification code to the process, and your application will need to provide it when exchanging an authorized request token for an access token. This verification code ensures that the person authorizing a request token is the same person who exchanges it for an access token.

Note that this change only affects the process users take to authorize your application. Any users who have already authorized your application to work with their account will be able to continue using your application without taking any action.

As a frame of reference, we'll use the OAuth authentication flow documented here: http://oauth.net/core/1.0/#anchor9. The change we're making affects steps D and E in the diagram. In step D -- after a user authorizes a request token -- a verification code will be generated and associated in our system with that request token. In step E -- exchanging this request token for an access token -- your application will need to provide that verification code back to us.

There are two ways in which your application will receive the verification code from us, depending on whether your application has been vetted by our security team. For untrusted API clients, the user will be presented with a page after authorizing which gives them the verification code. Your application will need to provide a UI for the user to type in the verification code, which you can then pass along in step E. For trusted API clients, we will allow you to register a callback URL that we will associate with your OAuth consumer key. All users authorizing request tokens associated with your consumer key will then be redirected to your callback URL, and the verification code will be passed as a CGI parameter named "callback_token". The rest of the flow is the same; you will provide the verification code in step E.

To send the verification code back to Yammer when requesting an access token, use the CGI parameter "callback_token". The code is not case-sensitive and should be alphanumeric with no punctuation or whitespace.

It is unfortunate that developers will need to take these extra steps, but it was necessary to ensure the security of Yammer user accounts. We will keep you updated as the OAuth spec is further refined. As always, we appreciate you working with us and welcome your feedback.

Example: Yammer Desktop Client

Here is how the new OAuth authorization flow works in the Yammer Desktop Client. The steps that differ from the normal OAuth protocol are highlighted in red.

1. The user opens the client in unauthorized state, the user then clicks on the button to initiate the OAuth authorization process.
2. The user's browser opens and after they log into Yammer they are directed to the Authorization Page for the Desktop Client. The user clicks the authorize button.
3. The browser is redirected to a new page that informs the user that the Authorization was successful, and also displays a 4 character code and tells the user to return to the application and enter the code.
4. The Desktop Application displays a text box to the user so that they can enter the code.
5. The user enters the provided code and clicks "Start Application". In the background, the desktop client makes a request to exchange the request token for an access token and passes the request token and the code that the user entered (the callback token).
6. If the token exchange is successful, the application fetches the user's messages via the API.