Office 365 API – Authentication & Setup

In our last article, we took a 10,000 foot view of what Office 365 has to offer. The article also made note of the Office 365 API, which enables developers to integrate with and use their users’ Office 365 data.

Before we can access the users’ data, we’ll need to authenticate our Office app and make sure it has the required permissions to access said data. This is accomplished by using single sign-on with Azure AD. The Office 365/Azure AD authentication uses OpenID Connect and OAuth 2.0, which is an open standard and if you’ve ever authenticated using either Facebook, Twitter or a Google account, the process of authenticating with Azure AD will be very familiar to you.

For the purpose of this article, we’ll only focus on authenticating using the new Office 365 Unified API. Although it is still only in preview, it will very shortly become the de facto method to access Office 365 data.

• Creating the application in Azure AD
• Creating the client application
• Accessing Office 365 data in Excel add-ins

Creating the application in Azure AD

Before we can authenticate, we’ll need to create our application in Azure AD. To do this, sign into your Office 365 portal and click on the Admin icon on the home screen.

On the Office 365 admin center home page, scroll down to the bottom of the screen and click on the Azure AD link which is located under the ADMIN menu.

This will take you to your Windows Azure AD management portal. Next, click on the Active Directory menu item on the left hand. This will list your active directory on the right.

Click on the arrow next to the name of your directory, which will open up more information about your Active Directory. Click on the APPLICATIONS link in order to show a list of applications set up for your Active Directory.

This will display a list of applications that have already been setup for your organization. Depending on your Office 365 plan, you should already see Exchange Online and/or SharePoint Online in the list. If you’ve already created an application and are not seeing it in the list, simply change the Show dropdown list to Applications my company owns to update the list.

In order to create a new application, click on the ADD button at the bottom of the screen. This will start a short wizard that will help you create a new application. On the first step, select “Add an application my organization is developing”.

On the next page, enter a name for you application and select whether it will be a Web/Web API application or a Native Client Application. If you’re going to develop a mobile or Windows desktop style app, select Native Client Application. If you’re building a website that integrates with Office 365 select Web Application and/or Web API.

We’ll build a Windows application for this example, so select NATIVE CLIENT APPLICATION.

On the next page, enter the Redirect URI. This is the URI to which Azure AD will redirect to after an OAuth 2.0 request. It does not need to be a physical endpoint, but it would need to be a valid URI.

Complete the wizard by clicking on the Complete button. On the application page, click on the CONFIGURE menu item. This will take you to the configuration page for your application, where you can set various options for your application as well as the required permissions. It is also the page where we’ll get two of the most important values for our application: (a) the Client ID; and (b) Client Secret. The Client Secret is not required when creating a Native Client Application.

Copy the Client ID to a location where you can access it later and scroll down to the bottom of the page. Under the “permissions to other application” heading, click the “Add application” button.

This will open a page where you can select which applications your application needs access to. Because we’ll be using the Unified API, click on the plus icon next to Office 365 unified API (preview) and click the check mark button to close this page.

Back on your applications’ page, you’ll see Office 365 unified API (preview) in the list of applications. Next to it, you’ll notice a dropdown list with all the available permissions. There are a host of permissions, enabling your app to read all the organization’s user profiles, manipulate site collections, read and write files, email, calendar and users.

For this example, we’ll only need access to the users’ profiles so select the following permissions:

• Read and write access to user profile; and
• Enable sign-in and read user profile.

Once done, save your Office 365 application.

Creating the client application

It is important to understand that the Office 365 API can be used in almost all applications, even traditional COM/Managed Add-ins! So, for this example, we’ll create a simple Excel Managed Add-in that adds some of the users’ profile information into the currently selected cell.

For this task there is no better toolset than Add-in Express! So, we’ll fire up Visual Studio and create a new ADX COM Add-in.

