MICROSOFT GRAPH AND AZURE ACTIVE DIRECTORY GRAPH API

One question that comes to our mind while require accessing Azure Active Directory resources is whether we should make use of Microsoft Graph  or Azure AD Graph. More commonly, Microsoft recommends using Microsoft Graph instead of Azure AD Graph API to access directory-based features, as Azure AD Graph API may fit in for very few scenarios.

Azure AD Graph API

Two APIs, different functionality

Microsoft Graph supports most of the Azure AD Graph features, but not all. Also, Microsoft Graph supports some features which are not in Azure AD graph, e.g. $select projection queries.

Microsoft aims to close the gap between Microsoft Graph and Azure AD Graph features by making it comfortable for developers to use Microsoft Graph. Now onwards, users who are building new apps or integrating existing apps with cloud will be proposed to use Microsoft Graph.

Note: Apps already using Azure AD Graph won’t get affected and Azure AD Graph API will remain fully functional for those applications.

While Azure AD Graph client library is only available for .Net applications, Microsoft Graph client libraries support multiple platforms and languages, which gives you more choices to use directory data in your apps.

Microsoft Graph – An API for Microsoft 365

Microsoft Graph provides a programming model to connect Office 365, Windows 10, Azure Active Directory, and Enterprise Mobility and Security services. Microsoft Graph is used to build apps for users interacting with millions of data by accessing resources using a single endpoint: Microsoft Graph

It is a RESTful Web API that allows you to access cloud services. You can request Microsoft Graph API after registering an app with Azure AD and accessing authentication tokens for a user.

You can use REST APIs and client libraries exposed by Microsoft Graph to connect data on:

  • Office 365 services: SharePoint, Microsoft Teams, Planner, Outlook/Exchange, Excel, OneDrive and OneNote.
  • Windows 10 services
  • Azure Active Directory
  • Enterprise Mobility + Security services: Advanced Threat Analytics, Advanced Threat Protection, Identity Manager and Intune

Microsoft Graph uses relationships to connect resources under these services. For example, member of relationship can be used to connect a user to a group and using manager relationship, a user can be connected to another user.

You can get important insights about the data using Microsoft Graph. For example, you can get the most accessed files that are trending around a user.

Microsoft Graph

You can construct a request to read from or write to a resource from services.

1) Below are the components of Microsoft Graph API request:

> HTTP Method used for making request to Microsoft Graph

MethodDescription
GETGet data from the resource
POSTCreate a new resource
PATCHModify resource with the latest values
PUTReplace resource with a new one
DELETEDelete a resource
  • No request body is needed for GET and DELETE methods
  • The Request body is required for PATCH, POST and PUT methods. It is returned in JSON format containing additional information such as values for properties.

> Version: Microsoft Graph API version which your app is using

VersionDescription
v1.0Contains commonly available APIs. Most recommended for production apps
betaContains APIs in the preview stage. Recommended for development or test apps, not to be used for production apps.

> Resource: Microsoft Graph resource with which you are interacting inside the request URL.

  • Top-level resources include me, sites, users, groups and drives
  • Most of the top-level resources contain relationships used to access other resources such as me/messages and me/drive
  • You can also use methods to interact with resources such as me/sendEmail.

> Query-parameters (optional): A set of parameters to customize request or response like filter response matching a custom query. For example, below filter parameter returns messages for a user with specified email address only.
https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq ‘[email protected]

2) Below are the components returned in response to your request:

  • HTTP status code: Standard HTTP status code returned in terms of success or failure.
    Some of the commonly returned status codes in case of failure include
    Status code Status message Description
    400 Bad request Unable to process the request as it is incorrect/malformed
    401 Unauthorized Missing or invalid authentication information
    403 Forbidden Access denied because the user does not have required permission
    404 Not found Requested resource is not available
  • Response message: Data or result requested.
  • Next link: In the case of the response containing a lot of data, you can navigate to the next page by selecting Next. It happens while using server-side paging or due to the usage of $top query parameter to limit the number of results returned on a page.
    https://graph.microsoft.com/v1.0/users?$top=3

Microsoft Graph API Features

