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.
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.
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
| Method | Description |
|---|---|
| GET | Get data from the resource |
| POST | Create a new resource |
| PATCH | Modify resource with the latest values |
| PUT | Replace resource with a new one |
| DELETE | Delete 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
| Version | Description |
|---|---|
| v1.0 | Contains commonly available APIs. Most recommended for production apps |
| beta | Contains 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
| Request | Endpoint URL |
|---|---|
| Get my profile | https://graph.microsoft.com/v1.0/me |
| Get my photo | https://graph.microsoft.com/v1.0/me/photo/$value |
| Get my files | https://graph.microsoft.com/v1.0/me/drive/root/children |
| Get my email | https://graph.microsoft.com/v1.0/me/messages |
| Get my calendar events | https://graph.microsoft.com/v1.0/me/events |
| Get my manager | https://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]
- Service Root: Windows Graph
- Tenant identifier: It can be a verified domain name or a tenant object ID registered with Azure AD
- 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
- 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”.
- 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.
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.
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 Resource | Query Results | URI |
|---|---|---|
| Top-level resources | Returns list of URIs for top-level resources for Azure AD | https://graph.windows.net/tenantname?api-version=1.6 |
| Company information | Retrieves company/tenant information | https://graph.windows.net/tenantname/tenantDetails?api-version=1.6 |
| Contacts information | Retrieves contact information for an organization | https://graph.windows.net/tenantname/contacts?api-version=1.6 |
| Users | Retrieves user information | https://graph.windows.net/tenantname/users?api-version=1.6 |
| Groups | Retrieves group data | https://graph.windows.net/tenantname/groups?api-version=1.6 |
| Directory Roles | Retrieve AD tenant roles | https://graph.windows.net/tenantname/directoryRoles?api-version=1.6 |
| SubscribedSkus | Retrieves all the subscriptions of the tenant | https://graph.windows.net/tenantname/subscribedSkus?api-version=1.6 |
| Directory metadata information | Retrieves tenant’s AD metadata file describing entities and their object types and data model | https://graph.windows.net/tenantname/$metadata?api-version=1.6 |
Other query operations
Some of the additional commonly used Graph API queries include:
| Query operation | URI |
|---|---|
| Fetch users and groups | https://graph.windows.net/tenantname/users?api-version=1.6 https://graph.windows.net/tenantname/groups?api-version=1.6 |
| Retrieve user using objectId or userPrincipalName | https://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 value | https://graph.windows.net/tenantname/users?$filter=displayName eq ‘Tom Datson’&api-version=1.6 |
| Retrieve or filter user where firstName equal to a specific value | https://graph.windows.net/tenantname/users?$filter=givenName eq ‘Tom’&api-version=1.6 |
| Retrieve or filter user based on givenName and surname | https://graph.windows.net/tenantname/users?$filter=givenName eq ‘Tom’ and surname eq ‘Datson’&api-version=1.6 |
| Fetch group by objectId | https://graph.windows.net/tenantname/groups/164c55e3-2b44-4429-aac1-0f538e75ac05?api-version=1.6 |
| Retrieve manager of a user | https://graph.windows.net/tenantname/users/useraccount/manager?api-version=1.6 |
| Retrieve direct reports list for a user | https://graph.windows.net/tenantname/users/ff9661e4-cdae-41da-847a-b0fdb753fea0/directReports?api-version=1.6 |
| Get links direct reports lists for a user | https://graph.windows.net/tenantname/users/ff9661e4-cdae-41da-847a-b0fdb753fea0/$links/directReports?api-version=1.6 |
| Retrieve group membership list | https://graph.windows.net/tenantname/groups/bc439c50-abf6-4946-9307-b0061b73ab5b/members?api-version=1.6 |
| Retrieve membership of user | https://graph.windows.net/tenantname/users/b2631075-c011-4175-8584-0952e898fee2/memberOf?api-version=1.6 |
| Retrieve all the groups that a user is member of | https://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 AD | https://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 AD | https://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.
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.
| Feature | Azure AD Graph capability | Microsoft Graph capability |
|---|---|---|
| Endpoint | https://graph.windows.net | https://graph.microsoft.com |
| Delta Sync | Differential query/delta sync available for users and groups |
|
| Organizational Contact Resource Type | Supported | In preview stage |
| Applications Management |
Applications management such as
| Available in preview |
| Partner Admin support | Yes | General Availability |
| Domain resource type | Yes | General Availability |
| Contracts resource type | Yes | General Availability |
| Directory schema extension definition registration | Supported |
General availability. Supports extending resources with application data. Does not support application or service principal resource type |
| Batching | Yes | Available in preview |
| Properties | Properties are missing on user
resources such as sipProxyAddress, otherEmails, licenseDetails | General availability. OtherEmails still not supported, but planned for future |
| Get Object | GetObjectsByObjectsIds method | General availability. getByIds method |
| Check Membership | IsMemberOf method | Unplanned. Need to use checkMemberGroups method |
| Users Management | Users management in B2C tenant | Coming 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.
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.
Want to Hire Skilled Developers?
Comments
Leave a message...