azurecoder's blog

In the previous post we looked at how to setup a Windows Azure Active Directory. In this post we’ll go about consuming it. In looking into this I found a disconnect with being able to hit the ground running with building a user in WAAD and building a principal in my web application. My aim is simply to be able to use metadata from my Active Directory users so that I can effectively have a single web principal whether the user has logged in via Active Directory or via another identity provider such as Facebook.

Firstly, the project is parked on github with a test project that you can begin using straight away. You can view this here. I’ve uploaded a nuget package as well which you can get started on here.

In the last post we looked at building a new WAAD tenant so that we can set this up as an Identity Provider in Access Control Services and then use this to login to a web application via Single Sign In. WAAD is still pretty virgin so there are a few gotchas when you go through that process. When that is done though you’ll want to do something with the AD user and currently there is a disconnect between getting this going out of the box. In this post we’ll look at the Graph API which is a REST-based API which exposes Active Directory objects for a particular WAAD tenant.

In order to get started let’s take a look at a great test application at https://graphexplorer.cloudapp.net where we can peruse the graph before we begin to write code. So to start with navigate to the site.

In order to begin enter into the resource textbox:

http://graph.windows.net/mydomain.onmicrosoft.com (replace the mydomain with your domain – unless you’ve managed to bag mydomain!)

You should see the following:

When you click on any one of the links you’ll be presented with the following screen which will allow you to login to the AD.

When you enter your credentials (AppPrincipalId and SymmetricKey from the previous post) you added earlier you’ll be greeted with the following error because the ServicePrincipal we created in the previous post is not authorised for the graph.

{
“Status Code” : “Unauthorized”,
“Description” : “The remote server returned an error: (401) Unauthorized.”,
“Response” : “{“error”:{“code”:”Authentication_Unauthorized”,”message”:{“lang”:”en”,”value”:”Unauthorized request.”}}}”
}

In order to authorise the new ServicePrincipal enter the following in the Msol CmdLets and try again.

You should be able to see the graph now like below.

You’ll see that the response is clickable and you can build simple graph queries to enable you to return various users and the groups that they are members of. Everything in the graph has a unique ObjectId (where xxx is the Guid ObjectId in the query below) and you’ll be able to see from the trace that the graph uses these and filters on them to move between nodes and node sets. One example to get all of the roles and groups for a particular user is a query like this. You’ll see that everything returned is of type ReferencedObject.

https://graph.windows.net/adelastacloud.onmicrosoft.com/Users(‘User_xxx’)/MemberOf

By now you should be clicking around the graph all over the place!

If we turn our attentions to code for now and look at how this all hangs together. In the test project this is what I want to accomplish which should be fairly self-explanatory.

The code looks to check the following for a particular user:

1. That the user exists
2. The the user belongs to one or more security groups
3. Gets some personal information about the user
4. Gets the user’s thumbnail image if it exists

The user is identified by the UPN (Unique Principal Name) which will be something like myname@mydomain.onmicrosoft.com. Certainly a better reference than the ObjectId! One thing that should strike you immediately is the use of security groups instead of roles. With a traditional Active Directory there are two things you can do which can be helpful within an application.

1. Add additional metadata for the user
2. Add roles and put the user into these roles

The latter is used throughout authorisation. The roles for the WAAD are, however, not usable (and configurable through the GUI) in the same way so we can create “security groups” instead and add the user to them. From now on we will treat these groups like roles.

From the above code it can be seen that the DirectoryDataService connects to the graph initially and uses an event to intercept the request so that the correct auth headers can be added. The following is added to the request:

1. The authorization header from shared secrets (the ServicePrincipal’s symmetric key)
2. The API contract version for the graph
3. If this is a continuation of an existing session then the session key is added
4. A unique id for the request

You can see from the creation of the authorisation headers that there is a reserved principal guid for the WAAD ServicePrincipal which is used like so 00000002-0000-0000-c000-000000000000/graph.windows.net@mydomain.onmicrosoft.com. This is called the ServiceRealm and a combination of this and the AppPrincipalId and SymmetricKey is used to build the header. At this time I have a dependency on AAL which abstracts this but you can get into the guts of the protocols and build a JWT (Json Web Token). Since AAL is a rich library with a lot of features (which I’m not using – such as GUI windows etc.) I may write my own JWT parser in the next iteration. Anyway, the majority of the connection code in ActiveDirectoryRequest.cs is cobbled together from a Microsoft sample.

The simplification comes from the ActiveDirectoryUser.cs file which contains the code which abstracts a user in the WAAD. In the first we need to check whether the user exists in the WAAD using:

This will perform an OData query and use the $filter on the UserPrincipalName which should be the email address for Office365 or the fully qualified name for a new Active Directory tenant. If this returns with a value we have access to all entered metadata about the user.

The Groups property returns the groups that the user is a memberof by using the MemberOf syntax we looked at with GraphExplorer. Since this query returns all of the memberships including Roles which we’re not interested in we simply return the group names. You’ll see from the WAAD portal that all we have is a name and a description for the group so we’ll just discard the description from now. The IsInGroup method therefore checks only whether the user belongs to the group which is already in the memberships list.

Apart from all the other supplementary user properties the only thing worth diverting attention to is the thumbnail part of the code. One of the requirements I had was to display the thumbnail image from the WAAD so I exposed a thumbnail property. There is a bit of jiggory-pokery going on in the ActiveDirectoryRequest.cs GetStreamData method if you look through the code but otherwise it is fairly straightforward.

Anyway, go ahead and feel free to adapt and change. I’ll be doing another post in the next week or so to give a bit of focus to this and show how you would consume this in a web principal.

Have fun and happy holidays!