Tuesday 16 December 2014

Office 365 apps – deciding between the SharePoint app model and the Office 365 APIs

Just like me, many other SharePoint developers have spent the last year or two getting to grips with the SharePoint app model – this was introduced in SharePoint 2013 as a way of building customizations which do NOT run on the SharePoint server. Enhancements built this way can run on a remote machine (e.g. Azure, IIS, whatever) and therefore any stability/performance issues do not affect core SharePoint. If you’re using Office 365 of course, the app model is a big cornerstone of extending the platform, since Microsoft do not allow custom SharePoint code to be deployed to the Office 365 servers (server-side code at least). These were big changes in the SharePoint development world, with lots to learn around authentication, remote APIs and patterns for solving common needs.

However, there’s a new kid in town. Microsoft have introduced a series of new APIs for Office 365 which span SharePoint, Exchange and Lync – and rather than needing to know each platform as a developer, more general concepts are exposed such as:

  • Mail
  • Calendar events
  • Contacts
  • Files

Of course, those who know the territory will recognize that “mail”, “calendars” and “contacts” are related to Exchange and that “files” are related to SharePoint (N.B. right now this is primarily about files stored in the user’s OneDrive for Business area). But the point is that not everyone who wants to work with Office 365 data these days has that background. Initially this new direction can be confusing to the experienced developer – after all, can’t I access SharePoint files using the existing SharePoint CSOM or REST APIs? Also, why is authentication different? I just spent months learning about provider-hosted apps and the “new” authentication models with context tokens, access tokens and so on! Why did we need something new?  If this is a new way of building apps for Office 365, is the old model going away? These are all logical questions in my opinion, so I wanted to talk about them here, as well as discuss some things to look out for in your apps which suggest you SHOULD be using the new approach. But for sure, if you’re about to start building an app you might be faced with this decision (with a gratuitous graphic to illustrate):

COB - provider-hosted SP app vs Office 365 app

After all, there are many similarities between the two – in both cases, the core implementation could be ASP.NET MVC, on Azure or some IIS servers for example. Let’s start by understanding what an Office 365 external app is about.

What an Office 365 app looks like

Here are some key tenets of these apps:

  • The application is an “external” or “standalone” app of some kind, perhaps implemented in ASP.NET (most likely MVC flavor these days). And when I say website, remember that it could really be something else altogether, like an App for Office which surfaces in Word or Outlook (since these use web pages underneath). Equally it could also be a Windows Store/Phone app or one which targets other devices, such as an iOS/Android app
  • We want to somehow integrate the app with Office 365 (perhaps in terms of user experience/navigation, data storage or authentication)
  • The app is registered in Azure Active Directory – specifically the Azure AD behind your Office 365 tenant
  • Apps can implement the same authentication mechanism as Office 365. This means your users get single sign-on, and can pass between Office 365 and your app without re-entering their username/password
  • Users can navigate to the app via the Office 365 App Launcher or “My apps” page
  • In coding terms, the apps are likely to use the new Office 365 APIs to access data there, but can also revert to using lower-level APIs such as the SharePoint CSOM/REST APIs
    • N.B. To do this, you use the authentication token obtained from Office 365 as the “bearer” token in the HTTP headers for the request to the other API:

Developing with the Office 365 APIs

If I was to summarize the development model, I’d say there are two high-level approaches:

  • Using the Office 365 REST API (more operations, but more complex since you need to craft the HTTP requests yourself and deal with authentication etc.)
  • Using a flavor of the Office 365 client libraries (simpler to use, but don’t have 100% coverage of what’s possible). These flavors include:
    • .NET (for use in ASP.NET websites, Windows Store/Windows Phone apps, Xamarin apps etc.)
    • iOS
    • Android
    • Cordova apps (multi-device hybrid apps)

Key differences between Office 365 apps and Apps for SharePoint/Apps for Office

But what if your app is SharePoint/Office focused, and could therefore be implemented as EITHER an Office 365 app or an App for SharePoint/Office? Let’s consider that decision for a while - here are some of the differences as I see them (N.B. I’m also summarizing these differences in a table below):

Difference 1 - how the app is accessed (by end-users)

Office 365 app:

An Office 365 app can be accessed in a few ways:

  • From any link (e.g. on your intranet home page), since it’s a standalone website
  • From the Office 365 App Launcher (if the app is “pinned” there for quick access)
  • From the Office 365 “My apps” page

App Launcher experience:

COB app pinned to app launcher

“My apps” page experience:

COB My apps page

App for SharePoint:

