Condividi tramite

Azure Active Directory Graph Client Library 1.0

  • Articolo

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

  • Anonymous
    June 03, 2014
    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.
  • Anonymous
    June 03, 2014
    Thank you for the feedback Ilkka. Right now the library can only be used to interact with Azure Active Directory.
  • Anonymous
    June 03, 2014
    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?
  • Anonymous
    June 04, 2014
    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.
  • Anonymous
    June 05, 2014
    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".
  • Anonymous
    June 05, 2014
    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.
  • Anonymous
    June 05, 2014
    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.
  • Anonymous
    June 15, 2014
    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?
  • Anonymous
    June 19, 2014
    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.
  • Anonymous
    June 22, 2014
    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?
  • Anonymous
    June 25, 2014
    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?
  • Anonymous
    June 26, 2014
    The comment has been removed
  • Anonymous
    July 11, 2014
    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").
  • Anonymous
    July 11, 2014
    Steve,Graph client library offers a different programming model. You might have to tune the existing code accordingly.
  • Anonymous
    July 11, 2014
    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.
  • Anonymous
    July 13, 2014
    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!
  • Anonymous
    September 17, 2014
    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.
  • Anonymous
    October 06, 2014
    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.
  • Anonymous
    October 07, 2014
    The comment has been removed
  • Anonymous
    October 08, 2014
    The comment has been removed
  • Anonymous
    October 23, 2014
    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)
  • Anonymous
    June 02, 2015
    Hello, Is this available for Windows store apps (Universal apps) now?
  • Anonymous
    August 26, 2015
    Hi Pavan, Is Azure Active Directory Graph Client Library 1.0" DLL  compatible with Framework 4.0?