Oauth 2: Client and Service Side Flow

Choosing an authentication flow

Yammer now supports both Yammer OAuth 2 (legacy) and Azure Active Directory (AAD) tokens for v1 REST endpoints. As a developer, you need to choose between these token types depending on your requirements.

The legacy tokens and authentication flow are still required when you need to:

• Access Yammer external networks, or other networks as a Yammer network-level guest, from an application.
• Use Yammer APIs from a background service or daemon needing a long-lived token.
• Support legacy freemium Yammer networks and users.

Yammer OAuth 2 (legacy) flow

The OAuth 2.0 flow is typically initiated by a user clicking a “Sign in with Yammer” button on your app’s login page. The end result is a token that your app will use to write activity (push data) to Yammer, and retrieve information from Yammer (pull data). The token is unique to each app/user combination. Please note that OAuth 2.0 requires HTTPS.

There are two OAuth 2.0 flows:

1. Server-Side Flow: Referred to as “Authorization Code Grant” in the OAuth 2.0 Specification, the server-side flow should be used whenever you need to call the Yammer API from your web application server.
2. Client-Side Flow: Referred to as “Implicit Grant” in the OAuth 2.0 Specification, the client-side flow should be used when you need to make API calls from a client, such as JavaScript running in a web browser or from a native mobile or desktop application.

Both flows involve these three steps:

1. User Authentication: Ensures that the user is who they say they are.
2. App Authorization: Ensures that the user knows that they are allowing your app to access their data.
3. App Authentication: Ensures that the user is giving their information to your app and not someone else’s app.

Server-Side Flow

This is a step-by-step tutorial of how the Yammer Server-Side OAuth 2.0 flow works:

1. User Authentication

When the user clicks a “Sign in with Yammer” button on your app’s login page, the user should be redirected to Yammer’s OAuth 2.0 dialog at: https://www.yammer.com/oauth2/authorize?client_id=[:client_id]&response_type=code&redirect_uri=[:redirect_uri]

The Client_id and redirect_uri are avaialble in theh app that you registered. The redirect_uri should match the Redirect URI entered in the app registration page.

Also, make sure to specify the response_type, which in this case is code. If the user is already logged in, Yammer will validate that the session cookie has been stored in the user’s browser, authenticating the user. If the user is not logged in, they will be prompted to enter their sign in credentials.

2. App Authorization

Once Yammer has successfully authenticated the user, the OAuth 2.0 dialog will prompt the user to authorize the app. If the user clicks “Allow”, your app will be authorized.

The OAuth 2.0 dialog will redirect the user’s browser via HTTP 302 to the redirect_uri with an authorization code:

https://[:redirect_uri]?code=[:code]

If the user presses Deny, your app will not be authorized. The OAuth 2.0 dialog will still redirect via HTTP 302 to the redirect_uri with error information:

https://[:redirect_uri]?error=[:error]&error_description=[:error_description]

error – string. The error type, example: “access_denied”.

error_description – string. A more fully formed human readable error, example: “The user denied your request”.

3. App Authentication

Next, submit a POST request on the OAuth 2.0 Token Endpoint, passing in the authorization code (you received above), client_id and client_secret (found on app configuration page), in the request body. The endpoint is:

POST https://www.yammer.com/oauth2/access_token?client_id=[:client_id]&client_secret=[:client_secret]&code=[:code]&grant_type=authorization_code

Yammer will return an access token object as part of the response, which includes user profile information. From this object, parse out and store the “token” property. This token will be used to make subsequent API calls to Yammer.

Response Body returned by Yammer including the access token object:

{
  "user":
  {
    "timezone": "Hawaii",
    "interests": null,
    "type": "user",
    "mugshot_url": "https://www.yammer.com/yamage-backstage/photos/…",
    "kids_names": null,
    "settings": {
      "xdr_proxy": "https://stagexdrproxy.yammer.com"
    },
    "schools": [],
    "verified_admin": "false",
    "birth_date": "",
    "expertise": null,
    "job_title": "",
    "state": "active",
    "contact": {
      "phone_numbers": [],
      "im": {
        "provider": "",
        "username": ""
      },
      "email_addresses": [
        {
          "type": "primary",
          "address": "[email protected]"
        }
      ]
    },
    "location": null,
    "previous_companies": [],
    "hire_date": null,
    "admin": "false",
    "full_name": "TestAccount",
    "network_id": 155465488,
    "stats": {
      "updates": 2,
      "followers": 0,
      "following": 0
    },
    "can_broadcast": "false",
    "summary": null,
    "external_urls": [],
    "name": "clientappstest",
    "network_domains": [
      "yammer-inc.com"
    ],
    "network_name": "Yammer",
    "significant_other": null,
    "id": 1014216,
    "web_url": "https://www.yammer.com/yammer-inc.com/users/…",
    "url": "https://www.yammer.com/api/v1/users/101416",
    "guid": null
  },
  "access_token": {
    "view_subscriptions": true,
    "expires_at": null,
    "authorized_at": "2011/04/06 16:25:46 +0000",
    "modify_subscriptions": true,
    "modify_messages": true,
    "network_permalink": "yammer-inc.com",
    "view_members": true,
    "view_tags": true,
    "network_id": 155465488,
    "user_id": 1014216,
    "view_groups": true,
    "token": "ajsdfiasd7f6asdf8o",
    "network_name": "Yammer",
    "view_messages": true,
    "created_at": "2011/04/06 16:25:46 +0000"
  },
  "network": {
    "type": "network",
    "header_background_color": "#0092bc",
    "community": false,
    "navigation_background_color": "#3f5f9e",
    "navigation_text_color": "#ffffff",
    "permalink": "yammer-inc.com",
    "paid": true,
    "show_upgrade_banner": false,
    "name": "Yammer",
    "is_org_chart_enabled": true,
    "id": 155465488,
    "header_text_color": "#000000",
    "web_url": "https://www.yammer.com/yammer-inc.com"
  }
}

Once the token expires, you will need to re-run the steps above to generate a new code and access_token. If the user has already authorized your app they will not be prompted to do so again.

If there is an issue authenticating your app, the authorization server will issue an HTTP 400 and return the error in the body of the response.

{
  "error": {
    "type": "OAuthException",
    "message": "Error validating verification code."
  }
}

Client-Side Flow

The Client-Side Flow also uses the OAuth 2.0 dialog for user authentication and app authorization. The only difference is that you must specify the response_type parameter with a value of “token” when invoking the dialog.

GET https://www.yammer.com/dialog/oauth?client_id=[:client_id]&redirect_uri=[:redirect_uri]&response_type=token

Once the user is authenticated and authorizes to your application, the browser will be redirected to the redirect_uri, rather than being passed an authorization code (via the code parameter) as in the server-side flow, the access token is passed.

https://[:redirect_uri]#access_token=[:access_token]

Because the access token is passed in a URI fragment, only client-side code (such as JavaScript executing in the browser, or desktop code hosting a web control) can retrieve the token. App authentication is handled by verifying that the redirect_uri is in the same domain as the Site URL you specified during app registration.