Wednesday, October 5, 2016

Work with Azure AD via Microsoft Graph API

In this post I will show example of working application (we will use simple console application for simplicity) which will read Azure AD groups using Microsoft Graph API.

First of all we should have MS account and MSDN subscription for accessing Azure portal: https://manage.windowsazure.com. Note that we will use old Azure portal in our example, when I tried to use new portal and made the same steps there, application didn’t work. Instead it threw exception:

Code: Authorization_IdentityNotFound
Message: The identity of the calling application could not be established

May be I missed some steps there, but with steps described below application worked successfully.

Once we logged to Azure portal we need to create Azure AD directory with which we will work. Alternatively you may use existing Azure AD. In order to create it go to Active Directory > New:

Notice domain name – it should be globally unique and it will be used later in our console application. For testing let’s create several groups in newly created AD:

Now we have working AD and groups for testing, next step is to register application. Some tutorials say that you may create it in https://apps.dev.microsoft.com, but after I tried to do it and ran application I also got same exception:

Code: Authorization_IdentityNotFound
Message: The identity of the calling application could not be established

May be after you add application from https://apps.dev.microsoft.com you should go to Azure portal > Active Directory > choose your AD > Applications and add your application here explicitly. But for me the following method works: go to Azure portal > Active Directory > choose your AD > Applications > Add > Add an application my organization is developing. On the 1st wizard step specify application name and leave Web application and/or Web API selected by default:

On 2nd step we need to specify application urls. Once we develop application which won’t require user sign-on and delegating permissions from users, leave https://example.com there:

After application has been created go to its Configuration page, create new Key (or Secret. Actual value will be shown after changes will be saved). Under Permissions to other applications uncheck all Delegated permissions as we don’t need them and in Application permissions list check Read directory data. Save changes and copy Client Id and generated Key value – they will be needed in console application.

When configuration described above is completed we may implement our console application for reading Azure AD groups via Microsoft Graph. Create new console project in VS and add the following Nuget packages:

  • Microsoft Graph Core Client Library
  • Active Directory Authentication Library
  • Json.NET

In App.config add the following settings:

   1: <appSettings>
   2:   <add key="ClientId" value="..." />
   3:   <add key="ClientSecret" value="..." />
   4:   <add key="AuthorityUrl"
   5: value="https://login.windows.net/alexeydemo.onmicrosoft.com/oauth2/token" />
   6: </appSettings>

ClientId and ClientSecret should contain values copied from application registration page and AuthorityUrl should be in format https://login.windows.net/{AzureDomain}/oauth2/token, where {AzureDomain} is the domain of our Azure AD specified during creation of AD (alexeydemo.onmicrosoft.com in our example). In Program.cs add the following code:

   1: class Program
   2: {
   3:     static void Main(string[] args)
   4:     {
   5:         Console.WriteLine("before: enumGroups");
   6:         enumGroups();
   7:         Console.WriteLine("after: enumGroups");
   8:         Console.ReadKey();
   9:     }
  10:  
  11:     static async void enumGroups()
  12:     {
  13:         var graph = new GraphServiceClient(new AzureAuthenticationProvider());
  14:         try
  15:         {
  16:             Console.WriteLine("before: graph.Groups.Request().GetAsync()");
  17:             var groups = await graph.Groups.Request().GetAsync();
  18:             Console.WriteLine("after: graph.Groups.Request().GetAsync()");
  19:  
  20:             foreach (var g in groups)
  21:             {
  22:                 Console.WriteLine(g.DisplayName);
  23:             }
  24:         }
  25:         catch (ServiceException x)
  26:         {
  27:             Console.WriteLine("Exception occured: {0}", x.Error);
  28:         }
  29:     }
  30: }
  31:  
  32: public class AzureAuthenticationProvider : IAuthenticationProvider
  33: {
  34:     public async Task AuthenticateRequestAsync(HttpRequestMessage request)
  35:     {
  36:         string clientId = ConfigurationManager.AppSettings["ClientId"];
  37:         string clientSecret = ConfigurationManager.AppSettings["ClientSecret"];
  38:         string authority = ConfigurationManager.AppSettings["AuthorityUrl"];
  39:  
  40:         var authContext = new AuthenticationContext(authority);
  41:  
  42:         var creds = new ClientCredential(clientId, clientSecret);
  43:  
  44:         Console.WriteLine("before: get token");
  45:         var authResult =
  46: await authContext.AcquireTokenAsync("https://graph.microsoft.com/", creds);
  47:         Console.WriteLine("after: get token {0}", authResult.AccessToken);
  48:  
  49:         request.Headers.Add("Authorization", "Bearer " + authResult.AccessToken);
  50:     }
  51: }

There are several interesting moments. First of all note AzureAuthenticationProvider class (lines 32-50) – it is passed to constructor of GraphServiceClient (line 13) and used for getting authentication token for our app. In order to get it we retrieve client id, client secret and authority url from app.config (lines 36-38). We used AuthenticationContext.AcquireTokenAsync() methods for acquiring auth token because in our case app-only permissions are used. For applications which require users’ sign-on with their MS accounts and delegeting permissions DelegateAuthenticationProvider class should be used (see examples on Microsoft Graph site). Once authentication token is received we can query groups via GraphServiceClient.Groups.Request().GetAsync() (line 17).

Also notice that in our example async programming model is used (async and await keywords). If you are not familiar with it yet, read this MSDN article: Asynchronous Programming with async and await (C#). They key thing is that methods which are marked with async may be called asynchronously (i.e. control is returned to the caller immediately after calling this method without waiting when its execution will be completed). This is happen when we call such method with await keyword (lines 17 and 45-46). After such call control is returned to the caller of parent method immediately, and code which is located after await call will be resumed in separate thread when execution of this await call will be completed. I.e. after we call

var authResult = await authContext.AcquireTokenAsync("https://graph.microsoft.com/", creds)

in AuthenticateRequestAsync(HttpRequestMessage request) control is returned to the caller of AuthenticateRequestAsync() method and resumed in own thread after call to authContext.AcquireTokenAsync() will be completed starting from the next line after it:

Console.WriteLine("after: get token {0}", authResult.AccessToken)

I added console traces for better demo how execution flow goes. Also as tasks are completed in separate threads we need to add Console.ReadKey() to the main thread (line 8) in order to avoid its completing (and as result closing of application) before tasks are completed.

After we run the program we will get the following result:

before: enumGroups
before: graph.Groups.Request().GetAsync()
before: get token
after: enumGroups
after: get token eyJ0eXAiOiJKV1Q...
after: graph.Groups.Request().GetAsync()
Group3
Group2
Group1

As you can see calls are made asynchronously (e.g. we left enumGroups method before got token and queried groups from AD) and at the end we have list of AD groups we created earlier. Hope this tutorial will save your time and help to better understand Microsoft Graph API.

No comments:

Post a Comment