Getting Started with adal.js and the Office 365 APIs

Scot Hillier

by Scot Hillier on 6/30/2015

Share this:
Print

Article Details

Date Revised:
6/30/2015

Applies to:
adal-angularjs, adaljs, Angular, javascript, Office 365 API, SharePoint development, SharePoint Online, SPA


Single-page applications (SPA) continue to receive significant attention from developers inside and outside of the Microsoft world. SPAs are popular because they provide an excellent end-user experience that feels much more like using a desktop application. Furthermore, JavaScript frameworks like Angular and responsive frameworks like Bootstrap make them a pleasure to code across all devices. The architecture of a SPA, however, can present some development and security challenges.

Understanding implicit flow

Because client-side JavaScript is not an appropriate place for security and sensitive business rules, SPAs are generally paired with a back-end REST service that provides access to data and implements business rules. The challenge for SPA developers is authenticating to the associated REST service because – once again – client-side JavaScript is generally inappropriate for managing security credentials.

Last year at this time, I wrote an article describing how to manage OAuth tokens in single-page applications so a SPA could authenticate to a REST service in a different domain. This article was based on work I had completed with Andrew Connell as a demo for Microsoft. The idea was to create a WebAPI that was in the same domain as the SPA (so that security was essentially automatic) and then have that service call to another service in a different domain using OAuth. This design allowed the intervening service to utilize a Client Id and Client Secret to communicate with the back-end REST service. The solution worked, but the plumbing was complex.

Fortunately, the OAuth specification recognizes the need for client-side JavaScript to communicate more directly with REST services in another domain and so describes a process called implicit flow. In the classic OAuth flow, clients make separate requests for authorization codes and access tokens. In the implicit flow, clients receive an access token as a result of an authorization request. In straightforward terms, this means that the client gets an access token based on the current user successfully logging in. The end result is that the client never has to know a secret code. This is important because JavaScript can’t defend secrets – if you save it in a variable, anyone can see it.

At the time I wrote the first article, there was no real support in the Office 365 space for implicit flow. That, however, has changed because Microsoft has released two JavaScript libraries to support implicit flow: adal.min.js and angular-adal.min.js. The first library provides the functionality necessary to use implicit flow, and the second library supports using that flow from an Angular application. In this article, I’ll show you how to get started building an Angular application that uses implicit flow to talk to SharePoint. You can find the complete code for this article in the IT Unity GitHub repository.

Starting a project

In order to get started, create a new ASP.NET web application. Select an Empty project, and make sure it has No Authentication. This is because the implicit flow will force a user login to Azure Active Directory without any other support required.

Create a new ASP.NET application with no authentication

Figure 1, Create an empty ASP.NET application with no authentication

Once the new application project is created, enabled SSL in the project properties. Next, you can add support for Angular and Bootstrap by including the associated NuGet packages. Using the NuGet Package Manager, simply run the following commands.

Install-Package AngularJS.Core
Install-Package AngularJS.Route
Install-Package bootstrap

Once Angular and Bootstrap are in place, you can add a new page to the application. For this example, I’ll simply add an index.html page. We’ll only need one since this is a single-page application. In the head section, add a reference to the bootstrap.css style sheet. In the body of the page, add references to the Angular, Bootstrap, and adal libraries. In the example, the adal libraries are added through a CDN, but you could also download the files and include them directly in the project.

<script src="Scripts/bootstrap.js"></script>
<script src="Scripts/angular.js"></script>
<script src="Scripts/angular-route.js"></script>
<script src="//secure.aadcdn.microsoftonline-p.com/lib/1.0.0/js/adal.min.js"></script>
<script src="//secure.aadcdn.microsoftonline-p.com/lib/1.0.0/js/adal-angular.min.js"></script>

Add an application to Azure AD

Before you start coding the project, you should add a new application to Azure Active Directory. This application definition will contain the Client Id and permissions for the project. Inside of the Azure portal, create the new application definition and assign appropriate permissions. In the example, I am granting access to the user’s files.

In Azure portal, create the new application definition and assign appropriate permissions

Figure 2, Grant application permissions

Implicit flow is not enabled by default; you must edit the application manifest to enable it. Within the application definition in Azure Active Directory, click Manage Manifest and download the manifest file. Change the oauth2AllowImplicitFlow value to true, save the file, and then upload it back into the application definition.

If you are using the sample code from the ITUnity repo, then be sure to utilize your tenancy and client information in the sample code.

Coding the project

Once the application is set up, you can return to the project and begin coding. Start by adding a custom JavaScript file to the project and referencing it in the index page. This is where your Angular application and ADAL will be initialized. In order to initialize the library, you’ll need information about your tenancy and the Client Id for the application. Listing 1 shows the complete code for the sample application.

Listing 1, Initializing the application

var myApp = angular.module("MyApp", ["ngRoute", "AdalAngular"]);
 
myApp.config(["$routeProvider", "$httpProvider", "adalAuthenticationServiceProvider",
    function ($routeProvider, $httpProvider, adalProvider) {
 
        'use strict';
 
        //Initialize ADAL
        adalProvider.init({
            tenant: "spsboston.onmicrosoft.com",
            clientId: "5f4d2ee7-d0e4-4f37-a5c7-86fe4889bf15",
            cacheLocation: "localStorage",
            endpoints: {
        'https://spsboston.sharepoint.com/_api/': 
        'https://spsboston.sharepoint.com',
        'https://spsboston-my.sharepoint.com/_api/v1.0/me':
        'https://spsboston-my.sharepoint.com'
            }
        }, $httpProvider);
 
        //Configure routes
        $routeProvider.when("/", {
            controller: 'homeCtrl',
            templateUrl: 'Views/home.html',
            requireADLogin: false
        });
        $routeProvider.when("/documents", {
            controller: 'docsCtrl',
            templateUrl: 'Views/docs.html',
            requireADLogin: true
        });
        $routeProvider.otherwise({
            redirectTo: "/"
        });
    }
]);

ADAL takes the form of an Angular module that can be injected into the application on startup. The adalAuthenticationServiceProvider can then be injected into the config method where the init method is used to initialize it with the Client Id and information about tenancy endpoints. Once initialized, adal-angular.js listens for HTTP calls to the specified endpoints and will automatically add the required access token to the call. This makes it very easy for you to code the REST calls because authentication is handled for you.

When you configure routing for the app, you can have secure and non-secure routes. If you want to secure a route, simply decorate it with requireADLogin: true. If the user is not yet logged in, then they will be directed to a login page before your secure page is displayed. From that point on, you can just code controllers, directives, etc., in the normal way. In the sample, the page that reads OneDrive for Business files is secured.

Testing the project

Once the project is written, you can run it to see how it works. After starting debugging, you can navigate to a secure route, which will prompt you for a login.

Login screen to test your adal.js project

Figure 3, Logging in

In the sample, you can click on the Documents link to display documents from your OneDrive for Business.

Test project runs and displays a list of documents using Angular with adal.js security

Figure 4, Displaying documents in Angular with adal.js security

Summary

Angular is fast becoming the most popular framework for building single-page applications. Office and SharePoint developers interested in using Angular need a way to incorporate calls to the Office 365 APIs into their applications. The new adal.js and adal-angular.js libraries make it straightforward to build Angular applications that include Office 365 data.


Topic: Development

Sign in with

Or register