Authentication

After registering your app, the next step is to authenticate your app to connect to Yammer with the user’s Yammer credentials. The authentication is an OAuth 2 flow that is initiated from your app.

Login Button

If you are using JavaScript, the simplest way to authenticate is to use the “Login with Yammer” button. Please refer to the JavaScript SDK to learn more about this.

yammer-signin

OAuth 2

The OAuth 2 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 your app will use to write activity to Yammer and retrieve Yammer data. The token is unique to each app/user combination. Please note that OAuth2 requires HTTPS.

There are two OAuth flows:

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.

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 three steps:

User authentication - ensures that the user is who they say they are.

App authorization - ensures that the user knows that they are allowing your app to access their data.

App authentication –  ensures that the user is giving their information to your app and not someone else’s.

Server-Side Flow

Here is a step-by-step tutorial of how the Yammer server-side OAuth 2 flow works:

A. User Authentication

When the user clicks a “Sign in with Yammer” button on your app’s login page, redirect them to Yammer’s OAuth dialog at:

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

`client_id` and `redirect_uri` are available in the app that you registered. For dynamic URIs, the domain of the `redirect_uri` should match the Redirect URI entered in the app registration page. For static URIs, the full `redirect_uri` should match.

“Sign in with Yammer” from Sched.do app home page

SchedoLargeLogin-1024x539

If the user is already logged in, Yammer will validate the session cookie that it has stored in the user’s browser, authenticating the user. If the user is not logged in, they will be prompted to enter their credentials.

Oauth dialog launched on clicking “Sign in with Yammer”

Oauth2Login-1024x649

B. App Authorization

Once Yammer has successfully authenticated the user, the OAuth dialog will prompt them to authorize the app. If the user clicks “Allow”, your app will be authorized. The OAuth dialog will redirect the user’s browser via HTTP 302 to the redirect_uri with an authorization code:

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

Oauth2Login-1024x649

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

http://[: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”.

C. App Authentication

Next, submit a POST on the OAuth Token Endpoint, passing in the authorization code you got above and your app secret which is available in the app that you registered. The endpoint is:

https://www.yammer.com/oauth2/access_token.json?client_id=[:client_id]&client_secret=[:client_secret]&code=[: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 is long lived (years) and 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": "test@yammer-inc.com"
        }
      ]
    },
    "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 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

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

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

http://[: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.

Making API Requests

With a valid access token, your app can make calls to any Yammer API endpoint by sending the access token as a “Bearer” token in the “Authorization” request header.

GET /api/v1/messages/following.json HTTP/1.1 
Host: www.yammer.com 
Authorization: Bearer abcDefGhi

For more details on the “Bearer” token refer to http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-23

If the access token expires or the user de-authorizes your app, the API request will return an HTTP 401 with the following error in the body of the response.

{
  "response": {
    "message": "Token not found.",
    "code": 16,
    "stat": "fail"
  }
}

Your app can request a new access token by re-running the appropriate flow if this error occurs.

OAuth Impersonation

Impersonation allows you to request a valid access token on behalf of a user for your app. This action is restricted to verified admin users in paid Yammer networks. Here are the API endpoints for this:

GET https://www.yammer.com/api/v1/oauth/tokens.json

Generates (if necessary) and returns a list of authorized OAuth access tokens for each network which the user is a member. Supports the following parameters:

`user_id` – string. The user_id of the user on behalf of whom you are generating the access tokens.

`consumer_key` – string. The app’s consumer key which is available in the app that you registered.

Verified Admins may use the user_id and consumer_key parameters to generate tokens on behalf of other users. Non admins cannot use the parameters thus getting back oauth tokens for each network they are a part of.

POST https://www.yammer.com/api/v1/oauth.json

This action is restricted to verified admins only. It supports the “user_id” and “consumer_key” parameters and returns a preauthorized OAuth access token for a given user_id/consumer_key combination.

Generate a test access token

Below are steps to generate an OAuth token, for testing purposes, using your browser.

1. Sign up for Yammer @ https://www.yammer.com (no gmail/hotmail/yahoo).

2. Go to https://www.yammer.com/client_applications and register a new app.

3. Navigate to “Basic Info” on the left hand side and fill out the “Redirect URI” with: “https://www.yammer.com”

RedirectURI

 

4. Copy your Client ID, Redirect URI from the Application Information page.

ClientId

 

5. Paste this url into your browser, where client_id, redirect uri are the values obtained from step 4 above:
https://www.yammer.com/dialog/oauth?client_id=[:client_id]&redirect_uri=[:redirect_uri]

6. Copy the “code=” value from the URL created.

7.  Paste this url into your browser, where client_id, client secret are obtained in step 4 above. Code is the code from step 6.
https://www.yammer.com/oauth2/access_token.json?client_id=[:client_id]&client_secret=[:client_secret]&code=[:code]

8. Copy the “token:” value from the resulting JSON.

9. You can try out the resulting token with the following endpoint , sending the token as a bearer token as shown above.
https://www.yammer.com/api/v1/messages.json