17 Comments

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.

waad-waml-03

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.

waad-waml-05

I currently have no applications authenticating against my directory so I’ll click the Add button at the bottom of the portal.

waad-waml-06

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. 

waad-waml-07

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.

waad-waml-08

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.

waad-waml-09

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.

waad-waml-10

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.

waad-waml-11

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.

waad-waml-12

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.

waad-waml-01

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.

waad-waml-04

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.

waad-waml-15

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.

waad-waml-19

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.

waad-waml-20

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.

waad-waml-16

Once I log in using my subscription’s credentials, WAML can authenticate and pull down the list of virtual machines.

waad-waml-17

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!

24 Comments

I received an email from Hanselman this week, a forward of an email he received after posting his [much-appreciated and far too kind] blog post on WAML. The email was from a community member experiencing a behavior when trying to use WAML to create web sites (or manage their existing sites) from code running on the server side from another Windows Azure Web Site. I can imagine lots of user stories when a Web Site could be used with WAML:

  • I’m a software-as-a-service application business owner. I want to give users a form that, once filled out and submitted, will take user input and create a new web site and copy my application’s code into their web site
  • My web application needs to create a storage account when it first starts up
  • My web application needs to create a SQL Database when it first starts up

Automation isn’t limited to the desktop. With WAML you can pick and choose which areas you need to offer and install the appropriate NuGets and get up and running quickly. There are a few caveats, however, mostly deliberate design decisions based on the basic ideas of cryptography and data integrity. I spent a few hours this week talking to my good friends in the Web Sites team, along with my own awesome team in Azure Developer Experience, to work through some certificate-loading problems I was seeing in Web Sites. The ability to use a management certificate is pretty important when programming against WAML (yes, AAD support is coming soon in WAML). I’ve seen a few different forums mention similar issues. Given WAML makes use of certs, and sometimes using certs on the server side in the Web Site can be a little tricky, I thought a walk-through was in order.

How Meta. A Web Site that Makes Web Sites.

I’ve created a Visual Studio 2013 solution, with an ASP.NET project in the solution, that I’ll be using for this blog post. The code for this site is on GitHub, so go grab that first. The code in the single MVC controller shows you a list of the sites you have in your subscription. It also gives you the ability to create a new site. The results of this look like the code below.

SNAGHTML2c3c0b1

Here’s a snapshot of the code I’m using in an MVC controller to talk to the Windows Azure REST API using WAML.

There are a few areas that you’ll need to configure, but I’ve made all three of them appSettings so it should be relatively easy to do. The picture below shows all of these variables. Once you edit these and work through the certificate-related setup steps below, you’ll have your very own web site-spawning web site. You probably already have the first of these variables but if you don’t, what are you waiting for?

image

Once your Azure subscription ID is pasted in you’ll need to do a little magic with certificates. Before we get to all the crypto-magic, here’s the method that the controller calls that prepare WAML for usage by setting up an X509Certificate.

image

I’d been using a base 64 encoded string representation of the certificate, but that wouldn’t work on top of Web Sites. Web Sites needs a real physical certificate file.Which makes sense – you want for access to your subscription to be a difficult thing to fake, so this configuration you have to go through once to secure the communication? It’s worth it. The code below then takes that credential and runs some calls to the WebSiteManagementClient object, which is a client class in the Web Sites Management Package.

image

This next part is all about cryptography, certificates, and moving things around properly. It’s not too complicated or deep into the topics, just a few steps you should know just in case you need to do this again.

Don’t worry. If it were complicated, you wouldn’t be reading about it here.

Creating a Self-Signed Cert and Using the PFX and CER Files Properly with Web Sites

I’ll run through these steps pretty quickly, with pictures. There are many other great resources online on how to create certificates so I’m not going to go into great detail. This section has three goals:

  1. Create a self-signed certificate
  2. Create a *.CER file that I can use to upload to the Windows Azure portal as a management certificate
  3. Use the *.PFX file I created on the way to creating my *.CER file on my web site

