{"__v":6,"_id":"546b916b62515a14007ebc4b","category":{"__v":5,"_id":"545138eaa66f020800dbab4a","project":"545137a814af501a00b50cf9","version":"545137a814af501a00b50cfc","pages":["5451398d14af501a00b50d17","546b916b62515a14007ebc4b","546b91a862515a14007ebc4d","546b91c8b47b5d1400109ef6","546b91dab47b5d1400109ef8"],"createdAt":"2014-10-29T18:58:50.759Z","from_sync":false,"order":2,"slug":"authentication","title":"Authentication"},"project":"545137a814af501a00b50cf9","user":"5433099f9a2b451a00ad4531","version":{"__v":9,"_id":"545137a814af501a00b50cfc","project":"545137a814af501a00b50cf9","createdAt":"2014-10-29T18:53:28.525Z","releaseDate":"2014-10-29T18:53:28.525Z","categories":["545137a814af501a00b50cfd","545138eaa66f020800dbab4a","546b9072b47b5d1400109edf","546b9082b47b5d1400109ee0","546b9088b47b5d1400109ee1","546b909462515a14007ebc43","546b90a0b47b5d1400109ee2","546ced235884600e007a92f6","5481008eea7fd40b00cd7c2b"],"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["54ee52a1c622200d00ac0a18"],"createdAt":"2014-11-18T18:35:23.289Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"order":1,"body":"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.\n\n**There are two OAuth 2.0 flows for Yammer:**\n*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.\n*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.\n\n**Both flows involve these three steps:**\nA. User Authentication: Ensures that the user is who they say they are.\nB. App Authorization: Ensures that the user knows that they are allowing your app to access their data.\nC. App Authentication:  Ensures that the user is giving their information to your app and not someone else’s app.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Server-Side Flow\"\n}\n[/block]\nThis is a step-by-step tutorial of how the Yammer Server-Side OAuth 2.0 flow works:\n\n\n**A. User Authentication**\n\nWhen 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://www.yammer.com/oauth2/authorize?client_id=[:client_id]&response_type=code&redirect_uri=[:redirect_uri]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n`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. Also, make sure to specify the `response_type`, which, in this case is `code`\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://www.filepicker.io/api/file/l9wSy20QFo7Sgc7ZBZ7g\",\n        \"SchedoLargeLogin-1024x539.png\",\n        \"1024\",\n        \"539\",\n        \"#2a9ee4\",\n        \"\"\n      ],\n      \"caption\": \"“Sign in with Yammer” from Sched.do app home page\"\n    }\n  ]\n}\n[/block]\nIf 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://www.filepicker.io/api/file/fkcR76hiRlqdYMvFBXO7\",\n        \"Oauth2Login-1024x649.png\",\n        \"1024\",\n        \"649\",\n        \"#2f6f97\",\n        \"\"\n      ],\n      \"caption\": \"Oauth 2.0 dialog launched on clicking “Sign in with Yammer”\"\n    }\n  ]\n}\n[/block]\n**B. App Authorization**\n\nOnce 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://[:redirect_uri]?code=[:code]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIf 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://[:redirect_uri]?error=[:error]&error_description=[:error_description]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n`error` – string.  The error type, example: “access_denied”.\n\n`error_description` – string. A more fully formed human readable error, example: “The user denied your request”.\n\n\n**C. App Authentication**\n\nNext, 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://www.yammer.com/oauth2/access_token\\nclient_id=[:client_id]&client_secret=[:client_secret]&code=[:code]&grant_type=authorization_code\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYammer 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.\n\n*Response Body returned by Yammer including the access token object* \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"user\\\":\\n  {\\n    \\\"timezone\\\": \\\"Hawaii\\\",\\n    \\\"interests\\\": null,\\n    \\\"type\\\": \\\"user\\\",\\n    \\\"mugshot_url\\\": \\\"https://www.yammer.com/yamage-backstage/photos/…\\\",\\n    \\\"kids_names\\\": null,\\n    \\\"settings\\\": {\\n      \\\"xdr_proxy\\\": \\\"https://stagexdrproxy.yammer.com\\\"\\n    },\\n    \\\"schools\\\": [],\\n    \\\"verified_admin\\\": \\\"false\\\",\\n    \\\"birth_date\\\": \\\"\\\",\\n    \\\"expertise\\\": null,\\n    \\\"job_title\\\": \\\"\\\",\\n    \\\"state\\\": \\\"active\\\",\\n    \\\"contact\\\": {\\n      \\\"phone_numbers\\\": [],\\n      \\\"im\\\": {\\n        \\\"provider\\\": \\\"\\\",\\n        \\\"username\\\": \\\"\\\"\\n      },\\n      \\\"email_addresses\\\": [\\n        {\\n          \\\"type\\\": \\\"primary\\\",\\n          \\\"address\\\": \\\"test@yammer-inc.com\\\"\\n        }\\n      ]\\n    },\\n    \\\"location\\\": null,\\n    \\\"previous_companies\\\": [],\\n    \\\"hire_date\\\": null,\\n    \\\"admin\\\": \\\"false\\\",\\n    \\\"full_name\\\": \\\"TestAccount\\\",\\n    \\\"network_id\\\": 155465488,\\n    \\\"stats\\\": {\\n      \\\"updates\\\": 2,\\n      \\\"followers\\\": 0,\\n      \\\"following\\\": 0\\n    },\\n    \\\"can_broadcast\\\": \\\"false\\\",\\n    \\\"summary\\\": null,\\n    \\\"external_urls\\\": [],\\n    \\\"name\\\": \\\"clientappstest\\\",\\n    \\\"network_domains\\\": [\\n      \\\"yammer-inc.com\\\"\\n    ],\\n    \\\"network_name\\\": \\\"Yammer\\\",\\n    \\\"significant_other\\\": null,\\n    \\\"id\\\": 1014216,\\n    \\\"web_url\\\": \\\"https://www.yammer.com/yammer-inc.com/users/…\\\",\\n    \\\"url\\\": \\\"https://www.yammer.com/api/v1/users/101416\\\",\\n    \\\"guid\\\": null\\n  },\\n  \\\"access_token\\\": {\\n    \\\"view_subscriptions\\\": true,\\n    \\\"expires_at\\\": null,\\n    \\\"authorized_at\\\": \\\"2011/04/06 16:25:46 +0000\\\",\\n    \\\"modify_subscriptions\\\": true,\\n    \\\"modify_messages\\\": true,\\n    \\\"network_permalink\\\": \\\"yammer-inc.com\\\",\\n    \\\"view_members\\\": true,\\n    \\\"view_tags\\\": true,\\n    \\\"network_id\\\": 155465488,\\n    \\\"user_id\\\": 1014216,\\n    \\\"view_groups\\\": true,\\n    \\\"token\\\": \\\"ajsdfiasd7f6asdf8o\\\",\\n    \\\"network_name\\\": \\\"Yammer\\\",\\n    \\\"view_messages\\\": true,\\n    \\\"created_at\\\": \\\"2011/04/06 16:25:46 +0000\\\"\\n  },\\n  \\\"network\\\": {\\n    \\\"type\\\": \\\"network\\\",\\n    \\\"header_background_color\\\": \\\"#0092bc\\\",\\n    \\\"community\\\": false,\\n    \\\"navigation_background_color\\\": \\\"#3f5f9e\\\",\\n    \\\"navigation_text_color\\\": \\\"#ffffff\\\",\\n    \\\"permalink\\\": \\\"yammer-inc.com\\\",\\n    \\\"paid\\\": true,\\n    \\\"show_upgrade_banner\\\": false,\\n    \\\"name\\\": \\\"Yammer\\\",\\n    \\\"is_org_chart_enabled\\\": true,\\n    \\\"id\\\": 155465488,\\n    \\\"header_text_color\\\": \\\"#000000\\\",\\n    \\\"web_url\\\": \\\"https://www.yammer.com/yammer-inc.com\\\"\\n  }\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nOnce 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.\n\nIf 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"error\\\": {\\n    \\\"type\\\": \\\"OAuthException\\\",\\n    \\\"message\\\": \\\"Error validating verification code.\\\"\\n  }\\n}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Client-Side Flow\"\n}\n[/block]\nThe 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET https://www.yammer.com/dialog/oauth?client_id=[:client_id]&redirect_uri=[:redirect_uri]&response_type=token\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nOnce 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"http://[:redirect_uri]#access_token=[:access_token]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nBecause 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.","excerpt":"","slug":"oauth-2","type":"basic","title":"OAuth 2: Server & Client-Side Flow"}

OAuth 2: Server & Client-Side 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 for Yammer:** *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 these three steps:** A. User Authentication: Ensures that the user is who they say they are. B. App Authorization: Ensures that the user knows that they are allowing your app to access their data. C. App Authentication: Ensures that the user is giving their information to your app and not someone else’s app. [block:api-header] { "type": "basic", "title": "Server-Side Flow" } [/block] This is a step-by-step tutorial of how the Yammer Server-Side OAuth 2.0 flow works: **A. 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: [block:code] { "codes": [ { "code": "https://www.yammer.com/oauth2/authorize?client_id=[:client_id]&response_type=code&redirect_uri=[:redirect_uri]", "language": "text" } ] } [/block] `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. Also, make sure to specify the `response_type`, which, in this case is `code` [block:image] { "images": [ { "image": [ "https://www.filepicker.io/api/file/l9wSy20QFo7Sgc7ZBZ7g", "SchedoLargeLogin-1024x539.png", "1024", "539", "#2a9ee4", "" ], "caption": "“Sign in with Yammer” from Sched.do app home page" } ] } [/block] 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. [block:image] { "images": [ { "image": [ "https://www.filepicker.io/api/file/fkcR76hiRlqdYMvFBXO7", "Oauth2Login-1024x649.png", "1024", "649", "#2f6f97", "" ], "caption": "Oauth 2.0 dialog launched on clicking “Sign in with Yammer”" } ] } [/block] **B. 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: [block:code] { "codes": [ { "code": "http://[:redirect_uri]?code=[:code]", "language": "text" } ] } [/block] 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: [block:code] { "codes": [ { "code": "http://[:redirect_uri]?error=[:error]&error_description=[:error_description]", "language": "text" } ] } [/block] `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 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: [block:code] { "codes": [ { "code": "POST https://www.yammer.com/oauth2/access_token\nclient_id=[:client_id]&client_secret=[:client_secret]&code=[:code]&grant_type=authorization_code", "language": "text" } ] } [/block] 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* [block:code] { "codes": [ { "code": "{\n \"user\":\n {\n \"timezone\": \"Hawaii\",\n \"interests\": null,\n \"type\": \"user\",\n \"mugshot_url\": \"https://www.yammer.com/yamage-backstage/photos/…\",\n \"kids_names\": null,\n \"settings\": {\n \"xdr_proxy\": \"https://stagexdrproxy.yammer.com\"\n },\n \"schools\": [],\n \"verified_admin\": \"false\",\n \"birth_date\": \"\",\n \"expertise\": null,\n \"job_title\": \"\",\n \"state\": \"active\",\n \"contact\": {\n \"phone_numbers\": [],\n \"im\": {\n \"provider\": \"\",\n \"username\": \"\"\n },\n \"email_addresses\": [\n {\n \"type\": \"primary\",\n \"address\": \"test@yammer-inc.com\"\n }\n ]\n },\n \"location\": null,\n \"previous_companies\": [],\n \"hire_date\": null,\n \"admin\": \"false\",\n \"full_name\": \"TestAccount\",\n \"network_id\": 155465488,\n \"stats\": {\n \"updates\": 2,\n \"followers\": 0,\n \"following\": 0\n },\n \"can_broadcast\": \"false\",\n \"summary\": null,\n \"external_urls\": [],\n \"name\": \"clientappstest\",\n \"network_domains\": [\n \"yammer-inc.com\"\n ],\n \"network_name\": \"Yammer\",\n \"significant_other\": null,\n \"id\": 1014216,\n \"web_url\": \"https://www.yammer.com/yammer-inc.com/users/…\",\n \"url\": \"https://www.yammer.com/api/v1/users/101416\",\n \"guid\": null\n },\n \"access_token\": {\n \"view_subscriptions\": true,\n \"expires_at\": null,\n \"authorized_at\": \"2011/04/06 16:25:46 +0000\",\n \"modify_subscriptions\": true,\n \"modify_messages\": true,\n \"network_permalink\": \"yammer-inc.com\",\n \"view_members\": true,\n \"view_tags\": true,\n \"network_id\": 155465488,\n \"user_id\": 1014216,\n \"view_groups\": true,\n \"token\": \"ajsdfiasd7f6asdf8o\",\n \"network_name\": \"Yammer\",\n \"view_messages\": true,\n \"created_at\": \"2011/04/06 16:25:46 +0000\"\n },\n \"network\": {\n \"type\": \"network\",\n \"header_background_color\": \"#0092bc\",\n \"community\": false,\n \"navigation_background_color\": \"#3f5f9e\",\n \"navigation_text_color\": \"#ffffff\",\n \"permalink\": \"yammer-inc.com\",\n \"paid\": true,\n \"show_upgrade_banner\": false,\n \"name\": \"Yammer\",\n \"is_org_chart_enabled\": true,\n \"id\": 155465488,\n \"header_text_color\": \"#000000\",\n \"web_url\": \"https://www.yammer.com/yammer-inc.com\"\n }\n}", "language": "text" } ] } [/block] 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. [block:code] { "codes": [ { "code": "{\n \"error\": {\n \"type\": \"OAuthException\",\n \"message\": \"Error validating verification code.\"\n }\n}", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Client-Side Flow" } [/block] 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. [block:code] { "codes": [ { "code": "GET https://www.yammer.com/dialog/oauth?client_id=[:client_id]&redirect_uri=[:redirect_uri]&response_type=token", "language": "text" } ] } [/block] 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. [block:code] { "codes": [ { "code": "http://[:redirect_uri]#access_token=[:access_token]", "language": "text" } ] } [/block] 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.