Yammer API auth with Files in SharePoint Online

October 14, 2019

The original article is published on the Microsoft Tech Community Yammer Blog.

Screen Shot 2019-10-14 at 10.42.10 AM.pngYammer Files in SharePointWe have recently changed auth requirements for third-party apps to conduct operations on Yammer files API, with Yammer files moving to SharePoint Online. We’re providing advance notice to help you prepare for this change, help resolve issues, and improve documentation and guidance.

What's happening?

We’re rolling out a new feature where all new files uploaded into Office 365 Connected Yammer Groups will be stored in SharePoint Online by default. With files stored in SharePoint Online, third-party apps using Yammer authentication to access Yammer Files API endpoints and performing file operations (such as upload, preview, download and delete) will get an error on those API calls. 

Reason: The Yammer OAuth token does not include Azure Active Directory (AAD) claims, which is required for accessing files stored in SharePoint Online.

What are we doing to help with this change?

We’re building temporary support to retrieve claims from AAD tokens and associate them with Yammer OAuth tokens. When a user logs in and authorizes a third-party client application via the /dialog/OAuth endpoint, the Yammer OAuth token is read from the cookie, and the AAD claims required for SharePoint Online are extracted and associated with the user’s OAuth token for the particular client application.

However, there is no mechanism for the AAD claims associated with the Yammer token to refresh automatically. These AAD tokens and their claims typically have an expiration of one hour, meaning that the SharePoint Online file access will only work for a short time before the user is required to log in through AAD and reauthorize the client application. For this reason, Yammer strongly recommends managing and refreshing AAD Access Tokens within the client application and sending them in the Authorization header to Yammer APIs, instead of using Yammer OAuth tokens.

If there are no AAD claims associated with the Yammer OAuth token, or if the AAD claims have expired, then API operations for files stored in SharePoint will be rejected.

When making files Yammer API calls files in SharePoint, different 4xx status codes are returned based on the claims associated with the OAuth token.

API behavior

Status codeCauseRemediation
400Yammer OAuth token has no AAD claims associated with it, or the claims have expiredRefresh the AAD Access Token in the browser cookies (log out and log in) and reauthorize the client application
401Token is not validGenerate a new AAD token
403User does not have access to the fileNone

For more information on how to generate and manage AAD Access Tokens, see the Authentication Libraries page: https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-v2-libraries

Notes:

  • AAD claims do not refresh automatically, but their expiration only impacts file operations in SharePoint Online via the Yammer API. Yammer OAuth tokens will continue to function for all other Yammer API operations.
  • Test access developer tokens generated via the Yammer client application page may not have AAD claims associated with them, because these tokens aren’t generated during an Office 365 authentication flow. This means that SharePoint Online file access via Yammer APIs will not work for these tokens.
  • AAD claims will not work with files in Yammer external networks—a Yammer authentication token is required to complete those file operations.

What can you do?

You can continue to use the Yammer Files API to access files in Yammer storage without any further action.

However, if you have a third-party application that needs to perform operations on Yammer files stored in SharePoint Online for Office 365 Connected Yammer groups, then we recommend that your application uses AAD authentication and leverages AAD libraries to refresh AAD claims when they expire. If AAD claims are missing or expired, then file operations will be rejected.

We are also previewing a new API to upload files into Yammer Groups. An AAD token is required for uploading files into an Office 365 Connected Yammer Group. Read the documentation here.

 

As Yammer integrates further into Microsoft 365, we’re excited for additional platform opportunities through the Azure Active Directory. Recently, we announced preview support for using AAD tokens with all documented Yammer v1 APIs and are working on adding more support. Check out the resources below for information on creating an AAD app and calling Yammer APIs. We encourage the developer community to explore developing their Yammer apps in Azure AD. There’s also code samples in Yammer’s GitHub repo and in the links below.

The following limitations have been identified and we’re planning on addressing them:

  • Impersonation/Delegation scenarios: Currently not supported; we’re looking into supporting AAD delegation scenarios for SharePoint file operations (accessing data on behalf of other users).
  • Multiple scopes: An access token issued from Azure AD only available for one workload, such as Yammer, Teams, SharePoint, etc. You can't use the same access token for multiple workloads.
  • Single Page application: If you are using a single page Azure AD application that uses implicit grant flow, then your Azure AD application needs to be mapped to its corresponding Yammer platform application. Please provide details about your application in this form and our team will be in touch with you.

We’re interested in all your feedback so please be sure to comment on this blog. If you would like to discuss in detail then please email us or join the Monthly Yammer Platform and API Office Hours, first Wednesday of every Month from 11am to 12pm Pacific Time. We realize that this time may not be convenient for all our partners and customers, so we're considering expanding the office hours to other time zones in the near future. We're looking forward to engaging with you. Thank you!

Resources from this blog:

Discuss this article in the Microsoft Technical Community.