Managing Authentication flow within Office Add-ins has just got a whole lot easier with the introduction of the new Office UI Dialog API.
This post shows you how to create a simple Excel Add-in Command in Visual Studio 2015 that uses the new Dialog API to authenticate a user and then import their Outlook Contacts using the Microsoft Graph API.
If you are new to developing O365 Add-ins then I would highly recommend you check out the Getting Started page of dev.office.com. There are reams of examples and samples to help you get up to speed with links to the Office SDKs and a Yeoman Generator for Office if Visual Studio is not your thing.
The following is required to complete this module:
In this step you’ll create a new Excel Office Add-in using Visual Studio. If you haven’t done so already, make sure you have downloaded and installed the Visual Studio Office Developer Tools.
With the latest Office developer tools installed open Visual Studio and choose File-New-Project. In the dialog prompt choose Office/SharePoint under Installed Templates-Visual C#.
Choose Excel Add-in and enter a project name.
You will then be prompted to choose the type of add-in:
Accept the default and press Finish.
Visual Studio will create 2 projects: an Office Project which contains the add-in manifest; a web project that contains the content for the add-in. If you want more detail about the anatomy of an office add-in please refer to the following resource.
Full source code can be found here but I just want to highlight some of the key areas:
- (Contacts.js) Following the Dialog API guidance, create a displayDialog with the appropriate parameters:
- (Contacts.js) Specify how to handle the Dialog event type DialogMessageReceived. Note how the result message is parsed to extract the AAD access token:
- Based on the definition of the manifest this add-in has a single entry point which is a button on the Home Ribbon
In this step you’ll go through the steps of registering an app in Azure AD using the Office 365 App Registration Tool. You can also register apps in the Azure Management Portal but the Office 365 App Registration Tool allows you to register applications without having access to the Azure Management Portal. Azure AD is the identity provider for Office 365, so any service/application that wants to use Office 365 data must be registered with it..
Once you have signed in you will be asked for some details about the app:
Feel free to give the app a name of your choice but the redirect URI must match what is shown above.
Once you hit register you will be shown a second dialog which will; hopefully say “Registration Successful” and show you your Client ID. Copy this value as you will need it to complete the Office add-in solution.
Back in Visual Studio open the file App.js which can be found in the App folder.:
The tenant is the O365 tenant you either created as part of the app registration or your existing O365 tenant name.
Build the solution.
Ensure the Office Project properties add-in start action is set to Office Desktop Client:
When you click the Get Contacts button in the Office Ribbon you should be prompted with the following dialog:
Enter your O365 credentials (a user belonging to the tenant you specified in App.js) and if the user has contacts associated with the account then they should see them automatically added once the dialog is closed.
I hope you have enjoyed this post…feel free to send me any comments.