Configure Azure AD Graph permissions for an app registration
Azure Active Directory (Azure AD) Graph is deprecated and is in its retirement path. We recommend that you follow the App migration planning checklist to help you migrate your apps to Microsoft Graph.
Your app might still temporarily require Azure AD Graph permissions to access resources. You can follow one of three methods described in this article to configure Azure AD Graph permissions for your app registration:
- Use the Microsoft Entra admin center to find the APIs your organization uses
- Update the application manifest on the Microsoft Entra admin center
- Use the Microsoft Graph applications API
Caution
Any app using Azure AD Graph will still stop functioning after the API is retired. For more information, see Migrate Azure AD Graph apps to Microsoft Graph.
Prerequisites
The steps in this article require two sets of privileges:
- Privileges to add permissions to an app registration
- Privileges to grant those permissions to the app registration
A user with at least the Privileged Role Administrator role can do both, while a user with the Application Administrator or Cloud Application Administrator role can only add the permissions. To help you enforce separation of duties and least privilege access, separate the tasks of adding permissions and granting permissions to different users. For more information about the actions supported by these roles, see Microsoft Entra built-in roles.
In addition, you need the following resources and privileges:
- Sign in to an API client such as Graph Explorer to run the HTTP requests.
- The app used to make these changes must be granted the
Application.ReadWrite.All
permission.
Use the Microsoft Graph applications API
The Microsoft Graph application object includes a requiredResourceAccess property that is a collection of objects with information about the resource API and permissions. Use this property to configure Azure AD Graph permissions as described in the following steps.
Step 1: Identify the permission IDs for the Azure AD Graph permissions your app requires
Identify the Azure AD Graph permissions your app requires, their permission IDs, and whether they're app roles (application permissions) or oauth2PermissionScopes (delegated permissions). For more information, see Azure AD Graph permissions reference.
Azure AD Graph is identified as a servicePrincipal object with 00000002-0000-0000-c000-000000000000
as its globally unique appId and Windows Azure Active Directory
as its displayName and appDisplayName. Run the following request to retrieve the service principal object for Azure AD Graph in your tenant.
Request
GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000002-0000-0000-c000-000000000000'
Response
In the response object, details for Azure AD Graph application permissions are listed in the appRoles object while details for delegated permissions are listed in the oauth2PermissionScopes object.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals",
"value": [
{
"id": "1804a6f8-e623-4520-8f40-ba1b0c11c42d",
"accountEnabled": true,
"appDisplayName": "Windows Azure Active Directory",
"appDescription": null,
"appId": "00000002-0000-0000-c000-000000000000",
"appOwnerOrganizationId": "f8cdef31-a31e-4b4a-93e4-5f571e91255a",
"appRoleAssignmentRequired": false,
"displayName": "Windows Azure Active Directory",
"servicePrincipalNames": [
"https://graph.windows.net",
"00000002-0000-0000-c000-000000000000/graph.microsoftazure.us",
"00000002-0000-0000-c000-000000000000/graph.windows.net",
"00000002-0000-0000-c000-000000000000/directory.windows.net",
"00000002-0000-0000-c000-000000000000",
"https://graph.windows.net/",
"https://graph.microsoftazure.us"
],
"servicePrincipalType": "Application",
"signInAudience": "AzureADMultipleOrgs",
"appRoles": [
{
"allowedMemberTypes": [
"Application"
],
"description": "Allows the app to read applications and service principals without a signed-in user",
"displayName": "Read all applications",
"id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
"isEnabled": true,
"origin": "Application",
"value": "Application.Read.All"
}
],
"oauth2PermissionScopes": [
{
"adminConsentDescription": "Allows users to sign in to the app, and allows the app to read the profile of signed-in users. It also allow the app to read basic company information of signed-in users.",
"adminConsentDisplayName": "Sign in and read user profile",
"id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
"isEnabled": true,
"type": "User",
"userConsentDescription": "Allows you to sign in to the app with your work account and let the app read your profile. It also allows the app to read basic company information.",
"userConsentDisplayName": "Sign you in and read your profile",
"value": "User.Read"
}
]
}
]
}
From the preceding truncated output, 311a71cc-e848-46a1-bdf8-97ff7156d8e6
is the permission ID for the User.Read delegated permission while 3afa6a7d-9b1a-42eb-948e-1650a849e176
is the permission ID for the Application.Read.All application permission in Azure AD Graph.
Step 2: Add Azure AD Graph permissions to your app
The following example calls the Update application API to add the Azure AD Graph User.Read and Application.Read.All delegated and application permissions to an app registration identified by object ID 581088ba-83c5-4975-b8af-11d2d7a76e98
.
Important
To update the requiredResourceAccess property, you must pass in both existing and new permissions. Passing in only new permissions overwrites and removes the existing permissions.
Request
PATCH https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98
Content-Type: application/json
{
"requiredResourceAccess": [
{
"resourceAppId": "00000002-0000-0000-c000-000000000000",
"resourceAccess": [
{
"id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
"type": "Scope"
},
{
"id": "3afa6a7d-9b1a-42eb-948e-1650a849e176",
"type": "Role"
}
]
}
]
}
Response
HTTP/1.1 204 No Content
Step 3: Verify the Azure AD Graph permissions were added to your app
Verify that your app registration has the Azure AD Graph API permissions you added in Step 2 by:
Calling the Microsoft Graph GET /application/{id} endpoint and reading the requiredResourceAccess property as follows:
GET https://graph.microsoft.com/v1.0/applications/581088ba-83c5-4975-b8af-11d2d7a76e98?$select=id,requiredResourceAccess
Checking the App registrations page in the Microsoft Entra admin center.
Step 4: Grant admin consent
Though you added Azure AD Graph permissions, you haven't granted these permissions to the app. Many permissions require admin consent before they can be used to access organizational data. Sign in to the Microsoft Entra admin center as a privileged role administrator and grant admin consent for the permissions to the app registration.
Grant API permissions without using the consent prompt
When using Microsoft Graph and any related SDKs, you can grant permissions to an app registration without the need to use the Microsoft Entra admin center and selecting the Grant admin consent for [Company] button on the API permissions page. For more information, see Grant or revoke API permissions programmatically.
Use the Microsoft Entra admin center to find the APIs your organization uses
Sign in to the Microsoft Entra admin center.
Expand Identity > Applications > select App registrations.
In the App registrations window, under the All applications tab, select the app that you want to add Azure AD Graph permissions to.
From the left pane of the window, under the Manage menu group, select API permissions. In the Configured permissions window, select Add a permission.
In the Request API permissions window, switch to the APIs my organization uses tab and search for
Windows Azure Active Directory
or00000002-0000-0000-c000-000000000000
. Select from the filtered result set to reveal the Azure Active Directory Graph permissions window.Select the Delegated permissions or Application permissions tab to choose from the list of delegated and application permissions respectively. Select Add permissions to add the permission to your app registration.
After adding the permissions you need, back in the Configured permissions window, select Grant admin consent to grant the Azure AD Graph permissions to your app registration.
Update the application manifest on the Microsoft Entra admin center
Sign in to the Microsoft Entra admin center.
Expand the Identity menu > Applications > select App registrations.
In the App registrations window, under the All applications tab, select the app that you want to add Azure AD Graph permissions to.
In the left pane of the window, under the Manage menu group, select Manifest to open up an editor that allows you to directly edit the attributes of the app registration object.
Carefully edit the requiredResourceAccess property in the app's manifest to add the following details:
Tip
A. You can edit the app manifest on the Microsoft Entra admin center or select Download to edit the manifest locally, and then use Upload to reapply it to your application.
B. To learn more about how to configure the requiredResourceAccess property, see requiredResourceAccess resource type.
C. Refer to the Azure AD Graph permissions reference for details of Azure AD Graph permission names, IDs, and types.
5.1. If the app isn't assigned any Azure AD Graph permissions, add the resourceAppId property and assign the value
00000002-0000-0000-c000-000000000000
representing Azure AD Graph.5.2. Add the resourceAccess property and configure the permissions.
The following JSON snippet shows a requiredResourceAccess property with Azure AD Graph as the resource, and assigned the User.Read and Application.Read.All oauth2PermissionScope (delegated permission) and appRole (application permission) respectively.
"requiredResourceAccess": [ { "resourceAppId": "00000002-0000-0000-c000-000000000000", "resourceAccess": [ { "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6", "type": "Scope" }, { "id": "3afa6a7d-9b1a-42eb-948e-1650a849e176", "type": "Role" } ] } ],
Save your changes.
Back under the Manage menu group, select API permissions and in the Configured permissions for your app registration, select Grant admin consent to grant the Azure AD Graph permissions to your app registration.