You can use Microsoft Graph to add value to your application and build friendly user context experiences.

  • Simplifies user onboarding by automating tasks. Activities carried out include – assign managers, assign roles to users, provide permissions to documents, assign product licenses, change users’ roles and much more.
  • Retrieves Excel workbook data and builds powerful workflows to integrate data collection with cloud services such as SharePoint.
  • Allows finding meeting times and provides profile information for one or more attendees.
  • Gets recommended meeting times by scanning your calendar containing attendees and their preferred timeslots.
  • Supports file format conversion to PDF. Office file types such as Word, Excel, and PowerPoint as well as other common formats such as CSV and RTF can be converted.
  • Manages employee profiles by keeping your company Azure directory up-to-date. It can also modify user profile information stored in SharePoint via API.
  • Sends you a notification by subscribing to changes in your calendar, when you spend too much time in meetings and suggests meetings which you can miss based on the relevancy of your attendees.
  • Helps you sync and sort out personal data on your phone.
  • Calls Security Alerts API to avoid threats and correlates alerts from data sources in a simplified way.

Some of the common Microsoft Graph API requests include

RequestEndpoint URL
Get my profilehttps://graph.microsoft.com/v1.0/me
Get my photohttps://graph.microsoft.com/v1.0/me/photo/$value
Get my fileshttps://graph.microsoft.com/v1.0/me/drive/root/children
Get my emailhttps://graph.microsoft.com/v1.0/me/messages
Get my calendar eventshttps://graph.microsoft.com/v1.0/me/events
Get my managerhttps://graph.microsoft.com/v1.0/me/manager

Azure Active Directory Graph API

The Azure Active Directory (Azure AD) Graph API is used to access Azure AD objects using REST API OData endpoints. You can use Azure AD Graph API in your applications to perform CRUD operations on Azure AD data and objects.
Some of the common operations supported by Azure AD Graph API include:

  • Create a new user in Azure AD
  • Get properties of a user such as a group/s user belongs to, their email address or location
  • Update properties of a user, such as location, password or phone number
  • Disable or delete the user account

Similarly, you can access other Azure objects such as groups and applications.

Before you call Azure AD Graph API on a directory, you must register your app with Azure AD. You must also consent your app to access Azure AD Graph API.

Features of Azure AD Graph API

  • REST API Endpoints: Azure AD Graph API comprises of REST API OData endpoints that are accessed using HTTP requests. Azure AD Graph API’s requests and responses support XML or JSON formats.
  • Authentication with Azure AD: Azure AD Graph API request appends a JSON Web Token (JWT) in its authentication header. You can acquire the token by requesting Azure AD’s token endpoint.
  • Role-Based Authorization (RBAC): Azure AD Graph API uses security groups to perform Role-Based Authorization. For example, you can call Check Group Membership Boolean operation in your application to check user’s access to the specific resource.
  • Differential Query: Differential query tracks changes in a directory between two durations without the need to fire independent queries to API, which returns modifications made between the previous differential request and active request.
  • Directory Extensions: You can use custom properties with Azure directory objects to access properties from the external data source such as Skype.
  • Secured by permission scopes: Using Azure AD Graph API, you can use permission scopes to enable secure access to directory data using OAuth 2.0. It supports two types of permissions:
    > Delegated permission: Users are given delegated access to data through authorization from the signed-in user.
    > Application permissions: Users are given role-based access control defined by the application without authorization from the signed-in user.

Your client apps can utilize both delegate and application permission scopes exposed by Azure AD Graph API.

Constructing Azure AD Graph API URL

To perform CRUD operations on Azure directory and resources through Graph API, you can make use of Open Data (OData) protocol-based URLs.
Below are the components used in the URL of Graph API
https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters]

  1. Service Root: Windows Graph
  2. Tenant identifier: It can be a verified domain name or a tenant object ID registered with Azure AD
  3. Resource path: It identifies Azure AD resources or entities, for example, users and groups, to be interacted with. You can also access a specific entity from within the top-level entity, for example, users/{objectId} or users/userPrincipalName
  4. Query parameters: The part of the Graph API URL after question mark (?) form the query parameters section. Note that the “api-version” query parameter is mandatory on all requests made via Graph API. Other query options supported by Azure AD Graph API include $filter, Stop, $orderby, $format and $expand. You can find more information regarding query parameters here.