To create the self-signed cert open up IIS Manager (some would prefer to do this using makecert.exe) and click the Server Certificates feature.

SNAGHTML2649c9d

Then, click the Create Self-Signed Certificate action link.

SNAGHTML267808a

You get to walk through a wizard:

SNAGHTML269d26a

Then the new certificate will appear in the list:

image

Select it and click the Export action link:

SNAGHTML26c6682

Now that you’ve got the PFX file exported, it’d be a good time to drop that into the web site. Drop the PFX file into the App_Data folder…

image

Once the .PFX is in the App_Data folder, copy it’s location into the Web.Config or in the portal’s configure tab.

image

Double-click the PFX file. Run through the subsequent steps needed to import the PFX into the personal certificate store. Once the wizard completes you’ll have the certificate installed, so the final step will be to export it. Open up your user certificates tile. I always find mine using the new Modern Tiles method.

image

Open up the file in the user certificate manager, and select the new certificate just created. Select the Export context menu.

image

Select the DER option. This is when you’ll output a CER file that can be used as your management certificate in the next step.

SNAGHTML28b0253

Save the output *.CER file on your desktop. With the PFX file set up in the web site and this file created, we’re almost finished.

Uploading the Management Cert to the Portal

With the CER file ready, all one needs to do to upload it is to go to the Management Portal. So long as the web site you’re running WAML in is trying to access resources in the same subscription, everything should work. Go to the management portal, select Settings from the navigation bar, and then select the Management Certificates navigation bar.Click the Upload button to upload the *.CER file only. NOT the PFX, yet!

image

Once the CER is uploaded it’ll appear in the list of management certificates.

image

With those configuration changes in place, I can finish the configuration by adding the password for the PFX to the Web.Config file. This part isn’t perfect, but it’s just to get you started with the difficult connecting-of-the-dots that can occur when embarking on a new feature or prototype.

image

Deploying the Site

The last step, following the configuration and certificates being set up, is to deploy the site. I can do that from right within Visual Studio using the publish web features. Here, I’m just creating a new site.

SNAGHTML2a45cae

Once the site deploys and loads up in a browser, you can see what capabilities it’ll offer – the simple creation of other Azure Web Sites.

SNAGHTML2c01155

Summary

This article covers more how to prepare a web site with the proper certificate setup and contains code that explains the actual functional code. I’d welcome you to take a look at the repository, submit questions in the comments below, or even fork the repository and come up with a better way, or to add features, whatever you think of. Have fun, and happy coding!

1 Comments

The stories you hear about working at Microsoft and how we send and receive lots of email is true. It is more true than you could imagine. I’ve been an addicted avid user of Outlook since I’ve had a job but there are some features I’ve not explored with any depth. Even with software, I sometimes strive to live a more Buddhist lifestyle and deny myself the investigation for features that I fear I will not find. That whole expecting it to be there and being disappointed when it isn’t thing is too depressing for me to go through, so I choose to minimize my expectations and not go hunting for features my life would benefit from having. No, really. I’m just lazy. No but seriously, I have this obsessive rule about not seeing a scrollbar in my Inbox. Each day when the little scrollbar icon appears, shortening the width of my Inbox by 20 (or so) pixels, I cringe. I hate having more-than-a-scroll emails in my Inbox.

The feature I’ve wanted (ever since I got the feature of not having to refresh my inbox) is to tell my inbox to stop auto-refreshing. I’d never gone hunting for it. Tonight, I did, and I found it in 5 minutes. I like this feature so much I’m going to show it off. You’ve probably seen this already, but get this – you can leave Outlook open and prevent it from checking your mail. That way, you can clean out your Inbox while simultaneously preventing it from refilling itself as you try to clean it out.

Here’s the trick. On your Outlook ribbon in any of the modes – email, calendar, tasks, whatever – click the Send/Receive ribbon. Then, toggle the Work Offline feature. I’ve highlighted my favorite part of the feature – the “if you do not want to receive new mail” message.

