azurecoder's blog

Recently I’ve been looking at ways to build in Windows Azure Active Directory support into our applications. For those of you that haven’t been following the latest trends in identity Microsoft has supplied a freemium model called Windows Azure Active Directory (WAAD) which allows the integration of AD functionality for you Windows Azure or non-Windows Azure applications. I use the term freemium because they have recently announced that there is no charge for the use of AD transactions for your users. The pricing for additional services such as Rights Management have yet to be announced since WAAD is still in preview.

There are many architectural paradigms available when attempting to integrate WAAD authentication for a web site but it’s still virgin in its outlook and tooling. There are some tools available including a library released by the identity team called AAL and available nuget. I decided to write a series of 3 posts on WAAD including architectural patterns and talking through a new helper library I’ve made to aid in the integration with web applications.

In this first piece I’m going to talk through how to set up WAAD and some of the architectural patterns you can use within your application. It will containsome powershell but little code whereas part 2 will contain a lot of code and a reference to Elastacloud.Azure.ActiveDirectory which will be hosted on Github shortly and available through nuget.

There are many gotchas when trying to use WAAD. As my colleagues tell me, I’m an exception magnet so I hope some of this information will be useful to you if you come across some of the blockers that I have whilst trying to integrate WAAD into a Web Principal workflow. A lot of the information I’m writing here is on Vittorio Bertocci’s blog  although not the traps that you can fall in!

This article will show you you how to setup a new Active Directory tenant from scratch. I’ve done this and been able to integrate this into my application through Access Control Services (ACS) and also consume the WAAD Graph API which gives access to all objects in the AD via REST and OData. I’ve had problems using our existing Office 365 account which I have been able to use for Single Sign On via ACS federation but not to consume the Graph API. Later on I’ll explain why I think this is so.

To get started you’ll have to navigate to http://g.microsoftonline.com/0AX00en/5 which is the sign up link for new AD tenants. Follow the wizard and create a new domain and within minutes you’re setup. If everything goes as planned you should be able to login with your newly created domain address (me@mydomain.onmicrosoft.com) and access the AD. From the portal you should be able to manipulate users and groups as in the image below.

The WAAD portal

So now that you have a WAAD tenant you need to be able to do something with it. There are two activities which you would need to do to have comprehensive usage of WAAD within your applications. We’ll focus on being able to sign in first to our relying party (RP) application. In order to do this we must allow our application to connect to ACS so that our web application is aware of ACS and ACS is also aware of our web application. Before configuring ACS we need a way that ACS and our Active Directory tenant can be aware of each other.

For this we’ll need to download the Office 365 CmdLets and Sign In helper.

First install the sign in helper from here:

http://go.microsoft.com/fwlink/p/?linkid=236300

Then download and install the CmdLets from here:

http://go.microsoft.com/fwlink/p/?linkid=236297

There are lots of articles floating around the internet with redundant versions which can cause problems so if you click on the “Integration” link your Active Directory portal you can be assured to be using the latest. Some of the Service Principal activity you’ll need to provision the roles for the Graph API will not be present in earlier versions of the CmdLets so be weary here. Once you’re downloaded and installed fire up powershell from the desktop or start menu icon. To connect to your WAAD tenant use the following and enter your onmicrosoft.com login at the prompt.

Connect-MsolService

By default only the Office CmdLets are imported as a module so enter this at the prompt to enable access to CmdLets which allow the management of Service Principals.

Import-Module MSOnlineExtended -Force

We can then register a new address for our RP application:

$replyUrl = New-MsolServicePrincipalAddresses –Address "https://localhost:9090"

And then setup our Service Principal:

