Calling O365 APIs from your Web API on behalf of a user

Article
04/15/2014

This post will show how to create a custom Web API that calls the Office 365 APIs on behalf of a user.

Background

How about that title?!? That’s pretty geeky.

I’ve been working with a customer who is interested in the new Office 365 APIs that were announced at SharePoint Conference. They are building multiple client applications that will consume their custom Web API endpoints. They did not want to reference the O365 APIs and perform all of the work from the client applications, but rather centralize that logic into a service that they control.

In this scenario, the user opens an application and logs in using their Azure Active Directory credentials. Once the user is authenticated, we obtain an access token used to call the custom Web API endpoint. The Web API endpoint, in turn, obtains an access token for O365 using the user’s token. This means when the O365 API is called, it is called using an app+user context on behalf of the currently logged in user. The current user must have permissions to write to the list, as does the app, and if one of them is missing permission then the operation fails.

Yeah, even after editing that paragraph several times over it’s hard to understand. Let’s walk through an example.

The code I am going to show is based on a sample posted by the Azure Active Directory team, Web API OnBehalfOf DotNet available on GitHub. I am not going to provide a code download for this post, I strongly urge you to go download their sample and become familiar with it. Instead of using the O365 API, that sample shows how to use the Graph API. This post details how to leverage some of the code in that example to call the O365 API. There are many things I omitted that you should spend time in that sample understanding.

There’s also a great post by Johan Danforth, Secure ASP.NET Web API with Windows Azure AD, that illustrates some of the same concepts that I show here. His example is well formatted and might help explain some of the settings that I am going to gloss over here. If you need help understanding the various parts (client ID, client secret, callback URL, app ID URI for the web API) that is a great resource as well.

Manage O365 Tenant from Azure Management Portal

