Introduction
This post is to help define how one can find out which permissions are needed for a specific Graph API call.
Assuming you want to have granular control over each AAD Application Registration, having the exact permissions required to do exactly what you need helps to secure your environment from users abusing permissions that you may have granted in excess.
Whenever someone wants to utilize the Microsoft or AAD Graph API, they have to grant the correct permissions for the AAD Application Registrations properly in order to be able to utilize the call.
Also for more information between the two Graph APIs please look here : https://blogs.msdn.microsoft.com/aadgraphteam/2016/07/08/microsoft-graph-or-azure-ad-graph/
Note: that just because you have been given the ability to make a call, doesn’t mean that the call will be authorized and go through properly. I.e. for o365 calendar issues, if you are logged in as user1 and retrieved a delegated access token and try to access the calendar of user2 and you don’t have access to user2s calendar as user1, you won’t be able to access the calendar. Just because you have granted permissions to access calendars, doesn’t mean that your user can access a calendar that he/she doesn’t have access to in the first place.
Finding Which Permissions We Need for a Microsoft Graph Call
Finding the permissions for the Microsoft Graph API is easier because there is a direct mapping for each Microsoft Graph API call described on each Microsoft Graph API call.
To determine which permissions we are going to want, you will have to check the permissions at the top of the reference guide for an operation for the Microsoft Graph API.
For example :
I would like to be able to list some users from Azure using the Microsoft Graph API using a client credentials grant type. In order to do this we can check the reference guide for the Microsoft Graph API here :https://developer.microsoft.com/en-us/graph/docs/concepts/v1-overview
On the side bar we can see the reference guide for the Microsoft Graph V1 endpoint, since we would like to list users, I look in the users sections and see if there is a list users.
It seems that there is a list users call, so I click on that. At the top of the list users API documentation, we can see the permissions that are needed :
Depending on how you plan on getting your access token you will either pick the application permission or the delegated permission, the differences between application and delegated are described here : https://docs.microsoft.com/en-us/azure/active-directory/application-dev-delegated-and-app-perms.
With client credentials we will need to utilize the application permissions, the delegated permissions can be used for the code grant type, or a flow that uses a user in addition to login.
For more information on permissions you can go to the permissions page for Graph API here : https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference
In this blog post we will utilize the list users functionality, and we will want the permission to have user.read.all (the least privileged) so that we can list users from the AAD Application registration.
Now, in the AAD Application registration, it defaults to applications listed under “my apps” which means applications you are considered owner of. This is not going to be related to getting an access token to the Microsoft Graph API, so we are going to disregard not being the owner of the application. Please press the box that says view all applications to get access to your app shown in the picture below.
You can also change the box that says my apps to all apps to show all the applications in your tenant.
From here we will click on the application that you created, we will want to go to the required permissions blade described in the picture below :
After pressing the “Add” button, we will want to add the permission for the Microsoft Graph shown below.
Notice how the permissions have descriptions, and not the exact claim. Since we want to get the user.read.all permission we will want to determine which one of these permissions will give the claim user.read.all. We can find this in the permissions reference, for users we can find it here : https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference#user-permissions
Notice this is under the delegated permissions, if we scroll down a bit more we will find the application permissions section.
We will want to find the corresponding display string in our permissions list “read all users’ full profiles” and check the button and press the done button.
After adding the user.read.all permission for the Graph API we will need to press the grant permissions button because this permission requires admin consent. You can see if it requires admin consent by seeing if it says yes under the admin consent column.
Below shows where the grant permission button is next to the Add button in the portal. This will need a tenant global admin to grant admin consent for it.
We have now gone through the process to make a Microsoft Graph Call and should be able to connect to the AAD Application Registration now and make the call to the list users functionality. Remember that whether you pick application permission or delegated permission will determine whether or not you get an access token with the correct scopes depending on your grant type flow.
Finding Which Permissions We Need for an AAD Graph API Call
Finding the exact permission you need for the AAD Graph API calls is a bit tricky. This is because there isn’t a direct mapping between permissions and AAD Graph API calls. By this I mean you won’t be able to see a call and be able to read exactly which permission it needs in order to access the call.
You will have to look through the permissions/scopes for the AAD Graph API and determine what the call you would like to use is trying to do and draw comparisons to the permissions described in the permissions page : https://msdn.microsoft.com/en-us/library/azure/ad/graph/howto/azure-ad-graph-api-permission-scopes
For example, let’s say we would like to get a user’s manager described as this AAD Graph API Call :
We will have to read the call, and see what exactly we are doing first of all. To get a manager object, as described in “Operations on Navigation Properties”:
Relationships between a user and other objects in the directory such as the user’s manager, direct group memberships, and direct reports are exposed through navigation properties. When you use the me alias, you can read and, in some cases, modify these relationships by targeting these navigation properties in your requests.
So we are trying to access the “Navigation Properties” of a user object. The manager endpoint retrieves the sign-in user’s manager object from the manager navigation property. This means that we are going to want to get the permission that allows us to read navigation properties of users. Now going back to the permission scopes page, we can look and try to determine which permissions we will need in order to read navigation properties. Luckily this scenario is listed under “Permission Scope Scenarios”
But imagining that it doesn’t fit under the permission scope scenarios, you can look at the permission scope details.
The permissions scope details defines all the permissions for windows azure active directory. Notice how user.read’s description says it cannot read navigation properties. Since the manager object is a navigation property, we are going to have to look at the user.read.all permission which is a superset of permissions of user.readbasic.all. The extra permissions it user.read.all has however as said in the description is that it is allowed to read navigation properties which is the manager object’s property.
Thus after giving an AAD Application registration the User.Read.All command we will be able to utilize the getmymanagerobject AAD Graph API call in order to get the Manager Object.
Essentially we will be going through the scenarios and then the permission scope details to determine the permissions we will need in order to call the AAD Graph API.
Conclusion
We have now gone through an example process of finding the permissions for both the Microsoft Graph API and the Azure Active Directory Graph API. There are some minute differences between the two Graph APIs, and require a different process to determine which permissions should be allowed in order to make a graph api call.
If you experience anymore issues please file a support ticket and one of our support engineers will reach out to help you in regards to this issue.