New-MsolServicePrincipal –ServicePrincipalNames @(“https://localhost:9090”) -DisplayName "Cloudzync ACS Namespace" -Addresses $replyUrl

I’ve just left the principal display name as the application reply to address but this can be customised as needed.

It’s worth noting that at this point there is a symmetric key which is generated for the principal. This will not be displayed again so make a note of this! If you don’t you’ll have to regenerate it. To check that the Service Principal exists we can look at the default application principals and the service principals should be at the bottom of the list (they are the ones that have Trusted for Delegation marked as false!)

Get-MsolServicePrincipal

Checking a Service Principal

As you can see each one has an AppPrincipalId which is how we’ll refer to them from now. The other thing that we’ll do is to look at how we can generate the credentials (sym key) again if we didn’t make a note of it.

To get the key(s) back you can use the following:

Get-MsolServicePrincipal -ServicePrincipalName http://localhost:9090

you can see in the image below that I have two keys for this principal. I can automatically generate a second using the New-MsolServicePrincipal credential and remove ones using the Remove-MsolServicePrincipalCredential. This is great if you have an enterprise key rotation policy in place.

Checking Service Principal Credentials

Now that the Service Principal (SP) has been created we’re half way done. In order to enable Single Sign In we need to setup a namespace in ACS. You will have to do this through the old Windows Azure portal. If you’re new to Azure if you login to the new portal you can get a link from you profile on the top right of the screen. Got to the Cache, Access Control and Service Bus option and create a new ACS namespace. In future you can just navigate to the management endpoint for ACS @ https://mynamespace.accesscontrol.windows.net.

When you’ve logged into ACS you need to set up a new ws-federation  Identity Provider to allow you to set up the single sign in with your application. We won’t through the setup steps here for ACS here because they are very well documented on windowsazure.com but you need 3 things to enable you federate and sign in with your web application (RP).

1. An identity provider
2. A Relying Party
3. A rule group

The first one you can setup by going through a wizard which will allow you to create the iDP using a ws-federation document. You can follow the iDP wizard entering the following URL as per the image below:

https://accounts.accesscontrol.windows.net/mydomain.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml

Where mydomain is the WAAD domain you setup earlier. It’s important to note that accounts is a special namespace if you mistake this for your own namespace and you try and sign to your RP when you’ve followed the setup steps you’ll see the following error:

“ACS50001

400

Requested relying party realm ‘<Realm URL>’ is unknown.

There was a mismatch between the AppliesTo given in the token request and the realms you have configured in ACS. Check that: 1. Your relying party has its realm configured correctly. You can do this through the Management Portal or using the Management Service, by looking at your RelyingParty.RelyingPartyAddresses entries. 2. Your relying party has been associated with the identity provider. You can also do this from the Management Portal or using the Management Service, by looking at your RelyingPartyIdentityProviders entries.”

Identity Provider in ACS

This is it you’re now ready for Single Sign in your application by using the “Identity and Access” extension in VS2012 and entering the realm (can be anything unique). Above you can see that this is https://sts.windows.net/{guid}  and is how you uniquely identify the new WAAD iDP from your application. This value also comes through as a claim in your RP so to convert this to something meaningful you’ll need to index and lookup this especially if you’re using multiple WAAD tenants with  your web application.

Identity and Access

For those of you that are still using VS 2010 you can just right-click on your web project and add STS reference. From the dialog I can then choose to select which iDPs I want to import and the relevant metadata is imported. If I have more than one I’ll get a default menu allowing me to choose who I want to authenticate with.

Active Directory Patterns

In the above image we can see the possible patterns we can put in place with WAAD. The WAAD tenant can be central to authentication and can can federate with ACS and an AD within a corporate network. In this instance it will need to use a feature call DirSync, which we’ll look at in a later post to sync accounts between on premises and cloud OR both the corporate AD (through ADFS) and WAAD can federate directly to the RP application through ACS.

In the following post we’ll looking at how to build applications using the Active Directory Graph API and the post after that how to integrate and build custom principals through the web to take advantage of all of the above. This setup process  is relatively problem free if you can avoid the one pitfall I walked into and highlighted. When we look at the Graph API we’ll consider how our application should be designed to leverage it.

Happy trails and enjoy playing with WAAD. After all it’s free!

Update: Some excellent investigative work by Lauri Kotilainen showed that the {guid}/graph.windows.net@tenantdomain was failing resolution because the prefix was not set as a ServicePrincipal name for the WAAD tenant (Microsoft.Azure.ActiveDirectory). See script here to update the SP name collection for the tenant https://gist.github.com/4338524. This will make Office 365 accessible to the Graph API.