Select your programming language (C#, VB.NET or C++.NET) and the minimum supported version of Office. The latest release of Add-in Express supports Microsoft Office 2016!

For this example, we’ll only need to support Microsoft Excel.

Once the “New Microsoft Office COM Add-in” wizard has completed, we’ll need to add a few Nuget packages to our project in order to easily access the Office 365 data. The first package we need is the Office 365 unified API client library (preview). To add a reference to this package, open the Package Manager console by selecting it from the Tools > NuGet Package Manager menu.

Type the following into the Package Manager console:

Install-Package Microsoft.Graph -Pre

This will add the required dependencies for the library as well as add a reference to Microsoft.Graph to your project.

Next, in order to facilitate the authentication, we’ll need to add the Active Directory Authentication Library NuGet package to our project by entering the following in the Package Manager console and hitting Enter:

Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -Version 2.16.204221202

With the required references added, let’s add a Ribbon Button with which we’ll authorize our app and retrieve some user information. Open the AddinModule designer surface and add a new ADXRibbonTab component to it. Design the Ribbon Tab to resemble the following image:

Select the Ribbon Button and add an event handler for its OnClick event by double-clicking next to the OnClick event name in the properties windows’ events list.

Add the following code to the button’s OnClick event handler:

private void adxGetProfileInfoRibbonButton_OnClick(object sender,
    IRibbonControl control, bool pressed)
{
    Excel.Range currSelection = null;
    try
    {
        var client = new GraphService(
            new Uri("https://graph.microsoft.com/beta/{tenant-id}"), GetUserToken);
        IUser user = client.Me.ExecuteAsync().Result;
        var name = user.displayName;
        currSelection = ExcelApp.Selection as Excel.Range;
        currSelection.Value2 = name;
    }
    finally
    {
        if (currSelection != null)
            Marshal.ReleaseComObject(currSelection);
    }
}

In the preceding code, we first created a reference to the active selection in the Excel sheet. We then initialized a new instance of the GraphService object, which took a parameter for the service root of the service you’re trying to call. Because we’re using the Office 365 Unified API, this was set to https://graph.microsoft.com/beta/[tenant-id], whereas [tenant-id] will be your Office 365 tenant name e.g. mycompany.onmicrosoft.com.

The second parameter is a method called GetUserToken that will return the OAuth token to use for the service calls. The code for this method follows below:

private Task<string> GetUserToken()
{
    var authContext = new AuthenticationContext(
        "https://login.microsoftonline.com/common", false);
    var authResult = authContext.AcquireToken(
        "https://graph.microsoft.com",
        "98651301-70ac-481f-9a3b-4a2ade1e3132",
        new Uri("https://myapp"),
        PromptBehavior.Auto);
 
    var userToken = authResult.AccessToken;
    return Task.FromResult(userToken);
}

In the GetUserToken method, we created a new instance of the AuthenticationContext object and called its AcquireToken method. This method’s first parameter is the resource URI what we’re trying to access, when accessing the Unified API this should be https://graph.microsoft.com. The second parameter is the Client ID of the application we created in Azure AD. The third parameter should be a URI you’ve specified in the list of Redirect URI’s when you created the application.

Lastly, we used the GraphService client to return a new instance of the logged in user as an IUser interface. We then simply set the current selection in Excel’s value to the Display name of the current user.

Accessing Office 365 data in Excel add-ins

With the necessary code in place, it’s time to test! Build, register and run your project, and when Excel starts up, you should see an Office 365 Tab.

Make sure you have a cell selected and click on the “Get Profile Info” button. This will open an Office 365 sign-in window. Enter your Office 365 username and password and click Sign In.

If you’re signing in with a different account that is associated with a different Azure AD organization than the one that the application was setup in, a list of permissions required by the application will be displayed with a request to allow the Office 365 application access to your information or not.

After clicking Accept, you should see your Office 365 user’s Display name in the selected Excel cell.

In the upcoming articles, we’ll dive deeper into the Office 365 API and see how to access different types of Office 365 data.

Until then, thank you for reading and keep coding!

Available downloads:

This sample Outlook Add-in was developed using Add-in Express for Office and .net:

Office 365 Authentication sample