Monday, October 5, 2015

O365 Dev Challenges - Part 1 - Introduction to creating a multi-tenant Office 365 add-in using VS2015



The background for my O365 add-in coding adventure was that for Puzzlepart’s Office 365 customers we wanted a better way to integrate how they log support tickets with Office 365 directly. Today a user has to either send us an e-mail to the support account or log into our JIRA service desk in order to log a ticket.

The ticket logging action takes the user one step away from where he or she works, so why not instead create a multi-tenant Office 365 app/add-in which can be listed in the App launcher? This first implementation provides a simple add-in in Office 365 where they can file their tickets. Very similar to the existing ticket form, except we get single sign-on and tenant info directly. No need for a separate login or figuring out which information to write in an unstructured e-mail.

The next iteration of our support app will remove the need for sending e-mail and instead use REST API against JIRA to log the cases – requiring even less consent from the user. A more advanced version could rely on Application permissions granted by a tenant admin, but that’s a story for the future. I'm not ready to dive into specifics of certificates.

Technical approach

I do have a basic understanding of how the authorization flow works (more or less) for the user flow in Office 365, but I wanted the easiest experience possible where the plumbing code and scaffolding was created for me when I started to program in Visual Studio.

And utopia is almost within reach as long as you check the right boxes in the wizards to ensure the AdalTokenCache class is added and hooked into your projects authentication flow. I’m sure there are github samples out there which could have worked, but again, I wanted the VS only approach.

Delegated permissions

The add-in I’m creating will use a minimal set of Office 365 features, allow login and read the users profile as well as be allowed to send an e-mail on a user’s behalf. I could have started off with the Office 365 unified API which is in preview, but as this was my first go I wanted to go with the wizards and the easiest approach possible. Switching to the Unified API is covered in Part 6 – and the switch was not without challenges.

These are some of the pain points experienced on my journey:
  • hooking up the OWIN authentication flow for multiple resource end-points
  • making sure the token cache worked with multiple resources and cleared correctly when the cached tokens are no longer valid
  • patch the injected code to only keep one database entry per user for caching
  • figuring out that the connected service wizard and the publish web to Azure wizards have overlapping functionality which does work together when done right


I had some help from reading Tobias Zimmergren’s series on Getting started with Office 365 development and Chaks post on Making your Office 365 App Available to Multiple Organizations, but the wizards have since changed and I’m now on VS2015.

To make the experience as easy as possible I chose not to require any tenant admin setup, but instead let each user consent to the app by themselves. On login I check if the tenant is a registered customer, and if not you won’t be able to log a ticket. This is implemented with a simple database keeping track of valid tenant id’s and domains.

The demo app will not do the tenant check part, but covers logging in a user and sending an e-mail on his/her behalf.

Read on!