Posted by on Mar 2, 2016 in #Office365Dev | 0 comments

With the new application model for Office comes a brand new way of extending Office with your own functionality – using the tools and dev stacks that we already know and love.

In mail add-ins, we have access to a great functionality within the APIs to get an identity token. This identity token represents the Office 365 user and is key when it comes to building a single sign-on experience for your users. If you would like to learn more about what’s inside the identity token – head to: http://simonjaeger.com/dissecting-and-validating-the-exchange-identity-token/

Why would you want to do this? Imagine if your mail add-in could sign in the user as soon as it starts in Outlook – without having to ask for credentials every time. Not only is this behavior annoying from a user standpoint, but it’s also possible to overcome this because we have access to the identity token.

This blog post demonstrates how to implement a single sign-on experience within an Outlook add-in. In addition, Different styles and components from the Office UI Fabric library are used throughout this Office add-in.
The objective is to get familiar with some of the possiblities that we have when building Outlook add-ins.

The blog post is divided into multiple steps and should be followed in a chronological order. These are the included steps:

1.1 Create the project
1.2 Edit the manifest
1.3 Launch the project
2.1 Clean up the project
2.2 Add Office UI Fabric
2.3 Add the base
3.1 Add the input fields
3.2 Add the Spinner
3.3 Add the dialog
4.1 Add the authentication logic
4.2 Add the sign in button
4.3 Enable the sign in button
5.1 Add the Web API Controller
5.2 Add the Web API configuration
5.3 Add the Global Application Class
5.4 Add the models
5.5 Add the user service interface
5.6 Add the service implementation
5.7 Finish the SSO Controller

