The API Economy: Consuming Our Web API from a Single Page App

Article
03/27/2015

This post shows how to consume a Web API secured with Azure Active Directory using ADAL.js.

Background

This post is part of a series on building a SharePoint app that communicate with services protected by Azure AD.

Part 1 - An Architecture for SharePoint Apps That Call Other Services
Part 2 - Using OpenID Connect with SharePoint Apps
Part 3 – Call O365 Exchange Online API from a SharePoint App
Part 4 – A Sample SharePoint App That Calls A Custom Web API
Part 5 – The API Economy: Consuming Our Web API from a Single Page App (this post)

As originally proposed in the post An Architecture for SharePoint Apps That Call Other Services, changing our architecture to use a Web API affords new possibilities for our application to enable secure communication from multiple types of clients. One client for the Web API was our SharePoint app. Another client can now be a Single Page App written using Angular. Realizing there’s a ton of geekery that I’ve written on this, I put a big red arrow in the architecture diagram to show “You Are Here”.

To achieve this awesomeness, we will leverage the ADAL.js library. In fact, you’ll see we are now at the point that we don’t have to really write much code at all to make this work.

The code for this post is available at https://github.com/kaevans/spapp-webapi-exchange, including the SPA and Web API projects.

Create the Web Application

I could do this with any platform since I am just using HTML and JavaScript files. I thought about doing this in Eclipse using a Java application, but decided to just stick with Visual Studio. In Visual Studio, create a new ASP.NET Web Application project.

On the next page, choose Empty. This will generate a project with no content.

Change the project’s “SSL Enabled” property to True. Remember we only exchange OAuth tokens over SSL, let’s be safe out there people.

Register the SPA App with Azure AD

