Integration with Windows Azure Active Directory was one of the main features we wanted to get into the 1.0 release of the Windows Azure Management Libraries. Since Visual Studio and even the PowerShell Cmdlets (which use WAML, in fact) already have support for AAD, it was really important to all of us on the team that we have a method of providing authentication directly via AAD from within C# code using WAML. This makes for a synonymous login experience across all three of these (and more) areas. Most importantly, it makes it easy for Windows Azure users to be able to manage all their subscription assets when they only need to login using their username/password portal credentials rather than go through the process of creating and uploading management certificates. This blog post will answer some of the questions and requests we’ve had from the community on how to tie AAD and WAML together, to create AAD-authenticated applications code that can be used to manage your Windows Azure account assets.
This won’t be a deep-dive into how AAD works, but more a short examination on how it and WAML can be used together.
I worked quite a bit with the AAD team, especially Vittorio Bertocci, on this post. Our teams have a regular meeting so we’re on the same page, but the guys on their team spent some additional cycles with us spelunking, coming up with features, and so on. As we talked about ideas, the AAD team gave me some great resources, like this post which walks through the process of setting up a client app so that it can be authenticated using AAD. Vittorio’s site has a series of great examples on how to go deeper with AAD. I won’t go too deep into the inner-working of AAD in this post, so keep check out those great resources if you want more information. Thanks to the AAD team for all your help and patience and supporting our team!
Create a client app for managing Windows Azure assets
The code for this sample application won’t be too complicated. I’m actually going to retrofit a small command line app I wrote the other day when asked by a peer in another team who wanted to export the list of Virtual Machine images in the gallery. The code for this itty-bitty application’s beginnings is below, which makes use of the Compute Management Management Library.
With this code already working using my Management Certificate, and with it being a relatively simple app, it seemed like a great case for demonstrating how easy it is to switch out the CertificateCloudCredentials for the TokenCloudCredentials class once the AAD infrastructure is set up and ready. Speaking of that, this would be a good time to walk through the process using the Windows Azure portal to set up an AAD application in my AAD directory that I can develop that will use the Management Libraries to manage my subscription.
Setting up an AAD application using the portal
To authenticate using AAD I first need to create an application in my Windows Azure subscription’s existing Active Directory tenant. To do this I go to my AAD tenant page in the portal and click the Applications tab at the top.
I currently have no applications authenticating against my directory so I’ll click the Add button at the bottom of the portal.
Selecting the second option in this list presents me with a huge list of existing applications with which AAD can integrate. Since I’m interested in authenticating an application I’m writing, I’ll click the first option.
The application I’m writing is a small console application, not a web app. Hence I’ll select the second option – Native Client Application - in the Add Application dialog, shown below. If I’d wanted to put an ASP.NET Web API up in the cloud that would use AAD on the back end for authentication, I’d select the top option, Web Application and/or Web API. The API my client app will need to access is the actual Windows Azure Service Management API, which AAD has a special provision for in the portal that will be examined in a moment.
Next, I’ll need to provide a redirect URI. Even though the application I’m writing is a native app, I still need to provide this URI to give AAD more details on the specific application that will be authenticating.
Once these settings are made, I can see the application’s client id in the portal, along with the information I provided during the application’s creation process. The MSDN code site article I mentioned above, written by the AAD team, walks through more details of how the client application authentication workflow functions and offers more details, so definitely check out that sample if you need more information on these settings. For now, what’s important to remember from this window are the client id text box and the redirect URI created below. Those two strings make up 2 of the 3 strings I’ll need to authenticate a WAML application with AAD.
The final piece of information is the AAD tenant id, which can be found by clicking the View Endpoints button in the portal when on the page for the directory I wish to use to authenticate users.
The URI provided in each of the text boxes in the resultant dialog contain a GUID. This GUID is the tenant id, so it’ll need to be copied out for use in my code.
Changing the WAML code to perform AAD authentication
Back in Visual Studio I’m ready to change the code to make use of AAD authentication. The first step is to reference the required NuGet package, the Active Directory Authentication Library (ADAL). This will enable my project the ability of prompting the user with a login dialog, into which they can enter their Microsoft account username and password. It will also add all sorts of goodness from the AAD folks that you can make use of in your client applications.
In the code I’ll add a method called GetAuthorizationHeader that will take my tenant id as a parameter. I’ll presume the calling code might want to make use of the common tenant, but will give callers the ability to pass in their own tenant GUID identifying their custom Active Directory tenant. Take note that within this method I’m making use of the application’s settings, the redirect URL and the client id property from the portal. As well. I’m passing the base URI of the Windows Azure REST API as the value for the resource parameter to the AuthenticationContext.AcquireToken method. Vittorio has a great blog post introducing ADAL and what you can do with it, so if you’re looking to dive deeper on this topic head on over to CloudIdentity.com and check it out. In a more practical implementation I should probably be setting those values up as appSetting variables, but for this demonstration code sheer pasting in the values is sufficient.
The final step in the code is to comment out the old authentication mechanism, where I was using the X509Certificate2 class to authenticate using a management certificate. In place of this code, which creates an instance of a new CertificateCloudCredentials class, I’ll make a call to the new GetAuthorizationHeader method to get my token, then use that token as a parameter to an instance of the TokenCloudCredentials class.
Authorizing access to the Windows Azure Service Management API to my client application
At this point the code almost works. However, when I run it I get an error that pretty clearly indicates what’s wrong in the exception message. Clearly, this application hasn’t been granted access to the service management API.
A recently-added (okay, a personally recently-discovered) feature within the portal allows me to specify which applications I’m going to allow access to this client application. Since I’ve not yet created any APIs that also use AAD as an authentication mechanism I’ll only see the two default items in this drop-down menu (the Graph Explorer and the Service Management API). By selecting the option Windows Azure Service Management API, I effectively grant my client application access to any of the REST API URLs available under https://management.core.windows.net. Once I save this setting, the code should run and give me back the list of Virtual Machine images from the gallery.
When I run the code this time, it works as expected. I’m prompted for my credentials, thanks to some of the functionality provided in the ADAL package.
Once I log in using my subscription’s credentials, WAML can authenticate and pull down the list of virtual machines.
From here, I could use the rest of the functionality available in WAML to do whatever I need. Now that I’m able to authenticate using AAD, I won’t need to create, upload, configure, and track my management certificates. Rather, my applications can just make use of Active Directory to log in and manage my subscription’s assets.
I hope you find this to be an exciting new option available in the Windows Azure Management Libraries. I’ve been looking forward to showing this feature off, as I think it shows two awesome areas of the client developer experience – AAD via ADAL and the REST API via WAML – being used together to create some amazing client-side magic against the Windows Azure cloud. Thanks again to the AAD folks for lending a hand from time to time with some of the details and fine tuning!