Month: December 2012

This is the fifth installation in my series on WAAD. So far, we’ve managed to create a WAAD tenant domain, set up an application to use WAAD for Single-Sign On authentication and read the current user’s group memberships using the Active Directory Graph API. Oh, and let’s not forget fixing a problem where the current user’s name is null. Now that we’re here, let’s complete the picture by converting our group memberships to roles and using those roles for authorization.

Staking a claim

One of the interesting changes in .NET 4.5 that hasn’t received much attention is the fact that under the covers, all authentication providers are now claims-based. Of course, Windows Identity Foundation has been claims-based from the start – the real change is that all the common infrastructure supports claims as well. For ASP.NET MVC development, this means that all we need to do to support roles using the [Authorize(Roles = "RoleName")] attribute syntax is get role claims from somewhere. The bad news is that WAAD authentication only gives us an identity claim. The good news is we can make up our own role claims pretty easily. Our enabler is a class called System.Security.Claims.ClaimsAuthenticationManager:

Defines the base implementation for a claims authentication manager. The claims authentication manager provides a place in the claims processing pipeline for applying processing logic (filtering, validation, extension) to the claims collection in the incoming principal before execution reaches your application code.

Let’s put that to use. Create a new class and call it GroupToRoleClaimAuthenticationManager. Paste in this code:

Then configure the application to use the manager by adding this under system.identityModel/identityConfiguration in Web.config:

<claimsAuthenticationManager type="WAADDemo.GroupToRoleClaimAuthenticationManager, WAADDemo" />

Create groups

Log in to the WAAD administration portal, open up “users & groups” and switch to the “security groups” view:

Create a group called “Administrators” and add your WAAD administrator user to that group. Then, create a new user:

You don’t have to specify any additional details if you don’t want to. Click on “next” and you’ll get a page asking about user roles. Notably, you most likely don’t want to specify any roles here, as the roles are fixed and specific to WAAD:

The next page in the wizard will ask about assigning licenses. This is a feature that is specific to Office 365, so you can skip it and click “next”. Finally, the wizard will ask whether you want the generated password for your new user to be sent to someone via email. Whether you do that or not, the password will be displayed to you on the next page, so note the password down somewhere and complete the wizard.

Restricting access

Now we’ve got groups and our groups have members in them. We also have a bunch of code in our application that converts those memberships into role claims. The last thing we need to do is use that to restrict access within our application. Add a new controller action – for example, in the HomeController of the Internet Application app template:

[Authorize(Roles = "Administrators")]
public ActionResult AdminOnly() {
 return View();
}

Create a matching view, and run the application. When the application asks for you to log in, do that with the credentials of the user you just created. Since this is the first time you are logging in, instead of immediately directing you back to the application, WAAD will ask you to change the user’s password:

Change the password and log in again with the new password. Navigate to https://localhost:44302/Home/AdminOnly (substituting the port and protocol you’re actually using) and you should be greeted with a 401:

To verify that administrators can see the admin features, log out of your session by closing the browser session, re-launch the browser and log in again – this time, using your admin credentials – and the application will let you through:

You’ll probably also want to hide links to administrative features from users that don’t have the required privileges – that’s easily done with IPrincipal.IsInRole().

Phew! We’ve covered a lot of ground and come pretty far. I hope you found all this useful. As usual, questions and comments are welcome!

This is the third part in my series of posts on Windows Azure AD. In this post I go through the steps required to get your application talking to the AD Graph API, and the things that stumped me along the way. The reason we’re interested in the Graph API to begin with is that WAAD Authentication provides us with the user’s identity, but doesn’t tell us anything else about them. If we want more details, such as group memberships, we need to do some extra work.

Dependencies

We begin this part by adding a new Service Reference to the project. For the address of the service, type http://graph.windows.net/offbeatdemo.onmicrosoft.com (replacing offbeatdemo.onmicrosoft.com with your own tenant domain name) and click “Go”. After a moment of waiting, Visual Studio should generate the necessary metadata files. Here you can give your service a namespace – remember, it’s relative to your project’s default namespace, so let’s call it “ActiveDirectoryGraph”.