image

As soon as you do this, Outlook will stop checking your email for you. The status bar reflects my newfound joy, knowing I can keep my old friend open but quiet as I prune away towards inbox-zero Nirvana. In the status bar, I can see that I’m working offline. That way, once I get jittery in 15 minutes after not having received any new email, I can just look down and see why no one’s emailing me. I’ve temporarily put the incoming world on hold.

image

Whenever I’m ready to stop being anti-social, I can go back to the Send/Receive tab and see that I’m hiding via the greyed-out Work Offline toggle button.

image

Once I click that, Outlook connects and starts updating my folders…

image

After a few seconds everything is updated and I’m back online, with new fresh email to read…

image

You probably already knew about this feature, but I’m so excited I had to share it. Thanks, Outlook team, for being awesome.

12 Comments

The Windows Azure SDK team has been working hard to finish up more of the Windows Azure Management Libraries so you can use .NET code to manage your Windows Azure resources, and today’s blog will highlight one of the newest additions to the WAML stack. Today I’ll introduce you to the Windows Azure SQL Database Management Library. We released the SQL Management Library this week, and it’s loaded with features for managing your Windows Azure SQL Databases. Like the rest of the management libraries, the SQL library provides most of the functionality you’d previously only been able to do using the Windows Azure portal, so you’ll be able to write .NET code to do pretty much any level of automation against your SQL databases and servers.

Here’s a list of some of the features supported by the new SQL library:

  • Create, update, delete, and list your Windows Azure SQL Servers
  • Create, update, delete, and list your Windows Azure SQL Databases
  • Create, update, delete, and list your Windows Azure SQL Servers’ Firewall Rules
  • Import and Export SQL databases to & from Windows Azure Blob Storage

Let’s dive in to some of these features by exploring their usage in the sample code I’ve written to demonstrate all these cool new WAML features. I’ve put this code up in GitHub so you can fork it, add your own functionality and test cases, and [please, feel free] spruce up the UX if you’re so inclined. The code for this demonstration includes the demonstrations from my previous blog posts on WAML, so if you’ve been wanting to see that code, you can dive in as of this latest installment in the blog series.

The WPF app shown below sums up today’s code demonstration for using the SQL management library. Once I select my publish settings file and select the subscription in which I want to work WAML makes a REST call out to Windows Azure to retrieve the list of database servers in my subscription. I data-bind a list view in the WPF app with the list of servers. Next to each you’ll find buttons to allow for convenient access to the databases residing on the servers, as well as a button giving you access to the servers’ firewall rules.

SNAGHTML1a48f73

Creating the SQL Management Client

As with the other demonstrations, the first step is to create an instance of the SqlManagementClient class using a subscription ID and an X509 Certificate, both of which are available in my publish settings file. The code below is similar to the manner in which the other management clients (Compute, Infrastructure, Storage, and so on) are created.

image

SQL Server Operations

The code below shows how, in two lines of code, I can get back the list of servers from my subscription. Once I’ve got the list, I set a property that’s data-bound in the WPF app equal to the list of servers the REST API returned for my subscription.

image

Database Operations

Once a user clicks the “Databases” button in one of the server lines in the WPF app a subsequent call is made out to the Windows Azure REST API to pull back the list of databases running on the selected server. 

image

You can do more than just list databases using the SQL management library – you have full control over the creation and deletion of databases, too, using the easily-discoverable syntax. Below, you’ll see how easy it is to figure out using nothing more than the Intellisense features of Visual Studio to figure out how to create a new database.

image

Firewall Rules

You no longer need to load up a server in the portal to manage your firewall rules – you can do that using the SQL management library, too. The code below demonstrates how easy it is to retrieve the list of firewall rules for a particular SQL Servers. When the user hits the “Firewall Rules” button in the WPF app, this code runs and loads up the rules in the UX.