The first part of this exercise requires that you manage your Office 365 tenant from the Azure Management Portal. A blog post with detailed instructions and an accompanying video are available at Using a existing Windows Azure AD Tenant with Windows Azure. I have an existing Office 365 tenant (https://kirke.sharepoint.com) that I log into with the domain “kirke.onmicrosoft.com”, and I want to add that account into Azure AD. To do this was as simple as logging into my Azure subscription using a Live ID and adding an existing directory in the Azure Management Portal.

Next, I log in using my Office 365 tenant administrator, and then the directory shows up in the Azure Management portal.

I can now open the directory and see all of my users from my O365 tenant.

Make sure you start In Private browsing before doing this, and it should work smoothly.

Create the Web API Project

Create a new ASP.NET Application in Visual Studio 2013 and then choose Web API.

Click the button to Change Authentication. We’ll use organizational accounts in Azure AD to authenticate, using the same domain that our O365 tenancy was in.

Leave the default App ID URI value, which is your tenant + “/ListService”. When you click OK, you are prompted to sign in as a Global Administrator for the tenant. This is because Visual Studio is going to do several nice things for you, including registering the app and setting up the configuration settings for you.

Sign in, click OK, then click OK again, and the project is created. If you inspect the web.config, you’ll see that several settings were added for you.

Now go look at your Azure Active Directory tenant and click on the Applications tab. Notice that an application was added for you.

Click the ListService application to see its settings, then go to the Configure tab. In the section “keys”, create a new key:

Click Save, and the key is then displayed for you, and you can now copy its value.

Go back to web.config and add a new key “ida:AppKey” with the value of the key you just created. Add a key “ida:Resource” which points to your SharePoint Online tenant (note: this need not be the site collection you are accessing). Finally, add a key “ida:SiteURL” that points to your site collection.

Give the Web API Permission

The Web API has been registered with Azure AD, we now need to give it some permissions. In Azure AD, select your Web API application and choose Manage Manifest / Download Manifest.

We are prompted to download and save a .JSON file.

Save it, and then open it with Visual Studio 2013. If you have the Visual Studio 2013 Update 2 RC installed, you will be delighted to see color-coding while editing the JSON. There’s a property called appPermissions that we need to edit.

We’ll replace this with the following:

Code Snippet

"appPermissions": [
{
"claimValue": "user_impersonation",
"description": "Allow full access to the To Do List service on behalf of the signed-in user",
"directAccessGrantTypes": [],
"displayName": "Have full access to the To Do List service",
"impersonationAccessGrantTypes": [
{
"impersonated": "User",
"impersonator": "Application"
}
],
"isDisabled": false,
"origin": "Application",
"permissionId": "b69ee3c9-c40d-4f2a-ac80-961cd1534e40",
"resourceScopeType": "Personal",
"userConsentDescription": "Allow full access to the To Do service on your behalf",
"userConsentDisplayName": "Have full access to the To Do service"
}
],

The result looks like this:

Save it, then upload it to Azure by going to Manage Manifest and Upload Manifest.

The last thing we need to do is to grant our Web API application permission to call the O365 APIs. In Azure AD, go to the Configure tab for your application. We will grant the Web API permission to “Read items in all site collections” and “Create or delete items and lists in all site collections”.

Check for User Impersonation

In the previous step, we added the appPermission claim “user_impersonation”. We will check for the user_impersonation scope claim, making sure it was registered for the Web API application in Azure AD. We need to perform this check every time an action is executed for our controller, so we create a filter. It doesn’t matter where you put the class, but I prefer to put this in a new folder named Filters in my Web API project.

Code Snippet

using System.Net;
using System.Net.Http;
using System.Security.Claims;
using System.Web.Http.Filters;
namespace ListService.Filters
{
public class ImpersonationScopeFilterAttribute : ActionFilterAttribute
{
// The Scope claim tells you what permissions the client application has in the service.
// In this case we look for a scope value of user_impersonation, or full access to the service as the user.
public override void OnActionExecuting(System.Web.Http.Controllers.HttpActionContext actionContext)
{
if (ClaimsPrincipal.Current.FindFirst("https://schemas.microsoft.com/identity/claims/scope").Value != "user_impersonation")
{
HttpResponseMessage message = actionContext.Request.CreateErrorResponse(HttpStatusCode.Unauthorized, "The Scope claim does not contain 'user_impersonation' or scope claim not found");
}
}
}
}

To use the filter, we apply it to the top of our controller class. Yes, I am going to be lazy and just use the ValuesController class that Visual Studio generates.

Using ADAL

We’re now ready to start doing the Azure Active Directory coding. Right-click the Web API project and choose Manage NuGet Packages. Search for “adal” to find the Active Directory Authentication Library, and use the drop-down that says “Include Prerelease” to find version 2.6.1-alpha (prerelease).

Install and accept the EULA. Next, add a class “SharePointOnlineRepository” to the Web API project. We borrow some code from the GitHub project mentioned previously to obtain the user token. This class will use the SharePoint REST API, passing an access token in the header. Here I give you two different ways to accomplish this: using XML (as in the GetAnnouncements method) and JSON (as in the AddAnnouncement method).

Code Snippet

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System;
using System.Globalization;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading;
using System.Threading.Tasks;
using System.Web;
using System.Xml.Linq;
namespace ListService.Models
{
public class SharePointOnlineRepository
{
/// <summary>
/// Get the access token
/// </summary>
/// <param name="clientId">Client ID of the Web API app</param>
/// <param name="appKey">Client secret for the Web API app</param>
/// <param name="aadInstance">The login URL for AAD</param>
/// <param name="tenant">Your tenant (eg kirke.onmicrosoft.com)</param>
/// <param name="resource">The resource being accessed
///(eg., https://kirke.sharepoint.com)
/// </param>
/// <returns>string containing the access token</returns>
public static async Task<string> GetAccessToken(
string clientId,
string appKey,
string aadInstance,
string tenant,
string resource)
{
string accessToken = null;
AuthenticationResult result = null;
ClientCredential clientCred = new ClientCredential(clientId, appKey);
string authHeader = HttpContext.Current.Request.Headers["Authorization"];
string userAccessToken = authHeader.Substring(authHeader.LastIndexOf(' ')).Trim();
UserAssertion userAssertion = new UserAssertion(userAccessToken);
string authority = String.Format(CultureInfo.InvariantCulture, aadInstance, tenant);
AuthenticationContext authContext = new AuthenticationContext(authority);
result = await authContext.AcquireTokenAsync(resource, userAssertion, clientCred);
accessToken = result.AccessToken;
return accessToken;
}
/// <summary>
/// Gets list items from a list named Announcements
/// </summary>
/// <param name="siteURL">The URL of the SharePoint site</param>
/// <param name="accessToken">The access token</param>
/// <returns>string containing response from SharePoint</returns>
public static async Task<string> GetAnnouncements(
string siteURL,
string accessToken)
{
//
// Call the O365 API and retrieve the user's profile.
//
string requestUrl = siteURL + "/_api/Web/Lists/GetByTitle('Announcements')/Items?$select=Title";
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, requestUrl);
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/atom+xml"));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
HttpResponseMessage response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
string responseString = await response.Content.ReadAsStringAsync();
return responseString;
}
// An unexpected error occurred calling the O365 API. Return a null value.
return (null);
}
/// <summary>
/// Gets the form digest value, required for modifying
/// data in SharePoint. This is not needed for bearer authentication and
/// can be safely removed in this scenario, but is left here for posterity.
/// </summary>
/// <param name="siteURL">The URL of the SharePoint site</param>
/// <param name="accessToken">The access token</param>
/// <returns>string containing the form digest</returns>
private static async Task<string> GetFormDigest(
string siteURL,
string accessToken)
{
//Get the form digest value in order to write data
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(
HttpMethod.Post, siteURL + "/_api/contextinfo");
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/xml"));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
HttpResponseMessage response = await client.SendAsync(request);
string responseString = await response.Content.ReadAsStringAsync();
XNamespace d = "https://schemas.microsoft.com/ado/2007/08/dataservices";
var root = XElement.Parse(responseString);
var formDigestValue = root.Element(d + "FormDigestValue").Value;
return formDigestValue;
}
/// <summary>
/// Adds an announcement to a SharePoint list
/// named Announcements
/// </summary>
/// <param name="title">The title of the announcement to add</param>
/// <param name="siteURL">The URL of the SharePoint site</param>
/// <param name="accessToken">The access token</param>
/// <returns></returns>
public static async Task<string> AddAnnouncement(
string title,
string siteURL,
string accessToken)
{
//
// Call the O365 API and retrieve the user's profile.
//
string requestUrl =
siteURL + "/_api/Web/Lists/GetByTitle('Announcements')/Items";
title = title.Replace('\'', ' ');
//get the form digest, required for SharePoint list item modifications
var formDigest = await GetFormDigest(siteURL, accessToken);
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add(
"Accept",
"application/json;odata=verbose");
HttpRequestMessage request =
new HttpRequestMessage(HttpMethod.Post, requestUrl);
request.Headers.Authorization =
new AuthenticationHeaderValue("Bearer", accessToken);
// Note that the form digest is not needed for bearer authentication. This can
//safely be removed, but left here for posterity.
request.Headers.Add("X-RequestDigest", formDigest);
var requestContent = new StringContent(
"{ '__metadata': { 'type': 'SP.Data.AnnouncementsListItem' }, 'Title': '" + title + "'}");
requestContent.Headers.ContentType =
System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json;odata=verbose");
request.Content = requestContent;
HttpResponseMessage response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
string responseString = await response.Content.ReadAsStringAsync();
return responseString;
}
// An unexpected error occurred calling the O365 API. Return a null value.
return (null);
}
}
}