Once you hit OK, the service reference is generated as per usual. This is where the fun begins. Go to the References node in your project, right-click and select “Manage NuGet Packages…”. Select “Online” from the left, click on the search box and type in “Microsoft.WindowsAzure.ActiveDirectory.Authentication” and you should see a single matching package.

Click on “Install” to have NuGet fetch the library for you. The library in question is the Windows Azure Authentication Library, or AAL for short. It has all kinds of features, but the reason we need it is to authenticate our application so it can make Graph API requests. Somewhat counterintuitively, AAL depends on System.Windows.Forms of all things, so before your code will compile, you will need to add that as a reference to your project.

Using the API

Create a new class in your project – you can call it what you like, but I’m calling mine “GraphClient”. Paste in the following code – you may have to change some namespaces, but if you’ve added the service reference and the AAL package correctly, it should compile as is:

I’m not going to go through the implementation details of the class now – if you’ve got questions or feedback, leave a comment here or in the gist at GitHub. In order to use this class, what you need to do is find out some details about your tenant domain and Service Principal. It’s not entirely obvious why, but the only place where I’ve found the tenant id so far is the FederationMetadata.xml file (as documented in the article Integrating Multi-Tenant Cloud Applications with Windows Azure Active Directory) – note that the file I linked to is the federation metadata for my demo tenant domain, so you need to change the URL to get your own metadata. Locate the entityId attribute on the EntityDescriptor tag.

The entityId attribute looks like this: spn:00000001-0000-0000-c000-000000000000@a071bf68-ee1d-46aa-ac6d-cfddf3826050 – the emphasized part after the @ sign is the tenant id. Yours will be different from mine of course – copy the id somewhere handy, because you will need it soon. You’re also going to need the app principal id of the service principal you created in the previous installment. Finally, you’ll need to grant your application the right to read the directory, and create a symmetric key known to both WAAD and your application – it’s a key you will use to sign your requests, so WAAD will know it’s you making them. Here’s how you do all that: open the MSOL module for PowerShell and use Connect-MsolService to connect to your WAAD tenant. Run Import-Module MSOnlineExtended –Force to make all the commandlets available, and then run Get-MsolServicePrincipal | select DisplayName,AppPrincipalId to list your service principals.

PS C:\Windows\system32> Get-MsolServicePrincipal | select DisplayName,AppPrincipalId

DisplayName                             AppPrincipalId
-----------                             --------------
Microsoft.Azure.ActiveDirectory         00000002-0000-0000-c000-000000000000
Microsoft.Azure.ActiveDirectoryUX       0000000c-0000-0000-c000-000000000000
WAADDemo App                            e8a3050f-0c61-46bd-9808-ff7dd5dcdb4b

The resulting list will show you the app principal id (in this case, e8a3050f-0c61-46bd-9808-ff7dd5dcdb4b) – copy it somewhere handy. Next, we use that to create a new symmetric key with New-MsolServicePrincipalCredential:

PS C:\Windows\system32> New-MsolServicePrincipalCredential -AppPrincipalId e8a3050f-0c61-46bd-9808-ff7dd5dcdb4b
The following symmetric key was created as one was not supplied JH0QbohY5/+IW25zzukjuwPjr6mpnMhgicgVA4SfF9A=

Save the symmetric key somewhere too. As far as I know, there is no way to restore the value if you lose it – you’ll have to create a new key instead. You’ve got everything your application needs, but there’s still one more thing left to do: granting privileges.