An App for SharePoint can be accessed in the following ways:

  • From the Site Contents page of a SharePoint site where the app is installed
  • From a developer-provided SharePoint link, using AppRedirect.aspx?instance_id=[app instance GUID here]

In other words, these apps can only be accessed from a SharePoint/SharePoint Online site – assuming that is, that the app accesses some SharePoint data (as most would). This is because the authentication model relies on the context token being passed from SharePoint into the app – otherwise the app cannot talk to SharePoint in any way.

Site Contents page experience:

App deployed to target site

Difference 2 – app registration (for implementer)

Office 365 app:

Firstly, these apps must be registered in the Azure AD which relates to the Office 365 tenancy:

COB Azure AD COB Azure AD - applications

Note that Visual Studio (more specifically, the Office 365 dev tools) perform this step for you when you create an app for a single Office 365 tenancy. Azure AD administrators can also register apps, and this is what needs to happen for multi-tenant apps.

App for SharePoint:

These apps are registered in SharePoint/Office 365 using AppRegNew.aspx (or using the Office Seller Dashboard for Store apps):

AppRegNew

Difference 3 - how authentication and authorization works e.g. for SharePoint data (for implementer)

Office 365 app:

Once the app is registered in Azure AD, you can write code using the Office 365 client libraries to authenticate to the platform (simpler), or alternatively go lower level and obtain tokens yourself through OWIN (for MVC) or ADAL for .NET (both more complex, but what is needed when you’re coding directly against the Office 365 REST APIs). In terms of the client libraries approach, here’s a snippet showing how auth works in the .NET Office 365 library (taken from the Office 365 Starter Project for ASP.NET MVC sample):

You can cache these access tokens as you see fit to avoid repeated auth prompts. But if a new token needs to be obtained, this code does the work of redirecting the user to sign-in to Office 365 (whether they are in a web browser or on a device):

COB Office 365 sign-in - web

image

App for SharePoint:

Authentication for an App for SharePoint works in the following ways:

  • SharePoint-hosted app: authentication happens implicitly, since web pages are hosted in SharePoint context (and only the SharePoint JSOM API can be used)
  • Provider-hosted app: app must be registered with AppRegNew.aspx (or the Office Store), and .NET code can authenticate using the SharePointContext and TokenHelper classes which are added to your Visual Studio web project on creation:

Difference 4 – app deployment (for implementer)

Office 365 app:

Whatever is needed to to copy the app to the hosting location e.g. publish to Azure (from Visual Studio – shown below) or FTP or similar:

Publish web app - validate settings  

App for SharePoint:

Similar to above in that app files must be published to the hosting location, but with two extra steps:

  1. The app package (.app) must also be deployed to an App Catalog:

    Publish app - upload to app catalog
  2. Once the app is in the App Catalog, it must be installed to any SharePoint site which should use the app (or, a tenant-scoped installation should be performed):

     App install - in site

Summary table of differences/commonalities

Since the above sections are a bit difficult to cross-reference, let me try to summarize in a table:

Office 365 app

App for SharePoint

How the app is accessed (for end-user)
The App Launcher/My Apps page

Some other link (e.g. from some other intranet site you have) or bookmark – it’s a standalone website
Typically from the Site Contents page of a SharePoint site
Authentication to Office 365/SharePoint (for implementer) App is registered in Azure AD, then authentication helper in Office 365 client libraries typically used (e.g. AuthenticationContext object in .NET Office 365 SDK) App authentication – context token is passed from site into the app, and access token obtained from there. Helper code supplied in form of SharePointContext and TokenHelper classes (added automatically to app projects)
App hosting (for implementer) Any web platform – Azure or other cloud-hosting, on-premises IIS, or other web servers Any web platform – Azure or other cloud-hosting, on-premises IIS, or other web servers
App registration (for implementer) Registered in Azure AD Registered in SharePoint/Office 365 using AppRegNew.aspx (or using the Office Seller Dashboard for Store apps)
App deployment (for implementer) Deployed once to the hosting platform (e.g. Azure/IIS) Deployed to a SharePoint/Office 365 App Catalog, and then installed by site owners to various SharePoint sites or tenant-scoped install.

Alternatively, submitted to the Office Store for sale there.

Other differences

There are some wider differences not covered above too. Don’t forget things like:

  • For Office 365 apps, I no longer need knowledge of Exchange and SharePoint APIs to pull together an app which (for example) stores some files in an area I can access (i.e. my OneDrive) and sends an e-mail on my behalf. In other words, I don’t need to be a “career developer” in Exchange or SharePoint to make use of this stuff
  • Office 365 apps are probably easier to develop for devices – having SDKs for iOS and Android means that some common dev tasks are pretty simple on those platforms. I’d say the fact that these apps don’t need to be accessed from a SharePoint site can help here too