We will accept an HTTP POST from the caller to insert new announcements into the list. The easiest way to do model this is to create a class with the values that will be posted. I add a new class “Announcement” to the Models folder in my Web API project.

Code Snippet

namespace ListService.Models
{
public class Announcement
{
public string Title { get; set; }
}
}

Now that we have the repository class that interacts with SharePoint, and we have our new model class, we update the ValuesController class. The Get action will simply return the entire string of data back from SharePoint. The Post action will read data from the form data, add an announcement to SharePoint, and then return the SPList data for the item. I leave it as an exercise to the reader to do something more meaningful with the data such as deserializing it into a model object.

Code Snippet

using ListService.Filters;
using System.Collections.Generic;
using System.Configuration;
using System.Threading.Tasks;
using System.Web.Http;
namespace ListService.Controllers
{
[Authorize]
[ImpersonationScopeFilter]
public class ValuesController : ApiController
{
// GET api/values
public async Task<string> Get()
{
string clientID = ConfigurationManager.AppSettings["ida:ClientID"];
string appKey = ConfigurationManager.AppSettings["ida:AppKey"];
string aadInstance = ConfigurationManager.AppSettings["ida:AADInstance"];
string tenant = ConfigurationManager.AppSettings["ida:Tenant"];
string resource = "https://kirke.sharepoint.com";
string accessToken = await Models.SharePointOnlineRepository.GetAccessToken(
clientID,
appKey,
aadInstance,
tenant,
resource);
var ret = await Models.SharePointOnlineRepository.GetAnnouncements(
"https://kirke.sharepoint.com/sites/dev",
accessToken);
return ret;
}
// POST api/values
public async Task<string> Post(Models.Announcement announcement)
{
string clientID = ConfigurationManager.AppSettings["ida:ClientID"];
string appKey = ConfigurationManager.AppSettings["ida:AppKey"];
string aadInstance = ConfigurationManager.AppSettings["ida:AADInstance"];
string tenant = ConfigurationManager.AppSettings["ida:Tenant"];
string resource = "https://kirke.sharepoint.com";
string accessToken = await Models.SharePointOnlineRepository.GetAccessToken(
clientID,
appKey,
aadInstance,
tenant,
resource);
var ret = await Models.SharePointOnlineRepository.AddAnnouncement(
announcement.Title,
"https://kirke.sharepoint.com/sites/dev",
accessToken);
return ret;
}
}
}