PS C:\Windows\system32> Add-MsolRoleMember -RoleName "Service Support Administrator" `
 -RoleMemberType ServicePrincipal -RoleMemberObjectId 3dc125e6-d518-40d2-9392-87a03dac8f68

The “Service Support Administrator” role grants read-only access to the directory. The RoleMemberType switch is needed to inform WAAD that we’re granting the privilege to an application instead of a user or a group, and the RoleMemberObjectId switch identifies the Service Principal. Note that the Object Id is different from the AppPrincipalId we used earlier – if you don’t have the Object Id written down anywhere, you can use Get-MsolServicePrincipal | select DisplayName,ObjectId to get it. Now, you can use the collected values to create an instance of GraphClient and use it. Add this to a controller action:

var client = new GraphClient("offbeatdemo.onmicrosoft.com",  "a071bf68-ee1d-46aa-ac6d-cfddf3826050",
 "e8a3050f-0c61-46bd-9808-ff7dd5dcdb4b",  "JH0QbohY5/+IW25zzukjuwPjr6mpnMhgicgVA4SfF9A=");
 
var groups = client.GetUserGroups(User.Identity.Name);

return View(groups);

Now you should be able to display your user’s group memberships in the view:

Wrapping up

None of this was particularly difficult to do from a programming perspective – the trick is finding all the information you need! It doesn’t much help that most of the examples out there deal with either SaaS applications that are registered in the Seller Dashboard or applications that use ACS instead of WAAD. The steps are largely the same, but the places where you look for IDs and keys are wildly different. Merely listing the user’s group memberships isn’t very interesting. Now that we’ve got them, we could use them for authorization within the application – which is what we’re doing in the next part of this series.

Continuing where we left off in the previous post, we’ve got all the tools, so the next step is setting up the authentication itself. You probably don’t want to make a mess of the working state of your actual application. Or perhaps you don’t yet have an application to test with. For this walkthrough, you can start with a new ASP.NET MVC 4 project from Visual Studio and select Internet Application as the template. The template contains a layout that displays the current logged-in user, which demonstrates that the authentication mechanism integrates nicely with the rest of ASP.NET. After you’ve got your application open in Visual Studio, right-click on the project in Solution Explorer and select Enable Windows Azure Authentication.

Clicking on the menu item opens up a dialog that asks for your tenant domain name.

That is, unless it throws you a COMException instead. If that happens, ensure that you’ve got an IIS or IIS Express virtual directory set up for your web application. Visual Studio doesn’t let you misconfigure the virtual directory settings like this, but it might still happen if you’re running your web app as an Azure Web Role in the Compute Emulator.

Once you type in your tenant domain name, you’ll be prompted to log in. Log in with an account that has administrative access (for example, the account you created during the tenant setup process).

The prompt uses IE, so if you happen to be logged in an IE session with a Microsoft Online account that doesn’t exist in the tenant domain, you might end up with an error instead. This happens to me quite often, because I use our Office 365 apps with IE.

The easiest way to get rid of this error is to cancel the WAAD authentication setup, open up the Visual Studio web browser (View –> Other Windows –> Web Browser) and use it to navigate to the Microsoft Online logout page. Once the logout process is complete, close the Visual Studio web browser and try the WAAD authentication setup again. At this point, if everything went well, you’ll be presented with a happy green check mark.

You’ll have a number of changes in your Web.config, mostly under system.identitymodel:

The default authentication module for ASP.NET applications is the Forms Authentication module. You can only use a single authentication module for your application, and since the Forms Authentication module is configured at the web server level, it takes precedence. So make sure that your application doesn’t use the Forms Authentication module by adding this under system.webServer/modules:

<remove name="FormsAuthentication" />

A brief interlude on WAAD Single Sign-On

Before we go further, a few words on how SSO actually works. When a request comes in to your web application, the authentication module checks to see if the user is authenticated or not. This is typically done by looking at a cookie that holds some sort of authentication ticket. If the user is authenticated, then it’s all good. However, if the user is not authenticated, a bunch of things have to happen. First, the authentication module redirects the user’s browser to the identity provider. Among the information it passes on is a return address. Since the login process happens in the user’s browser, we can’t really control it. In order for things to work smoothly, we need to tell the identity provider what to do after the user has logged in. A return address tells the provider where the user should be redirected once authentication is completed. After the user logs in, the identity provider uses the return address combined with a login token to redirect back to our application. Our application invokes the authentication module, which takes the login token, verifies its validity and extracts the user’s identity. This is the point where the user is finally authenticated with our application.

I won’t pretend I understand all or even most of the security implications here, but one consideration is definitely this: you can’t let just anyone authenticate users against your directory, even if the only data you’d pass on to them would be the user name. Imagine a rogue third party that created an app that had your company’s branding and used your company’s official authentication mechanism – and then tricked your users into giving them confidential data. That’s no good, so we need to control who we give the login token out to. Which is what we’ll do next.

Configuring the Service Principal

Before your application can use WAAD authentication, it must be registered in WAAD. This registration is called a Service Principal, and a big part of what the Visual Studio wizard did for you involved creating the Service Principal. One of the things configured in the Service Principal settings is the list of accepted after-login return addresses. The wizard creates a Service Principal with a single return address: https://localhost:44302 — the port number is arbitrarily assigned, so yours might not be exactly the same. It also enables SSL for your app, so the return address will work. This is all well and good, unless your web application can’t run in that particular port – such as with Azure Web Roles in the Compute Emulator. That means you won’t get the login token from WAAD unless we add a new return address. Fire up Microsoft Online Services Module for PowerShell again. Call Connect-MsolService to authenticate, type Get-MsolService and hit tab. PowerShell will expand this to Get-MsolServicePrincipal. Hit enter… and boom! “Get-MsolServicePrincipal : The term ‘Get-MsolServicePrincipal’ is not recognized as the name of a cmdlet, function, script file, or operable program.”

Wait… what? Yeah. So PowerShell’s autocomplete suggests that there is a commandlet with this name, but then it’s not there when you try to use it. This is a weird artifact of the way the commandlets are packaged. What you now want to do is run Import-Module MSOnlineExtended –Force, and then the command will work. The –Force flag is necessary, because the extended module lives in the same binary file as the regular one, and without it, PowerShell will think it’s already well and properly loaded. In order to configure the return addresses, we need a handle on the service principal created by the Visual Studio Wizard. In the MSOL PowerShell window, type Get-MsolServicePrincipal | select AppPrincipalId,DisplayName

PS C:\Windows\system32> Get-MsolServicePrincipal | select DisplayName,ObjectId

DisplayName                             ObjectId
-----------                             --------
Microsoft.Azure.ActiveDirectory         25294a23-e33f-4b06-9bd4-c0a04f4cc155
Microsoft.Azure.ActiveDirectoryUX       081e23f3-5c2b-44b5-89e7-23cbbe7a13dc
My test app                             3dc125e6-d518-40d2-9392-87a03dac8f68

The last principal in the list is the one the wizard generated for you. Visual Studio always registers your application as “My test app”, regardless of what your app is actually called – for instance, the name of my application is the far more sensible “WAADDemo”. In my example, the generated principal’s object id is 3dc125e6-d518-40d2-9392-87a03dac8f68. In order to get a handle on that particular principal, we can run

$principal = Get-MsolServicePrincipal -ObjectId 3dc125e6-d518-40d2-9392-87a03dac8f68

To list the configured reply addresses, we type:

$principal.Addresses | select Address,AddressType

and get a return address listing

PS C:\Windows\system32> $principal.Addresses | select Address,AddressType

Address                                                             AddressType
-------                                                             -----------
https://localhost:44302/                                                  Reply

To add the final deployment and Compute Emulator reply addresses, we modify the address list we just got, then set it back to the principal:

$addresses = $principal.Addresses
$addresses.Add((New-MsolServicePrincipalAddresses -Address http://localhost:81))
$addresses.Add((New-MsolServicePrincipalAddresses -Address http://my-app.example.com))
Set-MsolServicePrincipal –ObjectId 3dc125e6-d518-40d2-9392-87a03dac8f68 -Addresses $addresses `
 -DisplayName "WAADDemo App"

