Susan Williams
February 11, 2016

Tips for Working with the Azure Active Directory Graph API

Susan Williams

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:

6 Comments

  1. 6 Drake 02 Mar
    Thanks for the post.  I am however having a hard time retrieving the  custom application Roles that I assigned to a user.  I followed the instructions from this website (http://www.dushyantgill.com/blog/2014/12/10/roles-based-access-control-in-cloud-applications-using-azure-ad/) in order to assign custom app Roles, but getting out using the API does not work even when using the servicePrincipal.  Any suggestions?  Thanks.
  2. 5 Susan Williams 04 Mar
    Hi Drake,
    I am happy to assist but it is difficult to make suggestions without more detail on what is happening. It sounds like you were able to successfully go in, create custom roles and assign them to users, as well as retrieve the Service Principal Id.
    When using the call to get the roles for a user, is any data returning or are you receiving an error? Can you successfully make requests using the API to retrieve the basic user information?
    I'll do my best to answer any questions you have!
  3. 4 Ridhima Banu 18 Mar

    I feel happy about and I love learning more about this topic. keep sharing your information regularly for my future reference. This content creates a new hope and inspiration with in me. Thanks for sharing article like this. The way you have stated everything above is quite awesome. Keep blogging like this. Thanks.

    Regards,
    Ridhima


  4. 3 Annette 13 Jun
    I have application portal inside which 86 applications are registered. When user loggs in to portal, user can view one or more applications inside portal as per his access.
    My question is how to get application names that specific user has access?
     Note :  users will have access to multiple applications as per their access.
    Please help
  5. 2 John McCann 15 Jul
    Fantastic post! I thought I'd take a break from beating my head against the graph API wall and ask you this question. Is it possible to add an application role via the graph API? I am able to assign previously defined app roles in the manifest to groups and users via the graph API, but would now like to manage application roles themselves, such as creating and deleting them.

    Thanks a ton, now back to the wall ... goto line 100: head.beat(wall);
    John  
  6. 1 Sam 04 Nov
    Great article!
    Can you please advise on adding role to group instead of user as you explained in your example?
    Thanks for pointers!

Comment

  1. RadEditor - HTML WYSIWYG Editor. MS Word-like content editing experience thanks to a rich set of formatting tools, dropdowns, dialogs, system modules and built-in spell-check.
    RadEditor's components - toolbar, content area, modes and modules
       
    Toolbar's wrapper 
     
    Content area wrapper
    RadEditor's bottom area: Design, Html and Preview modes, Statistics module and resize handle.
    It contains RadEditor's Modes/views (HTML, Design and Preview), Statistics and Resizer
    Editor Mode buttonsStatistics moduleEditor resizer
      
    RadEditor's Modules - special tools used to provide extra information such as Tag Inspector, Real Time HTML Viewer, Tag Properties and other.
       

Subscribe to Our Blog

Get the latest blog posts sent right to your inbox so you never miss an informative post from Mercury.

 

Get Your Share On!

 

Tags