The Microsoft Office 365 team is the sponsor of this series.
Part 1 of this article series introduced a stand-alone Expense Manager application built using AngularJS, Azure Active Directory, and the Office 365/SharePoint APIs. The overall scenario discussed throughout the series revolves around integrating data from the cloud into an application that can stand on its own and run gracefully in desktop browsers and mobile/tablet browsers. If you haven't read through Part 1, I encourage you to read it first before going through this article since it provides additional context about the application and the technologies used to build it. If you're new to Microsoft Azure or Office 365 cloud services, I also recommend that you learn more about them at http://azure.microsoft.com and http://products.office.com/business/enterprise-productivity-tools.
One of the essential requirements that enterprise applications (and many non-enterprise applications) have is authentication and identity management. Although you can certainly use on-premise deployments of Active Directory (AD) or another custom security provider, Azure Active Directory (AAD) integrates directly with Office 365/SharePoint APIs (in addition to several others) and lets you harness the power of the cloud. In this article, you'll see how a custom application such as the Expense Manager application discussed in Part 1 can be registered with Azure Active Directory so that users can be authenticated. In the next article in the series, we'll explore the AAD code that's required and see how it plugs into an ASP.NET MVC application.
So what is Azure Active Directory and how do you get started using it? In a nutshell, it provides "Identity and Access Management for the Cloud" (see http://azure.microsoft.com/services/active-directory for additional details). By using the Azure management website, you can setup and integrate AAD authentication and identity management into custom applications and also use it to secure Office 365/SharePoint deployments. AAD has many additional features, but the Expense Manager application discussed in this series uses it strictly for authentication purposes so that Office 365/SharePoint lists can be accessed and modified.
You can manage your Azure account and AAD functionality by going to https://manage.windowsazure.com. A new Azure management portal (https://portal.azure.com) is also available but it's currently in beta (as I’m writing this article) and doesn't offer AAD features yet. It's important to point out that going through the Azure management site isn't the only solution for registering a custom application with AAD so that users can authenticate. When working with Office 365/SharePoint APIs, you can simplify the overall process by using the Microsoft Office 365 API Tools, which is another topic that will be covered in this article.
Let's get started by taking a look at how to register a custom application with AAD using the Azure management site. Once you see how to manually register an application with AAD, you'll then learn about the Microsoft Office 365 API Tools and see how they can be installed and used to register an application from within Visual Studio.
Registering an application with Azure Active Directory
In order to add AAD authentication functionality into the Expense Manager application (or any custom application), it has to be registered with AAD. The standard way to register an application is to login to your Azure account (https://manage.windowsazure.com) and click the Active Directory item on the left.
Figure 1: Login to Azure and click Active Directory to begin the process of registering an application with AAD
Once you click on Active Directory in the Azure management site, the next screen lets you select the directory that the application should be associated with. By default you'll see a Default Directory entry (Figure 2) unless you've created a custom directory.
Figure 2: Select the directory that your application should be associated with
Click the desired directory (Default Directory in this example) to be taken to a Quick Start screen that allows you to configure different directory features. The Quick Start screen provides two options for creating a new custom application and registering it with AAD, as shown by the arrows in Figure 3.
Figure 3: Quick Start for adding an application you are registering with AAD
Click Add an application you're developing and the Add Application dialog will allow you to name the application and choose if it's for the Web or a native application (such as an Android, iOS, or Windows Phone).
Figure 4: Name the application and indicate if it is a Web app / Web API or native app
Give the application a name and click the arrow icon to go to the next step.
The next screen (Figure 5) asks for the sign-on URL that you'd like to use for your application and a unique App ID URI. You can change both values later so you can put localhost entries into the textboxes initially while starting development.
Figure 5: Add the sign-on URL that you'd like to use for your application in AAD and a unique App ID URI
Note that the port value would be the one Visual Studio assigned to your app or one you manually configured. To enable https with IIS Express (which is recommended), click on your project in the Solution Explorer and then go to the Properties window as shown in Figure 6.
Figure 6: Set the SSL URL for your application in the Project Properties window
In the AAD Add Application dialog, click the checkmark icon and the application will be registered with AAD and you'll be taken to its Quick Start screen. From there you can click the Configure menu option to get to details about the application.
Figure 7: Some of the properties for an application that has been registered in AAD
As you scroll down in the page through the application's properties, you'll see several important pieces of information shown including the Client ID, Keys, Reply URL, and permissions (you cannot see them all in Figure 7). You can create a key/password that will be used by the application by clicking the dropdown (Figure 8) and selecting how long the key can be used.
Figure 8: Set how long the key/password for your application will work in AAD
At this point you won't see the key, but after clicking Save at the bottom of the screen, the key will be generated and displayed. The Expense Manager application uses the Client ID and key/password to associate itself with AAD (more on this later).
The Reply URL property is also important. You can add multiple URLs here such as one for http and one for https (https is, of course, recommended). The URL that's defined will be called after a user has logged into AAD.
Figure 9: The reply URL that will be called after a user successfully logs in to AAD
This will cause a special token (a SAML token, which is often referred to as a "bearer token") to be passed back to your application after a user logs in successfully. The token will then be used to authenticate into Azure or Office 365 APIs.
The final properties section in the application configuration screen allows permissions to be defined. Click the first dropdown to select an application type and then assign permissions to it. For example, from the Select application dropdown you can select Windows Azure Active Directory and set delegated permissions that allow users to sign-on and have their profiles read.
Figure 10: Select Windows Azure Active Directory and then set the application type and assign permissions
When an Office 365 account is associated with an AAD directory, you can select Office 365 SharePoint Online from the dropdown and assign permissions to it as shown in Figure 11.
Figure 11: You can assign permissions for an Office 365 account that is associated with an AAD directory
Click Save to complete the AAD registration process. From here you can use the AAD application properties in your custom app. You'll learn more about that process in the next article.
Registering an application with AAD using the Microsoft Office 365 API Tools
Now that you've seen how to manually register an application with AAD, let's look at another option that simplifies the process significantly if your goal is to work with Office 365/SharePoint APIs. To get started, you'll need to install the Microsoft Office 365 API Tools extension into Visual Studio by going to Tools à Extensions and Updates and searching for Microsoft Office 365 API Tools.
Figure 12: Install the Microsoft Office 365 API Tools extension into Visual Studio
Once you have installed the tools, create a new ASP.NET Web Application in Visual Studio, give it a name and choose a location as shown in Figure 13.
Figure 13: Create the new Web Application named ExpenseManager.
After you click OK, another dialog will appear that allows a project type to be chosen. Select the Empty project and check the MVC checkbox in the dialog that appears (note that a Web Forms project can be created and used as well, if desired). Click OK to have Visual Studio add the folders and core references for the MVC project.
Figure 14: Click OK to have Visual Studio add the folders and core references for the MVC project.
The Microsoft Office 365 API Tools add a new Connected Service option into Visual Studio that can be used to register a custom application with AAD and assign permissions. To use it, right-click on the project in the Solution Explorer and select Add à Connected Service. The dialog in Figure 15 will appear.
Figure 15: Use the Microsoft Office 365 API Tools to register your app with your Microsoft Azure directory associated with your Office 365 tenant.
Click the Register your app link and login using your Office 365 Organizational Account. Once you're logged in, you'll see the following services listed in figure 16.
Figure 16: Set permissions for the services your app will use in your Office 365 tenant.
Since the Expense Manager site consumes Office 365/SharePoint list data, you'll want to click the Sites service. From there, click the Permissions link to the right of the dialog as show in Figure 17:
Figure 17: Click the Permissions link to set Sites permissions for the app you registered
Select the checkboxes to allow reading, editing, and deleting of site content and then click Apply.
Figure 18: Check the boxes to give your application read, edit and create/delete permissions for the Sites REST APIs
Select the Users and Groups item and then click the Permissions link again. From here you can control the permissions for users/groups and allow them to sign-on to AAD. Click Apply to set the permissions for users and groups.
Figure 19: Check the box to give your application access to Users and Groups REST APIs
Click OK on the Services Manager dialog to finalize the process. Once the dialog closes, login to your Azure account in the browser, select the proper AAD directory, and then click on Applications. You'll see that your application has been created automatically and that the proper permissions have been assigned to it. The name of the application is based upon your project name.
In addition to the application being registered with AAD, several assemblies are also added into your project's References such as Microsoft.Office365.Discovery, Microsoft.Office365.SharePoint, and others.
Figure 20: Using the Microsoft Office 365 API Tools also adds assemblies to your project’s References
If you open web.config, you'll also notice that new app settings have been added such as ida:ClientID (your AD application Client ID) and ida:Password (your AD application key/password). Although not currently used in the Expense Manager application, the Connected Service dialog can also be used to configure permissions for additional Office 365 services such as calendar, mail, contacts, and files.
In this article you've seen how a custom application can be registered with Azure Active Directory (AAD) so that authentication functionality can be used. Although you can manually register the application with AAD, the Microsoft Office 365 API Tools can significantly simplify the process and be used directly within Visual Studio.
Although progress has been made, there's still more work to be done in order to integrate the custom application with AAD. In the next article in this series, you'll learn how to add OWIN (Open Web Interface for .NET)/AAD code into an ASP.NET MVC application to authenticate users and handle successful logins. The overall process will involve modifying the Client ID and Key/Password for the AAD application in web.config, as well as adding additional code that hooks OWIN to AAD.