Register the Client Application

In Azure AD, go to your directory and add a new application. Choose “Add an application my organization is developing”.

Next, choose “Native Client Application” and give it a name.

In the next screen, we provide a URL. Any URL is fine here. If we were building a Windows 8 application, then we’d provide the ms-app URL obtained from the store. To save some digital ink, this is why we chose a WPF application… any URL will do here as long as it is a valid URL (but it does not to have to actually resolve to anything). I used “https://OnBehalfOf/Client".

In the Update Your Code section, you see that a client ID was generated for you. Copy that, you’ll need it later.

In the Configure Access to Web APIs in Other Applications section, click Configure It Now. Under Permission to Other Applications, find the ListService that we modified the manifest for earlier in this process. When we modified the manifest, we modified the appPermissions section and provided a new permission. We now use this to grant the client application permission to the Web API. Choose ListService, and choose “Have full access to the To Do List service”.

Notice that we are configuring the permission for the client application here, and the only permission it needs is to access our Web API. We do not have to grant the client application access to O365 because it never talks directly to O365… it only communicates with our custom Web API.

And a reminder to self… you can change the text of the permission by downloading the manifest, editing the appPermission section with the proper text, and uploading it again. Now make sure to click Save!

Create the Client Application

Create a new WPF application. This is going to be the easiest way to get started as it is the most forgiving in terms of callback URL. If we used a Windows 8 app, we’d need to register it with the store and obtain the app ID (the one that starts with ms-app). For now, a WPF application is fine.

Add the Active Directory Authentication Library pre-release version 2.6.1-alpha NuGet package.

The UI for the application is simple, two buttons and a text box.

Code Snippet

<Window x:Class="Client.MainWindow"
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
Title="MainWindow"
Height="350"
Width="525">
<Grid>
<Button Content="Add Announcement"
HorizontalAlignment="Left"
Margin="330,80,0,0"
VerticalAlignment="Top"
Width="142"
Click="Button_Click" />
<Button Content="Get Announcements"
HorizontalAlignment="Left"
Margin="190,147,0,0"
VerticalAlignment="Top"
Width="136"
Click="Button_Click_1" />
<TextBox HorizontalAlignment="Left"
Height="20"
Margin="93,81,0,0"
TextWrapping="Wrap"
Text="TextBox"
VerticalAlignment="Top"
Width="215"
x:Name="announcementTitle" />
</Grid>
</Window>

The code behind the XAML is what’s interesting. I am using the HttpClient classes to call our custom Web API. Note how we add the form data to the request using a Dictionary. I could have moved the settings to app.config instead of hard-coding everything in the GetAuthHeader method, I leave that as an exercise to the reader as well. The GitHub sample (link at the For More Information section of this post) does a better job of putting things in app.config, I’d suggest using that as a baseline.

Code Snippet

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Windows;
namespace Client
{
/// <summary>
/// Interaction logic for MainWindow.xaml
/// </summary>
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
}
private async void Button_Click(object sender, RoutedEventArgs e)
{
//POST to the Web API to create a new announcement
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(
HttpMethod.Post, "https://localhost:44307/api/Values");
//Create the form POST data
var postData = new Dictionary<string, string>
{
{"Title",announcementTitle.Text}
};
request.Content = new FormUrlEncodedContent(postData);
//Add the authorization Bearer header
string authHeader = GetAuthHeaderValue();
request.Headers.TryAddWithoutValidation("Authorization", authHeader);
HttpResponseMessage response = await client.SendAsync(request);
string responseString = await response.Content.ReadAsStringAsync();
MessageBox.Show(responseString);
}
private async void Button_Click_1(object sender, RoutedEventArgs e)
{
// Get the list of announcements
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(
HttpMethod.Get, "https://localhost:44307/api/Values");
string authHeader = GetAuthHeaderValue();
request.Headers.TryAddWithoutValidation("Authorization", authHeader);
HttpResponseMessage response = await client.SendAsync(request);
string responseString = await response.Content.ReadAsStringAsync();
MessageBox.Show(responseString);
}
private string GetAuthHeaderValue()
{
string aadInstance = "https://login.windows.net/{0}";
string tenant = "kirke.onmicrosoft.com";
AuthenticationContext ac = new AuthenticationContext(
string.Format(aadInstance, tenant));
string webAPIAppID = "https://kirke.onmicrosoft.com/ListService";
string clientID = "67070e10-9540-444f-883b-d090d7b7be18";
string callbackUrl = "https://OnBehalfOf/Client";
AuthenticationResult ar =
ac.AcquireToken(webAPIAppID,
clientID,
new Uri(callbackUrl));
// Call Web API
string authHeader = ar.CreateAuthorizationHeader();
return authHeader;
}
}
}