The first line gets the current address list to a new variable. The next two lines create the address objects and add them to the list. The final command associates the updated address list with the principal and changes its name to “WAADDemo App” for good measure.

Finishing up

The last thing you need to do is ensure that you’re sending the correct reply address to WAAD. Edit web.config at system.identityModel.services/federationConfiguration/wsFederation and replace the value of the reply attribute with one of the reply addresses you configured in the previous step:

<wsFederation passiveRedirectEnabled="true" issuer="https://accounts.accesscontrol.windows.net/a071bf68-ee1d-46aa-ac6d-cfddf3826050/v2/wsfederation" realm="spn:e8a3050f-0c61-46bd-9808-ff7dd5dcdb4b@a071bf68-ee1d-46aa-ac6d-cfddf3826050" reply="http://localhost:81/" requireHttps="false" />

By now, when you run the application, you should be automatically redirected to the Windows Azure Authentication portal:

When you log in, you’ll be redirected back to your app as an authenticated user:

If you play with the app a bit, you’ll notice that logging out doesn’t actually work. That’s a quirk of Azure federated login – you can visit the logout URL if you like, but it won’t really take effect unless you close the browser session. Phew, that was a lot of stuff to go through! What’s interesting here is that you didn’t have to write a single line of C# code. Now, that in itself is not really a goal worth pursuing, particularly if it results in an ungodly mess of XML configuration. However, what is remarkable and desirable is that once you understand all this, setting up new applications that share the same credentials is actually a breeze. So there is a point to all this, believe it or not. Next up: User details! We’ll be reading group memberships using the Graph API.

