Tips for Working with the Azure Active Directory Graph API
Recently I have had the need, and interest, to poke around the Azure AD Graph API. This is a REST API that allows you to query and update information in an Azure Active Directory.
I wanted to share a few things that caused me a bit extra time to figure out in hopes that it will make your development using the Graph API a bit smoother.
This is base structure for a request to the API. You will see this in various places of the documentation.
https://graph.windows.net/{tenant_id}/{resource_path}?api-version={api_version}[odata_query_parameters]
Tenant ID
Just starting out with Azure AD and the terminology, I wasn’t immediately sure what the Tenant Id was and where to find it. After a bit of looking around, there are two items that can be used as the Tenant Id.
One option is the actual Tenant Id which can be found in a couple places. Logging into the Classic Azure Portal, going to the Active Directory section and selecting the Directory you want to work with, in the URL you will see that there is a segment with /Directory/ followed by a string of random letters and numbers – this is the Tenant Id. Another way to view the Tenant Id is, in the Directory you want to work with select the “Applications” tab. At the bottom of the screen is an icon with the description “View Endpoints”. This link brings up a modal window with a list of Endpoints for various integrations. Third from the bottom (at the time of writing this post) you will see one for “Microsoft Azure AD Graph API Endpoint”. This URL includes the Tenant Id.
The other option is to use the Tenant Name. The Tenant Name is the full “*.onmicrosoft.com” domain name. If we created a directory with the name of “mercurytest” then the Tenant Name would be mercurytest.onmicrosoft.com
Now that you know what the Tenant Id is referring to, I can tell you that there are actually two more tokens that can go in this spot (surprise!). They are the aliases “myorganization” and “me”. The alias “myorganization” can access any items in the authenticated user’s directory that they have access to and using the alias “me” allows access to information about the logged in user.
Application Roles
Getting the application set up to use roles with AD was a bit tricky in itself but that process is a separate topic and would be another full post. At the bottom of this post are some resources to help get you started, though.
In our application we needed the ability to add, edit and remove users and their roles. Adding, editing and deleting a user was pretty straight forward following the API documentation.
When it came to editing user roles, I found there was not very much documentation and it was difficult to understand. The main functions I was looking for were:
- getting all users and their roles
- getting a list of available roles
- getting roles for a single user
- adding a role to a user
- removing a role from a user
I found this post (http://blogs.msdn.com/b/aadgraphteam/archive/2014/12/12/announcing-the-new-version-of-graph-api-api-version-1-5.aspx) which listed the URLs for many of the functions I wanted to use.
View User Application Role Assignments
Getting application roles for a user was pretty straight forward. Replace the {username} token with the full username (user@xxx.onmicrosoft.com).
https://graph.windows.net/{tenant-id}/users/{username}/appRoleAssignments?api-version={api-version}
Assigning Application Roles
This is where things started getting tricky. The URL is the same as the GET but using a POST. This API documentation for the App Role Assignments got me on the right track for what each of the properties in the body of the request are.
ID: This is the Id for the Role you are assigning. These Ids can be found in the Application’s Manifest.
Principal ID: This is the Id of the User you are assigning the role to.
Principal Type: If you are assigning this role to a User then this is set to the string “User”. You can also assign roles to Groups.
Resource ID: Resource Id? Looking at the API documentation for this property it says this is “The unique identifier… for the target resource (service principal)…”. While I understand what it means now, at the time I had no idea what a Service Principal was.
Looking at some of the other URLs listed in the referenced post, this Service Principal Id is an important part of these calls. Let’s switch gears for a moment to focus on the Service Principal Id.
Service Principal
The GUIDs I started testing out were various ones I found in the Application Manifest. There is an App Id and an Object Id, however, the Object Type is listed as “Application”.
After various searches and trying out various calls to the API, the URL that I landed on gave me a list of Service Principals.
https://graph.windows.net/{tenant-id}/servicePrincipals?api-version={api-version}
When setting up Active Directory you can add applications that use this directory for authentication. In our case for a new application we are developing we set up two – one for the localhost which will be used when debugging the application in Visual Studio and another for the staging environment.
In the data that came back, each of these application instances are listed with the Object Type of “Service Principal”. The roles for each instance were also listed. This was the missing Id I needed for my API calls.
Application Roles – Part 2
With the Service Principal Id we can go back and finish up these API calls. Use the Object Id of the application instance you are using as the Resource Id.
Assigning Application Roles – Finishing Up
This request is now complete with the Resource Id.
Resource ID: Service Principal Id found in the last section
Getting a List of Application Roles
https://graph.windows.net/{tenant-id}/servicePrincipals/{resource-id}/appRoles?api-version={api-version}
Get all Users and their role assignments
https://graph.windows.net/{tenant-id}/servicePrincipals/{resource-id}/appRoleAssignedTo?api-version={api-version}
This call is a bit different that what you might originally expect. The relationship between a User and an AppRole is many-to-many so the Object Type you see here is an AppRoleAssignment. If a User is assigned to multiple roles it would appear multiple times in this list with a different AppRoleAssignment Object Id.
Removing Role Assignment
https://graph.windows.net/{tenant-id}/servicePrincipals/{resource-id}/appRoleAssignedTo?api-version={api-version}
Removing a role from a User is actually removing a Role Assignment. This is the Object Id found on the GET for a specific user’s roles.
Additional Resources
Sometimes, especially for newer technologies, you just have to search and try out different things until you find the right answers. I hope this post will help get you going in the right direction.
Here are a handful of resources that I used when working through Azure AD and the Graph API:
- General Graph API Information: https://msdn.microsoft.com/en-us/library/azure/hh974476.aspx
- Active Directory Quickstart: https://azure.microsoft.com/en-us/documentation/articles/active-directory-graph-api-quickstart/
- Graph API Reference: https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/api-catalog
- OData Query Options and Common queries: https://msdn.microsoft.com/Library/Azure/Ad/Graph/howto/azure-ad-graph-api-supported-queries-filters-and-paging-options
- Graph API Complex Type Reference (bookmarked to AppRoleAssignment): https://msdn.microsoft.com/en-us/Library/Azure/Ad/Graph/api/entity-and-complex-type-reference#AppRoleAssignmentEntity
- Azure code samples (including a handful of Active Directory examples): https://github.com/Azure-Samples