Windows Azure Active Directory – CRUD for users and groups

Windows Azure Active Directory?

If you are not informed about the subject I recommend you to have a look on this Azure Info site.

Which resources are there?

The Azure AD contains the following entities:

- Users

- Groups

- Contacts

- Roles

Access to the directory or on the “directory graph”

Although the name contains “active directory” and the entities are known this Azure service hasn’t a lot in common with a usual active directory. Probably the biggest difference: there is no LDAP access – it’s a REST API. The informations are situated in the so called Windows Azure Active Directory Graph. Applications that are currently working with an Active Directory have to be rewritten for Windows Azure AD.

REST… or also OData

The endpoint is a REST or a OData API. If OData is the classiest way is controversial but at least the team is constantly working on supporting more OData features.

Basically there are two types of queries:

“Common Queries”: an easy API that helps you to get all the information out of the AD.

“Differential Queries”: This API is interesting if you have to synchronize huge amounts of information between your own application and the Azure AD. With this API you are able to find out the changes on the resource between two requests.

News: no nice NuGet package

Away from theory and into the practical part. Currently there is no NuGet Package or anything else that makes the work with the Graph API an easy job. There is an old NuGet package but it contains sample code only and the API is quite old and doesn’t support all functions that are available in the newest versions (for example group management).

Alternative: handmade request

Since it is a REST API all you need is a HttpClient and you can develop against it. The MSDN offers some examples for that:

GET https://graph.windows.net/contoso.onmicrosoft.com/users/[email protected]?api-version=2013-04-05 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net

Since the API makes a quick progress and I don’t want to develop the “OData”-like queries by myself there is one other way. It seems like this is the recommended way anyway.

The Code: we are going to use sample code – hmmm…

The Azure graph team has published several examples, including a “Graph API Helper Library”, on this MSDN site. The library is also used in the .NET sample.

The sample is an MVC application that projects a CRUD on users and groups. The GraphHelper includes the generated “DataServices” from the OData-endpoint and some utilities around it. With that you can authenticate yourself quite easy against the Grap API and send a request.

The sample includes default settings but the app has only “reading” rights on the AD.

Some screenshots from the application:

Generated code … uh …

The “generated” code is from the OData-endpoint and anything but “pretty”. There is also a “partial” class because the generated class doesn’t know the entity.

The main code is not very complex but the syntax is kind of unsexy.

For example that is how to call all groups:

//
        // GET: /Group/
        // Get: /Group?$skiptoken=xxx
        // Get: /Group?$filter=DisplayName eq 'xxxx'
        public ActionResult Index(string displayName, string skipToken)
        {
            QueryOperationResponse response;
            var groups = DirectoryService.groups;
            // If a filter query for displayName  is submitted, we throw away previous results we were paging.
            if (displayName != null)
            {
                ViewBag.CurrentFilter = displayName;
                // Linq query for filter for DisplayName property.
                groups = (DataServiceQuery)(groups.Where(group => group.displayName.Equals(displayName)));
                response = groups.Execute() as QueryOperationResponse;
            }
            else
            {
                // Handle the case for first request vs paged request.
                if (skipToken == null)
                {
                    response = groups.Execute() as QueryOperationResponse;
                }
                else
                {
                    response = DirectoryService.Execute(new Uri(skipToken)) as QueryOperationResponse;
                }
            }
            List groupList = response.ToList();
            // Handle the SkipToken if present in the response.
            if (response.GetContinuation() != null)
            {
                ViewBag.ContinuationToken = response.GetContinuation().NextLinkUri;
            }
            return View(groupList);
        }

Recommendation: Take a look at the sample and don’t link to the generated classes

The sample contains “Common Queries” plus CRUD-operations and offers an easy entry. I wouldn’t recommend using the entities directly because the generated classes contain some “imperfections” like small property-names.

More information in the MSDN on the Graph API site.