Graph API versions

You must pass the version of operation inside query string parameter “api-version”. Without an api-version, your request will be rejected and you will receive an error “The specified api-version is invalid”.

Graph API versions
  • You use numerical value for api-version 1.5 or later api-version 1.6.
  • For using earlier versions, you used data string of the format YYYY-MM-DD i.e. api-version=2014-12-07
  • In the case of preview features, you will need to use “beta” i.e. api-version=beta

Graph API metadata

To retrieve metadata file simply add $metadata after the tenant identifier in the URL. For example, enter below URL I browser to return Azure AD Graph API metadata file for a tenant.

https://graph.windows.net/tenantname/$metadata?api-version=1.6

Note: Replace the yellow highlighted tenantname and useraccount words based on your tenant name and user account respectively.
The metadata file returns described entities and their object types, actions, and functions exposed by thepassed Graph API version.

Graph API metadata

Azure AD Graph API common queries

Some of the common queries performed with Azure AD Graph include accessing top-level resources and other specific entities below top-level resource. Ensure that a valid authentication header having valid bearer token will be required to access Azure AD Graph API across the tenant.

Querying top-level resources

Top-Level ResourceQuery ResultsURI
Top-level resourcesReturns list of URIs for top-level resources for Azure ADhttps://graph.windows.net/tenantname?api-version=1.6
Company informationRetrieves company/tenant informationhttps://graph.windows.net/tenantname/tenantDetails?api-version=1.6
Contacts informationRetrieves contact information for an organizationhttps://graph.windows.net/tenantname/contacts?api-version=1.6
UsersRetrieves user informationhttps://graph.windows.net/tenantname/users?api-version=1.6
GroupsRetrieves group datahttps://graph.windows.net/tenantname/groups?api-version=1.6
Directory RolesRetrieve AD tenant roleshttps://graph.windows.net/tenantname/directoryRoles?api-version=1.6
SubscribedSkusRetrieves all the subscriptions of the tenanthttps://graph.windows.net/tenantname/subscribedSkus?api-version=1.6
Directory metadata informationRetrieves tenant’s AD metadata file describing entities and their object types and data modelhttps://graph.windows.net/tenantname/$metadata?api-version=1.6

Other query operations

Some of the additional commonly used Graph API queries include:

Query operationURI
Fetch users and groupshttps://graph.windows.net/tenantname/users?api-version=1.6
https://graph.windows.net/tenantname/groups?api-version=1.6
Retrieve user using objectId or userPrincipalNamehttps://graph.windows.net/tenantname/users/f3d5fba2-d5b7-45f7-aedd-6b2efa5bf1cd?api-version=1.6 https://graph.windows.net/tenantname/users/useraccount?api-version=1.6
Retrieve or filter user where displayName equal to a specific valuehttps://graph.windows.net/tenantname/users?$filter=displayName eq ‘Tom Datson’&api-version=1.6
Retrieve or filter user where firstName equal to a specific valuehttps://graph.windows.net/tenantname/users?$filter=givenName eq ‘Tom’&api-version=1.6
Retrieve or filter user based on givenName and surnamehttps://graph.windows.net/tenantname/users?$filter=givenName eq ‘Tom’ and surname eq ‘Datson’&api-version=1.6
Fetch group by objectIdhttps://graph.windows.net/tenantname/groups/164c55e3-2b44-4429-aac1-0f538e75ac05?api-version=1.6
Retrieve manager of a userhttps://graph.windows.net/tenantname/users/useraccount/manager?api-version=1.6
Retrieve direct reports list for a userhttps://graph.windows.net/tenantname/users/ff9661e4-cdae-41da-847a-b0fdb753fea0/directReports?api-version=1.6
Get links direct reports lists for a userhttps://graph.windows.net/tenantname/users/ff9661e4-cdae-41da-847a-b0fdb753fea0/$links/directReports?api-version=1.6
Retrieve group membership listhttps://graph.windows.net/tenantname/groups/bc439c50-abf6-4946-9307-b0061b73ab5b/members?api-version=1.6
Retrieve membership of userhttps://graph.windows.net/tenantname/users/b2631075-c011-4175-8584-0952e898fee2/memberOf?api-version=1.6
Retrieve all the groups that a user is member ofhttps://graph.windows.net/tenantname/users/b2631075-c011-4175-8584-0952e898fee2/$links/memberOf?api-version=1.6
Retrieve all the groups with displayName >= ‘ab’ and <= ‘cd’https://graph.windows.net/tenantname/groups?$filter=displayName ge ‘ab’ and displayName le ‘cd’&api-version=1.6
Retrieve all local account users in Azure ADhttps://graph.windows.net/tenantname/users?filter=creationType eq ‘LocalAccount’&api-version=1.6
Retrieve local account user with a specified sign-in name from Azure ADhttps://graph.windows.net/tenantname/users?$filter=signInNames/any(x:x/value eq ‘useraccount’)&api-version=1.6