image

In addition to the SQL library, we’ve also released the preview libraries for Media Services and Service Bus, too. We’re continuing to improve the landscape of WAML every day, and have some convenience features we’re adding into the overall WAML functionality set, too. Keep watching this blog for more announcements and tutorials on the Windows Azure Management Libraries. As always, if you have any suggestions or ideas you’d like to see bubble up in the management libraries, feel free to post a comment below.

Happy Coding!

3 Comments

I am not very good at cryptography, even the most fundamental basic aspects of it. I’m humble enough to be willing to admit this (or smart enough to put it out there so folks don’t ask me questions about it, take your pick). That said, the idea of working with X509 Certificates in my code is something I obviously don’t relish doing. It’s a necessary thing, however, when working with various authentication paradigms, like the traditional method of attaching certificates to individual requests I’d like to make to the Windows Azure API. Since the first implementation of the credential-passing logic with the Management Libraries use X509 certificates, I needed to come up with an easy way of testing my code with management certificates. Luckily, the *.publishsettings files one can download from Windows Azure via techniques like the PowerShell cmdlets’ Get-AzurePublishSettingsFile command provides a Base-64 encoded representation of an X509 Certificate. This post will walk through how I use the information in a publish settings file to authenticate my requests with the management libraries.

You won’t want to put your publish settings files onto a web server, store the information in these files in your code, or anything like that. This is just for demonstration purposes, and makes the assumption you’re working on your own machine, controlled by you, while you’re logged into it in a nice and secure fashion. If some nefarious villain gets ahold of your publish settings file they could theoretically authenticate as you. Point is, be careful with these files and with the strings embedded into them. Keep them somewhere safe and secure when you’re not using them.

Once you’ve downloaded a publish settings file to your computer, you can write code that will open the files up and parse them. Don’t worry, this is pretty easy, as the files are just normal XML files. So, you can use XLinq or any other XML-parsing techniques to read the values out of the file. In my example code for this and the other posts I’m writing on the topic, you’ll notice that I’ve provided a menu you can use to open up a publish settings file. A screen shot of this application running is below:

Selecting the publish settings file

When the user clicks this menu, I simply throw open a new Open File Dialog object and allow the user to select a *.publishsettings file from their machine. The screen shot below demonstrates this.

Opening the file

When the user selects the file the code does just what you’d expect – it opens the file up, parses out the XML, and builds an array of subscription models the rest of my code will use when it needs to make calls out the API via the management libraries. The section of the code below that’s highlighted is doing something pretty simple – just building a list of a model type known as PublishSettingsSubscriptionItem to which I’ll data-bind a list of child menu items in my form.

Loading up the subscriptions

The XAML code that does this data-binding logic is below. This sample code (which will soon be available for your viewing pleasure) shown below does the data-binding magic.

Data-binding the list of subscriptions

Once this code is in place and I select a publish settings file, the menu will be augmented with the list of subscriptions found in that publish settings file.

The data-bound list

Since I’ve got my XAML wired up in a nice command-like manner, selecting any of those items will fire the SelectSubscriptionCommand method in my form’s view model class. That method in turn sets the current selected subscription so that it can be used later on by management library client classes that need the information. The code below, which is the handler method for that command, does this magic.

Setting the selected subscription

Now, whenever I need to run any management library code that reaches out to the Windows Azure REST API, I can use the properties of my selected subscription to set up the two elements of data each client needs – the subscription ID and the Base-64 encoded management certificate. The code below does exactly this to make a call out to the REST API to get the list of supported regions in the Windows Azure fabric.

Using the selected subscription

Thanks to my good buddy and evil coding genius Mike Lorbetske for MVVM-ifying this code so the demos can be easily added to support the upcoming blog posts in this series. I was mixing MVVM techniques and nasty, old-fashioned codebehind brutality together, and Mike came in just in time and helped me make this code a little more robust using MEF and some other tricks.