Azure Active Directory Graph Client Library 1.0


We are happy to announce the general availability of Azure Active Directory (AAD) Graph Client Library 1.0. The goal of this library is to simplify .NET developer experience to write an application that leverages Azure AD through Graph API. The library supports all the capabilities exposed by the Graph API version 2013-11-08 and it is available as a NuGet package at https://www.nuget.org/packages/Microsoft.Azure.ActiveDirectory.GraphClient/1.0.2

To install Graph Client, run the following command in the Package Manager Console

PM> Install-Package Microsoft.Azure.ActiveDirectory.GraphClient

The need for a client library.

Consuming the Graph API directly (using raw web requests) can be tedious and error prone and also preparing the request for some advanced queries is non-trivial. Another popular option to consume OData services is to use Microsoft.Data.Services.Client (WCF Data Services) which could add unnecessary complexity to the application logic. Azure Graph client library provides a simple way to access Graph and it is the recommended way to access Azure AD.

How to make a request.

The library contains definitions for all the Graph entities available along with all their properties. All the client library functions are exposed through the GraphConnection class. To initialize a new connection, you need to provide an access token, which can be obtained using Azure Authentication Library.

GraphConnection graphConnection = new GraphConnection(accessToken);

There are several operations available on GraphConnection for various operations including,

  • Create/Get/List/Update/Delete operations on entities like User/Group/Application/Permission, etc.
    • TenantDetail GetTenantDetails()
    • T Get<T>(string uniqueIdentifier)
    • IList<T> List<T>(string pageToken, FilterGenerator filter)
    • T Update<T>(GraphObject)
      Delete<T>(GraphObject)
  • Add/Remove/List link/navigation properties (Members, Manager, etc) on an entity (User/Group etc.)
    • PagedResults<GraphObject> GetLinkedObjects(GraphObject graphObject, LinkProperty linkProperty, string nextPageToken)
    • IList<GraphObject> GetAllDirectLinks(GraphObject graphObject, LinkProperty linkProperty)
    • AddLink(GraphObject sourceObject, GraphObject targetObject, LinkProperty linkProperty, bool isSingleValued)
    • DeleteLink(GraphObject sourceObject, GraphObject targetObject, LinkProperty linkProperty, bool isSingleValued)
  • Batch operations (up to 5 operations can be batched together)
    • ExecuteBatch(params Expresssion<Action>[])
  • Get/Set stream properties on any supported entity.
    • Stream GetStreamProperty(GraphObject graphObject, GraphProperty graphProperty, string acceptType)
    • SetStreamProperty(GraphObject graphObject,GraphProperty graphProperty, MemoryStream memoryStream, string contentType
  • Perform actions like AssignLicense/GetMemberGroups/CheckMemberGroups/IsMemberOf, etc.
    • IList<string> GetMemberGroups(User user, bool securityEnabledOnly)
    • IList<string> CheckMemberGroups(GraphObject graphObject, IList<string> groupIds)
    • User AssignLicense(User user, IList<AssignedLicense> addLicenses, IList<Guid> removeLicenses)
    • bool IsMemberOf(string groupId, string memberId)

Extending Graph Client Library in your application.

Most APIs has overloads to meet different requirements and GraphConnection can be extended to add custom behavior or override specific methods. The sources are available at <Temporarily Removed>, please fork and contribute. We welcome your pull requests.

Feedback Welcome.

The following are our priorities in relation to the next official releases of the library. We welcome any feedback.

  1. Support Linq expressions as query model.
  2. Support Async model.
  3. Support a “preview” version that targets the latest Graph API preview version (for example, support extensions for 1.21-preview version).
  4. Support connection pooling.
  5. Support iOS and Android platforms.

Samples.

The console application -  https://github.com/AzureADSamples/ConsoleApp-GraphAPI-DotNet and a web application - https://github.com/AzureADSamples/WebApp-GraphAPI-DotNet shows how to use this library.

In part 2 of this blog, we will talk in detail about each of the APIs with a complete API reference.

 

Thanks

Pavan Kompelli
Vijay Srirangam
Edward Wu

Azure Active Directory Team

Comments (23)

  1. Ilkka Nissinen says:

    My comment is not actually directly related to this Client Library, but great to see you utilizing more and more Graph REST api.

    I have a few feature requests.

    When do we have ability to do basic exchange tasks using graph api, like modify proxyAddresses attribute and create/modify exchange distribution lists?

    Another feature what I would like to see in Graph api is the ability do some Intune tasks, like assign application/policy to a device, wipe out a mobile device and read a device attributes.

  2. Pavan Kompelli - MSFT says:

    Thank you for the feedback Ilkka. Right now the library can only be used to interact with Azure Active Directory.

  3. Paul Judson says:

    I'm just curious why fields such as mailNickname and password are required in the User API when they aren't required in New-MsolUser?

  4. Pavan Kompelli - MSFT says:

    Paul, Graph library uses REST endpoint and follows the reference - msdn.microsoft.com/.../dn130117.aspx. Powershell uses a different endpoint which sets a default mailNickname and generates a default password as a part of the API.

  5. Kune Wewe says:

    Re: "To initialize a new connection, you need to provide an access token, which can be obtained using Azure Authentication Library."

    I am developing a web service using Web API and OWIN. My service needs to read from and write to AAD, so GraphClient is a natural fit. Given that I've secured my service such that it requires HTTP Bearer auth (via OWIN's IAppBuilder.UseWindowsAzureActiveDirectoryBearerAuthentication), how do I obtain the access token necessary to use a GraphConnection? Note that my service is registered in AAD as an "application".

  6. Kune Wewe says:

    I figured it out. I needed to create an ADAL ClientCredential using my service's key (aka client secret), and then call AuthenticationContext.AcquireToken with that credential and the Graph API endpoint.

  7. Pavan Kompelli - MSFT says:

    Hi Kune, Please take a look at the web app sample - github.com/.../WebApp-GraphAPI-DotNet which shows how to use OWIN with Graph Client Library.

  8. Jørgen Hellemann says:

    Hi!

    I'm struggling adding new users with Norwegian special chars in names and addresses (such as my own: Jørgen). The input file I'm reading the users from is UTF-8 encoded and the console output looks all good. I have also tried to do some encoding both in File.ReadAllLines method and UTF-8 encode all strings I'm adding to the User class. But still unable to add to Azure AD. Any clue?

  9. Pavan Kompelli - MSFT says:

    Hi Jørgen, Sorry for the late reply. It looks like an issue with the way the library is encoding non ASCII characters. We will fix the issue and update the nuget package.

  10. Jørgen Hellemann says:

    Great, thanks! I have also been looking into extending the Azure Active Directory Schema. Will this be possible using this .NET Client Library anytime in the feature?

  11. Steve says:

    This is a great addition.  Will I need to re-write code rather than updating references if moving from the 2013_04_05 helpers to this?

  12. Saji says:

    Great Improvement!!  I'm able to create a User but not a Device object. Error : "One or more property contain invalid values". Couldnt find any code samples online. Please help!

  13. Pavan Kompelli - MSFT says:

    Jørgen,

    We have updated the nuget package (1.0.3) with the fix. Please try and let us know if it fixes your issue. Since the schema extensions are in preview state, graph client library does not currently support this feature completely. However you can get/set extension values on an object by using GraphObject.NonSerializedProperties or the indexer of GraphObject (user["extension..."] = "value").

  14. Pavan Kompelli - MSFT says:

    Steve,

    Graph client library offers a different programming model. You might have to tune the existing code accordingly.

  15. Pavan Kompelli - MSFT says:

    Saji,

    I just tried with the following and was able to add a Device using the library -

               Device device = new Device();

               device.AccountEnabled = true;

               device.DisplayName = Guid.NewGuid().ToString("N");

               AlternativeSecurityId altSecId = new AlternativeSecurityId();

               altSecId.Key = Guid.NewGuid().ToByteArray();

               altSecId.Type = 2;

               altSecId.IdentityProvider = null;

               device.AlternativeSecurityIds.Add(altSecId);

               device.DeviceId = Guid.NewGuid();

               device.DeviceOSType = Guid.NewGuid().ToString("N");

               device.DeviceOSVersion = Guid.NewGuid().ToString("N");

               device = graphConnection.Add(device);

    Please see msdn.microsoft.com/.../dn151674.aspx to learn more about each property.

  16. Jørgen Hellemann says:

    Pavan,

    Version 1.0.3 works like a charm on Norwegian (non ASCII) chars. I will look into your suggestion on extending the schema. Thanks!

  17. bill noel says:

    This is awesome.  However, I have a need for Windows Phone 8.1 (C#/XAML) and more generally Windows Store apps.  This library doesn't work for that.  Any plans to make it available for those platforms?

    Thanks.

  18. Pavan Kompelli - MSFT says:

    Bill,

    We are working on a version that would help Windows store/phone apps. We will update the blog once the nuget package is available.

  19. mikedenner@getzclinical.com says:

    Hi there,

    Some issues I'd like to report:

    1. The GraphException is not marked as ISerializable therefore fails with an exception when serialization is attempted.
    2. The more serious issue is that the package is marked as being dependent on Json >=6.0.1, however the assembly itself references as Json 4.5. Any reason for this? We are currently in "reference hell" trying to use a common Json version.

    Please help!

    Cheers,

    Mike

  20. Mike Denner says:

    Hi there,

    Further to the above:

    1. The GraphException.Message when the exception is thrown is blank and should be mapped to the ErrorMessage property for consistent error handling.
    2. The Logger class is spewing output into my trace logs. Either implement a TraceSwitch so it can be turned off, or a flag so that the logging can be disabled. Tying it the generic TraceSwitch is very inflexible.

    When can we expect a new release? Is there a better place to log issues such as these?

    Cheers,

    Mike

  21. Adam Hill says:

    Can someone from the team verify that the library works with users that have a single quote (') in the DisplayName?

    We have a user with a Last Name of  "O'Hara" in AD, if we don't escape the name, using the FilterExpression in a GraphConnection.List<T>() causes an error, if we do URL escape it, we get back no match. This same user can access other O365 resources fine (Outlook and Sharepoint).

    We can see the escaped GET request and it is formed correctly. What is the expected behavior with .Encode()'ed strings? (FTR, the documentation on what characters are allowed in On-Prem AD vs Cloud AD using DirSync is confusing to say the least)

  22. Aparna Chinya says:

    Hello, Is this available for Windows store apps (Universal apps) now?

  23. Marulasiddappa SB- Swamy says:

    Hi Pavan,

    Is Azure Active Directory Graph Client Library 1.0" DLL  compatible with Framework 4.0?

Skip to main content