Azure AD Graph Explorer

To query Azure directory data using Azure Graph API in your application, you can use Azure AD Graph explorer. Navigate to Azure Graph explorer to load Azure AD Graph Explorer. Sign-in with your Azure AD account to access Azure AD Graph Explorer.
Note: You or your tenant admin will need to consent during sign-in. In case of an Office 365 subscription, you are automatically consenting to Azure AD tenant.Azure AD Graph Explorer

Similarly, to get the list of all groups in your directory, type below query in the request text box and click on Go button
https://graph.windows.net/tenantname/groups?api-version=1.6
Some of the features of Azure AD Graph Explorer include:

  • Request history
  • ‘me’ and ‘myorganization’ addressing aliases are supported.
  • All the CRUD operations POST, GET, PATCH and DELETE are supported against your tenant.
  • Troubleshooting of issues while running queries using response headers.
  • Response to query in JSON format with the expand and collapse functionalities.

Although, there is no support to display a thumbnail picture in Azure AD Graph Explorer. In order to fetch and upload user’s profile picture, you can use Fiddler Web Debugger.
You can install Fiddler using link.

Difference between Azure AD Graph API and Microsoft Graph API

Microsoft Graph API supports most, but not all features supported by Azure AD Graph API.

FeatureAzure AD Graph capabilityMicrosoft Graph capability
Endpointhttps://graph.windows.nethttps://graph.microsoft.com
Delta SyncDifferential query/delta sync available for users and groups
  • General Availability with Delta query
  • Organizational contacts delta sync is not supported.
  • Sync from now is still not supported
Organizational Contact Resource TypeSupportedIn preview stage
Applications Management

Applications management such as

  • Application and service principal entity types
  • Assigning applications to users and groups
  • Assigning OAuth permissions to applications
Available in preview
Partner Admin supportYesGeneral Availability
Domain resource typeYesGeneral Availability
Contracts resource typeYesGeneral Availability
Directory schema extension definition registrationSupported

General availability.

Supports extending resources with application data.

Does not support application or service principal resource type

BatchingYesAvailable in preview
PropertiesProperties are missing on user

 

resources such as sipProxyAddress,

otherEmails, licenseDetails

General availability.
OtherEmails still not supported, but planned for future
Get ObjectGetObjectsByObjectsIds methodGeneral availability. getByIds method
Check MembershipIsMemberOf methodUnplanned. Need to use checkMemberGroups method
Users ManagementUsers management in B2C tenantComing soon in preview

Conclusion

Microsoft is recommending to use Microsoft Graph instead of Azure Active Directory Graph API to access Azure AD resources. Microsoft development is mainly focused on Microsoft Graph and there is no further extension planned for Azure AD Graph API. In our next blog, we will see how we can consume Microsoft Graph APIs secured with Azure AD in SharePoint Framework.

 

profile-image
Vishal Shah

Vishal Shah has an extensive understanding of multiple application development frameworks and holds an upper hand with newer trends in order to strive and thrive in the dynamic market. He has nurtured his managerial growth in both technical and business aspects and gives his expertise through his blog posts.

Related Service

Know more about SharePoint Development services

Learn more

Want to Hire Skilled Developers?


    Comments

    • Leave a message...