I’ve recently had the pleasure of familiarizing myself with Windows Azure Active Directory (WAAD) as an identity provider for .NET web applications. While the Build demo makes it look easy, my path was wrought with peril and unexpected pitfalls, so I present to you a series of blog posts where I will go through the ones we encountered, in the vague hope that it will save someone else the trouble. Identity management is a complex topic, so if you are not familiar with Windows Azure Active Directory – or cloud identity in general – I recommend that you read Jouni’s article first.

What is WAAD Authentication and why do I need it?

Windows Azure Active Directory is a SaaS identity provider – that is, a way to provide Single Sign-On and authorization across a variety of services. It’s used by Office 365, so you get the biggest bang for your buck when you are already using Office 365 and want to save your users from having yet another login to remember. Of course, even if you’re not using Office 365, you can still use it to share identities between multiple applications – whether they are cloud-hosted services, on-premises web sites or even client applications on your smartphone.

Setting up

If you’ve got an Office 365 subscription (and have administrative access to it), you are already good to go. If you don’t have or want one, you can subscribe for a new Windows Azure Active Directory Tenant. You’ll be creating a new admin identity to go with that, so before you start, make sure you’re not logged in with a live account (or any other Microsoft identity, for that matter). The sign-up form is pretty straightforward. First, you fill in the basics. Then, when you’ve chosen a domain and verified its availability, you add in details of the new admin identity, and off you go – the setup redirects you to a login screen which is pre-populated with your new account data. Clicking on “Continue” leads you to the tenant administration page. That’s it, you’ve created a new WAAD tenant.

PowerShell Modules

With the prerequisites out of the way, we’ll tackle the tooling. Download and install the Microsoft Online Services module for PowerShell (32bit 64bit). This is the first real snag: there are at least three versions of this module you may find floating around, and if your module is an older version, there are things you won’t be able to do with it! If you’re having trouble with the commandlets, look at the file properties for the installer package you downloaded, specifically the Digital Signature tab. If the date of the signature is older than July 16th 2012, uninstall the package and download the new version I linked above.

After you install the module, you’re going to want to check that you can actually use it. Open the quick link from your desktop or search your start menu or start screen for Microsoft Online Services Module for Windows PowerShell.

When the shell opens up, type in:

Connect-MsolService

And you’ll be prompted for credentials. Type in the username and password of the account you created when you subscribed to your WAAD tenant or an administrative account in your Office 365 subscription:

No news is good news, so after you’ve given the credentials, if PowerShell works for a while and then says nothing, you’re good to go. If, on the other hand, you get a bunch of red text, you’ve got problems with your login that you need to sort out.

ASP.NET Fall 2012 Update

In order to make use of Visual Studio’s wizardry in configuring your application, you’re going to need the ASP.NET Fall 2012 Update. It contains a number of fixes and a feature that adds Yet Another Context-Menu Item for Visual Studio Web projects.

You can do all of this without the wizard, but it’s somewhat error-prone, so I find it best to let tools do the heavy lifting. In the next installment, I’m going to go through the steps of setting up your application for authentication.