Summary - reasons to consider the Office 365 approach

So, there are clearly some things to consider if you’re building an app which could work as either a provider-hosted SharePoint app OR an Office 365 app. Here’s my summary list of indicators that the Office 365 app could be a good fit:

  • Your app doesn’t need to work with on-premises SharePoint/Exchange
  • Your app doesn’t really “fit” in SharePoint:
    • It’s an external app, not associated with a “site”
    • It sits at the “Office 365 suite” level
  • Your requirements match files/messages/events etc.
  • You want to integrate with the Office 365 App Launcher
  • You don’t want your app to need to be installed into SharePoint sites by site owners (and a tenant-scoped SharePoint app doesn’t suit your requirements)
  • You’re developing for devices and want to take advantage of device-specific SDKs
  • It’s the future!

In short, there will always be cases where either an Office 365 app or an App for SharePoint is a better fit – both models are valid going forward. The key is understanding the differences, both to the end-user and the implementer.

Feel free to leave a comment if you think I’m missing anything, or have any thoughts related to this!

8 comments:

Anonymous said...

Great article, and to me this is slowly sinking into how I might think about solutions on O365 in the future.

Do you see that perhaps the crossover point might be an app that has say a requirement for files, events, AND a custom list of sorts, or maybe even write an entry to the social stream (probably Yammer)?

Do you see the O365 API being extended so that all services are available through the common O365 API and perhaps the SharePoint specific API might become less important?

I'm wondering if we end up with scenarios where we might have a requirement for files, events, lists, social activities, and we choose to make use of say Azure Table Storage for lists and don't even bother with a SharePoint site at all!

Perhaps the key to this will be the reach of Delve, if Delve can surface search results from all O365 properties then maybe the requirement for a SharePoint site itself could diminish (at least in the custom app scenario).

jabberjaw said...

Great post Chris! Another distinction that affects this decision is: Office 365 APIs use Azure AD for authentication through User consent at runtime, whereas the for Apps for SharePoint uses OAuth through App consent at 'deploytime'. As of now, Azure AD does not have a construct for Apps to have 'AllUser' consent, it only has it for Users’ to individually give consent an App.

Chris O'Brien said...

@finarne,


Yes, I definitely think the Office 365 APIs will be extended significantly. I know the engineering team are working on some interesting examples of this at the moment. However, I don't foresee that the API will ever be as deep/rich as the "dedicated" remote APIs such as SharePoint CSOM/REST are - after all, those things have had several years of investment now.

I think the goal will be to make "generic" developers as productive as possible on the Office 365 platform, especially around common needs.

So if only basic use of SharePoint constructs such as sites/lists is required, then it may move to the background somewhat yes. But if deeper use is needed, that SharePoint API knowledge would still be required IMHO.

Cheers,

COB.

Chris O'Brien said...

@jabberjaw,

Yes - very good point, thanks. It's worth noting on your points that some Common Consent permission levels need the user *AND* an administrator to agree (e.g. AllSites.FullControl). But yes, each individual user does have to consent.

Also missing at the moment is the ability to request permissions for *specified* SharePoint sites (rather than all) - on the way though apparently..

Thanks for the comment.

Cheers,

COB.

Nigel Dewar said...

this is an amazing article, thank you very much!!!

quintorel said...

Good article Chris!

Garima said...

Thanks for this article Chris. Just a question, does this scenario still holds true with all the new capabilities in O365. So for instance, I need to create an add-in which users will access from SharePoint Online but nothing else will be stored in it. Backend will be SQL or some other system. Does it still make sense to go with O365 apps? Have you ever encountered any issue while using it in production?

Chris O'Brien said...

@Garima,

Yes, all of this basically holds true today, except to say:

- the Office 365 APIs have evolved into the Microsoft Graph - but the same considerations still apply
- it's perhaps more popular to implement your app more on the client-side than ASP.NET MVC these days, using Angular, React or similar JS libraries. Both work well though. If calling the Graph with JS, you'll need to use adal.js to authenticate (at the moment)
- If you *do* use a JavaScript-based implementation, any server-side code you need could be implemented using Azure Functions. See Calling an Azure Function from the SharePoint Framework for more info on that

Overall, the big considerations between SP provider-hosted apps vs. Office 365 apps still apply - how should end-users access the app, and do either of the authentication models/API sets lend themselves to what I need to build more than the other? In the case of data being stored in SQL, it might mainly be the "how should users access the app?" question to consider.

HTH!

COB.