Microsoft have gone to great lengths in the past few years to build a comprehensive set of APIs making it easy for developers to work with all of their products. OneDrive for Business is no exception as it has been a key part of the Graph API set since the beta versions.
However in effect what this means is that when building OneDrive for Business apps (OD4B henceforth) you have a number of API options to consider; Graph API, OneDrive API and the SharePoint APIs (CSOM, JSOM, REST and even the old SSOM)! In addition to which the authentication story is just as complex, you have OAuth2, ACS, ADFS and even NTLM!
In this two part series I’m going to attempt to demystify the differences and share some hard learned experiences building enterprise software for OneDrive.
Graph, OneDrive API, OAuth, Azure AD, you lost me already!
Firstly let’s clarify a few things because in the modern day of Microsoft APIs everything seems to have at least two names, and sometimes the same name is even reused in different products! (Azure AD Graph anyone?).
So firstly Graph API or OneDrive API?
OneDrive API is to quote; “Built on Graph”. That wasn’t always strictly true but even the beta versions of both APIs were similar in syntax. At the time of writing one may well assume that the OneDrive API will eventually be completely replaced by the Graph API, however today there are still some subtle differences that can throw you off at times.
That may lead you to choose to use only Graph, just as I wanted to, however it turns out that when writing Enterprise apps you’ll probably run into some of the “in preview” or non-existent features, such as a big one:
Note: At this time, only user-delegated permissions are available for the files portion of the Microsoft Graph. While some scopes may be available for app-delegated or client credentials authentication, these scopes are not supported with Microsoft Graph.
What does that mean? Well simply put your app cannot have “app-level” permission to access “All files in all site collections” for example. “Wait what” you ask? This is important, I’ll talk more about this in Part 2 in the section “Configuring permissions for access in lieu of App-delegated permissions”.
Interested in reading more about the differences? See: https://github.com/OneDrive/onedrive-api-docs/blob/master/direct-endpoint-differences.md
Now OAuth2 or AzureAD, what’s the difference?
Azure AD (AAD) is an OAuth2 compliant authentication and authorization protocol. However I’m going to add that’s where the similarities end. The Microsoft cloud is unsurprisingly a big beast, so in order to distinguish between O365 tenants, both hybrid or cloud as well as working with all of the Microsoft Apps while maintaining support for most of the available APIs and their various versions, Microsoft have extended their OAuth2 implementation in a way that is somewhat familiar to anyone who knows OAuth2. But does require some significant changes to any standard implementation.
We’ll talk about the Office Discovery service and Resource endpoints below, as you will see even if you are familiar with other OAuth2 implementations these differences require significant changes in your AAD implementation.
What I won’t be talking about is Microsoft Account OAuth2 (formerly Live Connect or Passport if you’ve been around too long like some of us). Microsoft Accounts do not work* with Azure AD and furthermore you should avoid using them in the Microsoft Enterprise Cloud space as while some things can be done using a Microsoft Account, those things won’t always work as expected when working with other Azure AD / Graph or specifically OneDrive services.
(*) For an example of the pitfalls I allude to, we’ll cover setting up an Azure AD application registration for your app in part 2. If you do this using a Microsoft Account when logged into the Azure Portal, the app will not work, period. Worse still the errors given will not help much! Trust me, I lost many hours to this little feature.
One last thing; Azure AD, Azure AD v2.0 or a Converged Application?
Do you see why I’m writing this article now? Yes there actually are multiple different versions of Azure AD that we need to consider!
Azure AD v2.0 apps now referred to by Microsoft as Converged Applications, are Microsoft’s way of combining all these authentication methods; Microsoft Accounts, Azure AD, Office 365, etc, into one single pure OAuth2 implementation. As a result converged apps do away with ‘resources’ in favour of ‘scopes’ (read: more OAuth2 spec compliant).
Perfect that would have saved me the last section of this article, but no there’s always a catch. Specifically there are a number of limitations documented by Microsoft in using AAD v2.0 , most of them relate to the same limitations that you’ll find with Graph, such as the endpoints supported – e.g. specific Microsoft cloud services only.
That means that a major consideration is your environment itself; if you are targeting a pure cloud Office 365 + OD4B environment then AADv2 is probably the best choice for now and definitely so in the future. However if you have a hybrid configuration to support then AADv1 may be the only choice! (Reference: https://dev.onedrive.com/auth/readme.htm#aad-authentication)
Finally in my experience when working with OneDrive, less than a year ago much of what I needed to do – things like server side offline access, delegated access, etc. E.g. all those enterprisey-app-things – was simply not possible, today the picture is much better, although some of those features are still listed as ‘in preview’.
So with all of the above in mind, in the next part of this article I’m going to cover both AAD v1 and v2 configurations with an emphasis on v1 due to two reasons; 1. the limitations of v2, as I suspect many will be around for years to come, and 2. because v1 rather hard and needs explaining, whereas on the other hand AAD v2 is simple.
For more information on the differences and which one you should choose see the following:
- Should I use the v2.0 endpoint – https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-limitations
- Deciding between Azure AD and Azure AD v2.0 – https://developer.microsoft.com/en-us/graph/docs/concepts/auth_overview#deciding-between-the-azure-ad-and-azure-ad-v20-endpoints
End of Part 1
In part 2 of this series we’ll dive in to the API’s and look at what you’ll need to know to actually build OneDrive for Business apps in your Enterprise.
[Check back for Part 2 soon]