Cross Your Fingers

This is a lot of configuration, and a lot of code. There are a lot of opportunities for errors here, so we’re going to cross our fingers, set the start-up projects, and run the application.

We run the application and click the button. A login screen shows itself (this is a good thing!)

I wait for a little bit and… darn it, I see this screen.

That’s not right, I should see the Announcements list data. I fire up Fiddler and watch the traffic. Looking through the requests, I notice that one of them does not have an access token value.

I double-check the code, yep… we’re providing it. What did I miss? I debug through the code and see that I do not get an access token. Hmm… maybe permissions? Let’s go double-check the Web API permissions in Azure AD.

Yep… that’s the problem. Earlier in the post I told you to add two permissions for Office 365 SharePoint Online, but apparently I forgot to hit Save. Do this step again, and this time, hit Save!

Run the application again, this time we see a different response… we get the items from our Announcements list!

We then try our operation to write an announcement to the list, and it works. The UI is horrible, but serves my purpose for now.

We then check the Announcements list in SharePoint and see the new announcement. Notice that the item was added by the Web API application on behalf of the current user!

Think about how incredibly cool that is. We just used constrained delegation to a downstream resource, all using OAuth.

For More Information

Using a existing Windows Azure AD Tenant with Windows Azure

Web API OnBehalfOf DotNet

Secure ASP.NET Web API with Windows Azure AD

Comments

Anonymous
June 02, 2014
Awesome article Kirk! Is there any documentation for the Manifest schema? Trying to get a little deeper into the permissions, and what is possible. Any help or pointers appreciated.
Anonymous
June 02, 2014
Thanks, Pete. About the only documentation available at the moment is at msdn.microsoft.com/.../dn132599.aspx. What you see is pretty much the set of options at the moment. See github.com/AzureADSamples for more samples that demonstrate the capabilities.
Anonymous
June 17, 2014
Thanks Kirk, I will look into the links!
Anonymous
August 26, 2014
Is it possible that I get access to the Mails, Files, Folders of a user using Admin credentials? Let's just say it is one form of impersonation where the Admin plays the role of a user. Is this achievable?I have changed my manifest, run Powershell commands for impersonation assignment, but nothing helps.The REST APIs give changelogs only but when I try to fetch the Item that is changed it says, "Item does not exist. It may have been deleted by another user."But the item is there, so I guess it is purely an access issue. If it is, then it is strange because what good is the Admin account then if it can't monitor such information!Much appreciated
Anonymous
May 03, 2015
Hi Kirk,I cannot get the token with the code shown above (ref function GetaccessToken).While debugging I observed that the string authHeader is always empty, so I presume this causes the token not to be generated and then to get an Authorization Denied message (302) to my client application.Any hints on this?Thanks a lot in advance, nice post!Alex Varia
Anonymous
May 06, 2015
@Alex - I don't usually update past posts. The techniques have changed somewhat, the appPermission is no longer needed as impersonation is added by default. See blogs.msdn.com/.../a-sample-sharepoint-app-that-calls-a-custom-web-api.aspx for a more recent version of how to do this. That link points to a GitHub repository where you can download a sample. Note that you have to change the appSettings values (client ID, client secret, realm, etc) with values from your environment.
Anonymous
June 29, 2015
Really nice article Kirk. So just to be clear, form digest is no longer required, when using Bearer authentication? cheers
Anonymous
June 29, 2015
@Nigel - that is correct, form digest is not required when using Bearer authentication.
Anonymous
June 29, 2015
AWESOME!!!!
Anonymous
December 07, 2016
The comment has been removed
- Anonymous
  December 13, 2016
  I haven't worked with this code in some time. It worked at the time of writing. It is similar to the official sample, https://github.com/Azure-Samples/active-directory-dotnet-webapi-onbehalfof, which hasn't been modified in 8 months. Unsure what might have changed.

Share via

Calling O365 APIs from your Web API on behalf of a user

Background

Manage O365 Tenant from Azure Management Portal

Create the Web API Project

Give the Web API Permission

Check for User Impersonation

Using ADAL

Register the Client Application

Create the Client Application

Cross Your Fingers

For More Information

Comments

Additional resources