Short of time and just want the final sample? Clone this repository (https://github.com/simonjaeger/OfficeDev-HOL.git) and open the solution file: Single-Sign-On-Outlook-Add-in\Source\Single-Sign-On-Outlook-Add-in.sln.

Prerequisites

Visual Studio 2015: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
Office Developer Tools: https://www.visualstudio.com/en-us/features/office-tools-vs.aspx
Office 2013 (Service Pack 1) or Office 2016
Office 365 Developer Tenant: http://dev.office.com/devprogram

Step 1.1: Create the project

The first thing that we need to do is to create the project itself. Make sure that you have installed all of the required prerequisites before launching Visual Studio 2015.

1. Click File, New and finally the Project button.
2. In Templates, select Visual C#, Office/SharePoint and then Office Add-ins. This will list the Office add-in templates, choose Office Add-in.
3. Name your project “Single-Sign-On-Outlook-Add-in” and click the OK button to continue.

4. Next up Visual Studio 2015 will need a bit more information about what you are going to create – in order to set up the required files. Your next step is to decide which type of Office add-in that you want to create. Depending on what you pick, your Office add-in will run in different Office applications and contexts.

For this blog post, we will create a mail add-in – this means that our Office add-in will run in in Outlook as a view beside the Office context (e.g. a message or appointment). Select Mail and click on Next.

5. Finally we need to choose the supported modes for our mail add-in. This means that we are defining the contexts that our mail add-in can run within; read, compose or both. If you choose Read form, the mail add-in will be able to run when a user is viewing a mailbox item. In Compose form, the mail add-in can run when a user is creating or editing a mailbox item.

In our case, select Read form for Email message. Deselect everything else to create a read mode mail add-in. Click Finish to complete the wizard.

6. Using the information you specified in the wizard, Visual Studio 2015 will configure your project. Have a look in the Solution Explorer and find your two new projects in the Single-Sign-On-Outlook-Add-in solution.

Single-Sign-On-Outlook-Add-in: This is your manifest project, containing the XML manifest file. This is basically a representation of the information you just specified while creating your Office add-in project.

Single-Sign-On-Outlook-Add-inWeb: This is your web project for the Office add-in. This contains all of the different source files that makes up your Outlook add-in. We will make quite a few adjustments to this structure as we continue.

You’ve now created the basic structure for a mail add-in running in Outlook.

Step 1.2: Edit the manifest

We need to make sure that we understand the manifest file. This file is essential for your add-in; it tells Office where everything is hosted (locally throughout this blog post) and where it can be launched. So let’s open it and edit the manifest file.

1. In the manifest project Single-Sign-On-Outlook-Add-in, double-click the Single-Sign-On-Outlook-Add-inManifest file. This will open the manifest editor.

2. In the General tab section, find and edit the Display name and Provider name to anything you’d like.

3. In the Read Form tab section, find the Activation part. This is what determines the rules for potential activation of your mail add-in. By default, Item is a message should be included.
4. Scroll down and pay attention to the Source location property. This points to a specific file in your web project (Single-Sign-On-Outlook-Add-inWeb). When launching your mail add-in, this page will be the first thing that gets loaded and displayed.
5. Below the Source location property, you will find the Requested height (px) property. This a way for your mail add-in to ask for a certain height in pixels when displayed within Outlook. Be aware though, it doesn’t mean that it will be granted. Change this to 300 – as we want a bit more height for our mail add-in to display the sign in form.

Step 1.3: Launch the project

Before we launch our mail add-in we should validate that our start actions are proper.

1. Select the manifest project; Single-Sign-On-Outlook-Add-in in the Solution Explorer.

2. In the Properties window, set Start Action to Office Desktop Client.
4. Set Web Project to your web project; Single-Sign-On-Outlook-Add-inWeb.

5. To launch the project, open the Debug menu at the top of Visual Studio 2015 and click on the Start Debugging button. You can also click the Start button in your toolbar or use the {F5} keyboard shortcut.

6. When launching your mail add-in for the first time, Visual Studoo 2015 needs to install the manifest file. This is where you should use your Office 365 Developer Tenant (if you haven’t signed up for one yet, get yours for free at http://dev.office.com/devprogram). Enter the credentials of a user ([username]@[your domain].onmicrosoft.com) belonging to your Office 365 Developer Tenant and click on the Connect button.

7. Once Outlook has launched, you’ll notice that your mail add-in doesn’t start right away. We need to start it manually. Select a message in your mailbox (send yourself one if needed) and click on the Single-Sign-On-Outlook-Add-in above it. Once your mail add-in has launched, you can explore the functionality that comes right out of the box with the Visual Studio 2015 template.

8. Finally, stop debugging by opening the Debug menu at the top of Visual Studio 2015 and click on the Stop Debugging button. You can also click the Stop button in your toolbar.

Step 2.1: Clean up the project

While the default styling that comes along with the Visual Studio 2015 template for Office add-ins does its job – leveraging the features of the Office UI Fabric can be fantastic. It’s a UI toolkit made specifically for building Office and Office 365 experiences, so it will certainly help us out here.

The Office UI Fabric library comes with everything from styling, components to animations. The majority of the library can be references via a CDN. The heavier parts needs to be downloaded and added to the project itself. We will go through both of these approaches.

Our first task is to clean up the project, and remove the default styling and setup.

1. Remove the Content and Images folders from the web project. You can do this by right-clicking these folders in the Solution Explorer and choosing the Delete option.

2. In your Solution Explorer, find the Home.html file – which is the startup page for your mail add-in. Remove everything inside the body tags.
3. In Home.html remove the CSS reference to “../../Content/Office.css” – we have removed this file and will be using Office UI Fabric instead. This should leave you with this:

4. In App.js, remove the initialize() function defined on the app object, as this will not be used:

5. In Home.js, remove the displayItemDetails() function and the call to app.initialize(). We are remaking the structure of the mail add-in, these will no longer be used. You should end up with this:

6. In App.css, remove everything, leaving you with an empty file.
7. In Home.css, remove everything, leaving you with an empty file.

Step 2.2: Add Office UI Fabric

1. In Home.html, add two CSS references to the CDN for Office UI Fabric inside the head tags. Add them before the CSS reference to “../App.css”.

2. Some components in the Office UI Fabric library require some additional JavaScript to function. In our case, we will use a Spinner component that needs this. Download the JavaScript file for this component (Spinner.js) at https://raw.githubusercontent.com/OfficeDev/Office-UI-Fabric/master/src/components/Spinner/Spinner.js or get it by browsing…
2. Right-click and choose Add Global Application Class. Name it “Global” and click on the OK button.

3. In Global.asax.cs, find the Application_Start method and add the following code piece inside of it.

4. In Global.asax.cs, add the following using statements at the top of the file:

Step 5.4: Add the models

We will use three different models (objects) when building the authentication/mapping logic. These are:
CredentialsModel: Represents the basic values needed to validate someone as a user (UserModel). This model is merely a demonstration of an authentication mechanism. Make sure that your usage of credentials meets the security requirements of your application. You could either implement a token flow (i.e. using one-time tokens or the OAuth protocol) for your web service or POST directly over HTTPS (with an HTML FORM) to your API.

Ideally your web service should generate a set of (short-lived) credentials only intended for the user mapping. Validate and expire those credentials in your Web API.
UserModel: Represents the user in the service. It contains both a DisplayName property and Credentials property.
UserRequestModel: Represents the properties (IdentityToken, HostUri and optional Credentials) needed to perform a mapping of an Office 365 user and a user in your service. It also containts the properties needed to do a lookup of an already mapped user.

1. Select the web project; Read-Mode-Outlook-Add-inWeb in the Solution Explorer.
2. Right-click and choose Add New Folder, name it “Models”.
3. Right-click on the Models folder and choose Add Class…. Name it “CredentialsModel” and click on the OK button.
4. In CredentialsModel.cs, replace everything with the following code piece.

5. Right-click on the Models folder and choose Add Class…. Name it “UserModel” and click on the OK button.
6. In UserModel.cs, replace everything with the following code piece.

7. Right-click on the Models folder and choose Add Class…. Name it “UserRequestModel” and click on the OK button.
8. In UserRequestModel.cs, replace everything with the following code piece.

Step 5.5: Add the user service interface

Let’s create an interface to define the three different operations we need to create a single sign-on experience:
GetUserAsync: Get an already mapped user in the service using the Office 365 unique user identifier (UUID).
GetUUIDSaltAsync: Create or get an existing unique salt for the Office 365 unique user identifier (UUID) – used creating the UUID.
MapUserAsync: Map the Office 365 unique user identifier (UUID) with a user in your service (using the provided credentials).

1. Select the web project; Read-Mode-Outlook-Add-inWeb in the Solution Explorer.
2. Right-click and choose Add New Folder, name it “Services”.
3. Right-click on the Services folder and choose Add Class…. Name it “IUserService” and click on the OK button.
4. In IUserService.cs, replace everything with the following code piece.

Step 5.6: Add the user service implementation

In order to get going and test this out – we need to implement the IUserService interface. In this exercise we will implement the three needed methods (GetUserAsync, GetUUIDSaltAsync and MapUserAsync) by creating a fake user service.

We will simulate a persisted solution for users, salts and mappings with simple Dictionary objects. While it will be simple to implement, it is not persisted to disk and will only be available as long as your web application is running (so keep the debugging session going to keep the data).

1. Right-click on the Services folder and choose Add Class…. Name it “UserService” and click on the OK button.
2. In UserService.cs, replace everything with the following code piece.

Step 5.7: Finish the SSO Controller

The last step is to complete the Web API Controller. We will create a POST method to handle everything. This method will accept a UserRequestModel object to be passed in this request body. The Credentials property on the request body is optional, but without it we will not perform a mapping between an Office 365 user and a user in the UserService instance.

Before we do anything that has to do with user lookups or user mappings – we need to validate the identity token in the request. We can of course write this validation code if we want to (http://simonjaeger.com/dissecting-and-validating-the-exchange-identity-token/). But we can save ourselves a lot of time (and errors) by using the Exchange Web Services Managed API – available as a NuGet package.

When we are mapping an Office 365 user with a user in the UserService instance, we don’t want to use the Office 365 email address (or Exchange ID for that matter). Instead, we should get the UniqueUserIdentification property, salt it and then hash it (this is done in the GetHashedUUID method).

1. Click on Tools in the Visual Studio 2015 top menu.
2. Select NuGet Package Manager and choose Package Manager Console.

3. In the Package Manager Console, select the web project (Single-Sign-On-Outlook-Add-in) as the Default project.
4. Enter and run Install-Package Microsoft.Exchange.WebServices to install the Exchange Web Services Managed API.

5. In SSOController.cs (in the Controllers folder), add the following using statements at the top of the file:

2. In SSOController.cs, add the following code piece within the class:

3. Launch your mail add-in and test your work. Use the form to sign in with the credentials of a user in the UserService class. When the sign in is completed, the mail add-in will reload and automatically sign in (single sign-on).

If you restart Outlook and the mail add-in, you will find that the user is automatically signed in every time (as long as you keep your application running, because the mapping is in-memory and not persisted).

You could also launch your mail add-in in Outlook Web Access (https://outlook.office.com/owa/) and experience the SSO. Also, if you wanted to release a mail add-in with single sign-on to the Office Store – you should give the users a way to sign out (release the mapping) as well.

Wrap up

View the source code files included in this blog post for a final reference of how your code should be structured (if needed). You should now have grasped an understanding of a few possibilities of interacting with the Office context (a mailbox item in this case). In addition, you have also seen some of the styles and components included in the Office UI Fabric.

-Simon Jaeger