Working with Azure Active Directory resources in Microsoft Graph
APIs under the
/beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.
With Microsoft Graph, you can access Azure Active Directory (Azure AD) resources to enable scenarios like managing administrator (directory) roles, inviting external users to an organization, and, if you are a Cloud Solution Provider (CSP), managing your customer's data. Microsoft Graph also provides methods apps can use, for example, to discover information about users' transitive group and role memberships.
To call the Microsoft Graph APIs on Azure AD resources, your app will need the appropriate permissions. Many of the APIs exposed on Azure AD resources require one of the Directory permissions. Directory permissions are highly privileged and always require administrator consent.
If your app is acting on behalf of a user (delegated permissions), that user will likely need to be a member of an appropriate administrator role for your app to successfully call many of the Azure AD APIs.
For more information about permissions, including delegated and application permissions, see Permissions.
Common use cases
The following table lists some common use cases for Azure AD resources.
|Use cases||REST resources||See also|
|Directory object and methods|
|Manage directory (administrator) roles, administrative units, directory settings, and policy|
|Activate directory roles in an Azure AD tenant and manage user memberships in directory roles. Directory roles are also known as administrator roles.||directoryRole
|Assigning administrator roles in Azure Active Directory|
|Manage administrative units. Directory roles delegate tenant-wide authority to their members. An administrator can create and manage administrative units to delegate more granularly scoped administrative authority to users.||administrativeUnit||Administrative units management in Azure AD|
|Apply predefined directory settings across a tenant or to individual resource instances. Currently, only settings for Office 365 groups are supported. Directory settings control behaviors like blocked word lists for group display names, whether guest users are allowed to be group owners, and much more.||directorySetting
|Azure Active Directory cmdlets for configuring group settings|
|Apply Azure AD policies to applications, service principals, groups, or the entire organization. Currently, policies for token lifetime and home realm discovery are supported.||policy||N/A|
|Secure privileged access to Azure AD|
|Manage and monitor time-bound privileged access to directory and Azure resources for administrators and IT professionals with Privileged Identity Management (PIM).||Privileged Identity Management API||What is Azure AD Privileged Identity Management?|
|Monitor identity risk events like users signing in from malware-infected devices or from unfamiliar locations.||Identity Protection Service API||Azure Active Directory Identity Protection
Azure Active Directory risk events
|Manage devices registered in the organization. Devices are registered to users and include items like laptops, desktops, tablets, and mobile phones. Devices are typically created in the cloud using the Device Registration Service or by Microsoft Intune. They're used by conditional access policies for multifactor authentication.||device||Getting started with Azure Active Directory device registration
What is InTune?
Enroll devices for management in InTune
|Manage app configuration in a developer tenant.||application||Application and service principal objects in Azure Active Directory|
|Manage apps installed in a tenant.||servicePrinicpal||Application and service principal objects in Azure Active Directory|
|Manage permissions consented by users and administrators on apps installed in a tenant.||oAuth2PermissionGrant||N/A|
|Manage user, group, and service principal role memberships on apps installed in a tenant.||appRoleAssignment||N/A|
|Partner tenant management|
|Get information about partnerships with customer tenants.
Note: This applies to partner tenants only. Partner tenants are Azure AD tenants that belong to Microsoft partners who are either part of the Microsoft Cloud Solution Provider, Office 365 Syndication, or Microsoft Advisor partner programs.
|contract||Call Microsoft Graph from a Cloud Solution Provider application|
|Manage domains associated with a tenant. Domain operations enable registrars to automate domain association for services such as Office 365.||domain||Add a custom domain name to Azure Active Directory|
|Get information about an organization, such as its business address, technical and notification contacts, the service plans that it's subscribed to, and the domains associated with it.||organization||N/A|
|Get information about the service SKUs that a company is subscribed to.||subscribedSku||N/A|
|Invite external (guest) users to an organization.||invitation||What is Azure AD B2B collaboration?|
|Ensure group memberships and application access rights are correct with access reviews||access reviews API||Azure AD access reviews|
Directory resources and APIs can open up new ways for you to engage with users and manage their experiences with Microsoft Graph. To learn more:
- Drill down on the methods and properties of the resources most helpful to your scenario.
- Try the API in the Graph Explorer.
Need more ideas? See how some of our partners are using Microsoft Graph.