Go to the Azure Management Portal (https://manage.windowsazure.com), go to the Applications tab for your Azure AD tenant, and choose Add to add a new application.

When prompted, choose “Add an application my organization is developing”.

Provide a name for the new application, and set the type to “Web application and/or Web API”.

On the properties page, provide the sign-in URL for the application, which is the SSL URL that you obtained when you created the web application.

The pieces of information you primarily need are (1) the client ID and (2) the APP ID URI. The reply URL (3) and the sign-in URL (not shown) need to be updated once you deploy your application.

Scroll to the bottom of the page in the permissions section and click Add application.

In the next screen, choose your custom Web API. Note: See the previous post A Sample SharePoint App That Calls A Custom Web API for details on how the Web API is built and how it is registered with Azure AD.

Once you’ve added the application, choose the permission and click Save.

Applications in Azure AD do not use the OAuth2 implicit flow by default, you have to add that capability by editing the manifest. Download the manifest.

Change the oauth2AllowImplicitFlow value to true.

Manifest

"oauth2AllowImplicitFlow": true,

You can see where to make the change in this screen shot.

Save the file locally, then upload it to the management portal by choosing the “Upload manifest” button for the application.

Create the SPA

I am going to use the SinglePageApp-WebAPI-AngularJS-DotNet sample from the Azure AD team as a starting point. If you want more details on creating single page apps with Angular.js, go through that sample as there is some good information to be discovered there. First, I add an HTML page “index.html” and add the following markup.

index.html

<!DOCTYPE html>
<html xmlns="https://www.w3.org/1999/xhtml">
<head>
<title>Mail SPA: a SPA sample demonstrating Azure AD and ADAL JS</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css">
</head>
<body ng-app="mailApp" ng-controller="homeCtrl" role="document">
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed"
data-toggle="collapse"
data-target=".navbar-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="#/Home">ADAL JS Sample</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li ng-class="{ active: isActive('/Home') }"><a href="#/Home">Home</a></li>
<li ng-class="{ active: isActive('/Mail') }"><a href="#/Mail">My Messages</a></li>
</ul>
</div>
</div>
</div>
<br />
<div class="container" role="main">
<div class="row">
<div class="col-xs-10 col-xs-offset-1" style="background-color:azure">
<div class="page-header">
<h1>Exchange Demo SPA</h1>
</div>
<p>This sample demonstrates how to take advantage of ADAL JS for adding Azure AD authentication to your AngularJS apps.</p>
</div>
</div>
<div class="row">
<div class="col-xs-10 col-xs-offset-1">
<div ng-view class="panel-body">
</div>
</div>
</div>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.25/angular.min.js"></script>
<script src="https://code.angularjs.org/1.2.25/angular-route.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script>
<script src="App/Scripts/adal.js"></script>
<script src="App/Scripts/adal-angular.js"></script>
<script src="App/Scripts/app.js"></script>
<script src="App/Scripts/homeCtrl.js"></script>
<script src="App/Scripts/mailCtrl.js"></script>
<script src="App/Scripts/mailSvc.js"></script>
</body>
</html>

Notice at the bottom of the page, we are referencing scripts in the App/Scripts folder. I add a folder, “App”, and two subfolders “Scripts” and “Views”.

I copied adal-angular.js and adal.js from the SinglePageApp-WebAPI-AngularJS-DotNet sample into the Scripts folder. I am not providing a code listing for those assets here.

Let’s add two HTML pages to the Views folder. The first, Home.html, is just used to let me know that the Angular routes are working.

Home.html

<div>
home sweet home
</div>

The next HTML page will show our email messages.

Mail.html

<div ng-init="populate()">
<p class="error">{{error}}</p>
<p>{{loadingMessage}}</p>
<div class="panel">
<table class="table table-striped">
<tbody>
<tr data-ng-repeat="item in mailList">
<td>
<p>{{item.From}}</p>
</td>
<td>
<p>{{item.Subject}}</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>

I add a JavaScript file called homeCtrl.js that will be the controller when on the home page.

homeCtrl.js

'use strict';
angular.module('mailApp')
.controller('homeCtrl', ['$scope', 'adalAuthenticationService','$location', function ($scope, adalService, $location) {
$scope.isActive = function (viewLocation) {
return viewLocation === $location.path();
};
}]);

Next I add an indexCtrl.js to handle any callbacks to the index page.

indexCtrl.js

'use strict';
angular.module('mailApp')
.controller('indexCtrl', ['$scope', 'adalAuthenticationService', function ($scope, adalService)
{
}]);

Next we need a controller to display our email messages from our custom Web API.

mailCtrl.js

'use strict';
angular.module('mailApp')
.controller('mailCtrl', ['$scope', '$location', 'mailSvc', 'adalAuthenticationService', function ($scope, $location, mailSvc, adalService)
{
$scope.error = "";
$scope.loadingMessage = "Loading...";
$scope.mailList = null;
$scope.populate = function ()
{
mailSvc.getItems().success(function (results)
{
$scope.mailList = results;
$scope.loadingMessage = "";
}).error(function (err)
{
$scope.error = err;
$scope.loadingMessage = "";
})
};
}]);

And finally the service that will call our custom API.

mailSvc.js

'use strict';
angular.module('mailApp')
.factory('mailSvc', ['$http', function ($http)
{
//var apiEndpoint = "Enter the root location of your Mail API here, e.g. https://contosotogo.azurewebsites.net/";
var apiEndpoint = "https://localhost:44350/";
$http.defaults.useXDomain = true;
delete $http.defaults.headers.common['X-Requested-With'];
return {
getItems: function ()
{
return $http.get(apiEndpoint + 'api/mail');
}
};
}]);

OK, that’s all our controllers and our one service. Now we need to add the app.js that initializes everything. Using the adal.js library and adal-angular.js implementation, we can simply provide the tenant and the clientId for our application. The endpoints object lets us specify an external endpoints that will be called. In this case, the Web API runs on a different port than our SPA application. Additionally, we provide the APP ID URI for the Web API application registration in Azure AD (see the previous post A Sample SharePoint App That Calls A Custom Web API for details on how the Web API is built and how it is registered with Azure AD).

The App.js file uses the “requireADLogin” property on the Angular route provider to ensure that we are first authenticated before accessing the Mail view.

app.js

'use strict';
angular.module('mailApp', ['ngRoute','AdalAngular'])
.config(['$routeProvider', '$httpProvider', 'adalAuthenticationServiceProvider', function ($routeProvider, $httpProvider, adalProvider) {
$routeProvider.when("/Home", {
controller: "homeCtrl",
templateUrl: "/App/Views/Home.html",
}).when("/Mail", {
controller: "mailCtrl",
templateUrl: "/App/Views/Mail.html",
requireADLogin: true,
}).otherwise({ redirectTo: "/Home" });
var endpoints = {
"https://localhost:44350/":
"https://kirke3.onmicrosoft.com/ExchangeDemoAPI",
};
adalProvider.init(
{
tenant: 'kirke3.onmicrosoft.com',
clientId: 'c2b3f3bc-1b6a-4c17-8b89-b5e474dd3949',
extraQueryParameter: 'nux=1',
endpoints: endpoints,
cacheLocation: 'localStorage', // enable this for IE, as sessionStorage does not work for localhost.
// Also, token acquisition for the To Go API will fail in IE when running on localhost, due to IE security restrictions.
},
$httpProvider
);
}]);

That’s all there is to our SPA application. A few HTML files and some JavaScript and we are done.

Testing

To test the application, I changed the application startup projects to start just my Web API project and the SPA project.

I run the application, and it opens to the Home controller view.

Click the “My Messages” link in the navigation bar, and you are prompted to log in. This is because the route provider has the property requireADLogin set to true.

Log in, and then we can see our email message. This was a SPA application calling a custom Web API using OAuth, which then in turn calls the O365 Exchange Online API on behalf of the current user.

Summary

In case you didn’t see how incredibly cool that was, let me point it out as clearly as I can. We just created an application that is purely HTML and JavaScript that enables the user to log on using Azure Active Directory, securely calls a custom Web API, and that Web API calls the O365 Exchange Online API on behalf of the current user to retrieve email messages.

For More Information

Enabling Cross-Origin Requests in ASP.NET Web API 2

ADAL.js library

SinglePageApp-WebAPI-AngularJS-DotNet

OAuth Fiddler Extension – extension for Fiddler that enables you to inspect OAuth tokens.

https://github.com/kaevans/spapp-webapi-exchange – source code for this post, including the SPA and Web API projects

Comments

Anonymous
April 01, 2015
Hi Kirk, Thank you so much for this series! Not just text but with github examples, this is very helpful and interesting.
Anonymous
May 25, 2015
Hi Kirk, thank that's a very interesting post! Is it possible to access a on premise SharePoint instead O365 in behalf of the user with this approach?
Anonymous
May 26, 2015
@Stefan - The approach I detailed here does not work with on-prem SharePoint. That's not to say it's not possible: It is possible, but using a different approach that is outside the scope of these posts. My focus here is the value of the O365 APIs and other APIs registered with Azure AD.
Anonymous
September 13, 2016
if I put the SPA application within a SharePoint Hosted Add-in, will I still be prompted for a user name and password. Is there a mechanism to do it for SharePoint hosted add-in.

Share via