The Microsoft Graph, My New Adventure Begins...

I have been catching up on some of the talks from the 2016 Microsoft Ignite conference, and amongst all of the great talks there was one that caught my eye, it is the one about the Microsoft Graph and how it can power up today's applications Access the Microsoft Graph API to supercharge your Line of Business Applications. I had read a bit about the Azure Active Directory Graph but this one seemed different since this Graph API was connecting with Outlook, Exchange and Active Directory. So I was hooked!

Shortly after watching the Ignite talk, I went on a web hunt to dive into some code and understand how the Microsoft Graph worked and how I could get started developing on it. However, I found that the information I needed to just get started was sprinkled across many different sources. Also, there were a few things that I overlooked, such as the differences between Azure AD Graph and Microsoft Graph, that took me down the wrong path for a bit before I realized I needed to stop and get my bearings before continuing forward. So hopefully this post will help to demystify some of the questions you might have about the Microsoft Graph, which perhaps are things that may be familiar to those that have been involved with the Microsoft Graph for a while, but that may not be as well known for those who are just getting started. But enough talk, let's dive in!

The Azure AD Graph & The Microsoft Graph

When you get started with the Graph API, you are going to find that there is actually a 'Y' on your path: The Azure AD Graph and the Microsoft Graph. Having two Graph offerings has obviously caused a lot of confusion, but fortunately the Microsoft Graph Team addressed this in a blog post that explains the differences between the two, you can read all about it here: https://blogs.msdn.microsoft.com/aadgraphteam/2016/07/08/microsoft-graph-or-azure-ad-graph/ I recommend that you read that blog post for the official news on where the Graph API roadmap is heading. However, if you are starting a new project or just getting to know the Graph API, then I would recommend sticking with the new Microsoft Graph. As the Microsoft Graph team makes it clear that they will in the future be recommending the usage of Microsoft Graph over the Azure AD Graph, so it's a safer bet to follow that recommendation in my opinion.

Office 365, Outlook.com and you

Note that there are currently two authentication endpoints supported by the Microsoft Graph: The Azure AD and the Azure AD V2.0 endpoints. The Microsoft Graph documentation actually explains this in detail and I recommend you read the documentation which is pretty good: https://graph.microsoft.io/en-us/docs/authorization/auth_overview Essentially the Azure AD v2.0 endpoint allows you to authenticate your applications using both, work & school (Azure Active Directory, e.g. myaccount@mydomain.onmicrosoft.com) accounts and personal (Microsoft Account, e.g. myaccount@outlook.com). On the other hand, the Azure AD endpoint can be used only for work & school accounts. It is important to mention that the Microsoft recommendation for new applications going forward is to use the Azure AD V2.0 endpoint, as it provides significant improvements and advantages such as...well, you guessed it, being able to authenticate work & school or personal accounts. :) I had to dig just a bit to find that recommendation, but you can read more about it here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-limitations/ This brings me to my next point, about which account you should use to actually access the Microsoft Graph for testing purposes.

Taking the Microsoft Graph out for a test drive

You can actually test the Microsoft Graph from the comfort of your favorite browser, just head over to https://graph.microsoft.io/en-us/graph-explorer and log in with your account:

If you happened to log into the site with a Microsoft account, you may have encountered an error like the following:

I am inferring that this is due to the fact that behind the scenes Microsoft is still migrating accounts to their new tenant, while at the same time merging the functionality of the two Graph APIs. Keep in mind that at times you may stumble on a construction zone, and a hard hat will be required; but keep up your good spirit, this is only temporary :). You may have been fortunate enough to not have this issue, but if you do then don't despair, there is still a way you can easily test/play with the Microsoft Graph. It's very simple really, just head over to the new Azure Portal and create a new user account in a test tenant of your choice. Your new user may look something like this: newuser@yourAADDomain.onmicrosoft.com. One thing to keep in mind is that in order to use the Graph Explorer, you will have to log in with a user that has Global Administrator privileges, I attempted to login to the Graph Explorer using a standard user account to no avail. This may not be what you want to do for your production tenant, but you can use a test tenant and create a 'temporary' user that has Global Administrator privileges and test with it. Now, once you log in, you will be directed to a consent page where the API Explorer asks you for an extensive number of permissions, driver's license and a picture of your grandmother :)

Again, this may not be what you want to do at all in a production tenant, so more reason to always use a test tenant when conducting these deep ocean cave diving adventures.
So now that you are finally logged into the Graph Explorer, you can just choose the Graph resource of your choice, select the appropriate HTTP verb and let it fetch some data:

Notice that there is a new beta endpoint that is also available in the Graph Explorer. The main difference that I have noticed at first glance is in the greater amount of information that the beta endpoint brings back:

Writing code with the Microsoft Graph

So now that hopefully you are more familiar with the capabilities of the Microsoft Graph, perhaps you feel ready to dive in and eager to look at some code samples? Well, you are in luck! There are a number of Microsoft Graph sample applications provided by Microsoft which are hosted on GitHub. If you are like me and are interested in the AngularJS samples, then I suggest you start with a simple one, such as the Angular Connect Sample. The documentation for the sample application will show you how to authenticate and connect with the Microsoft Graph, which is surprisingly very straight forward. All you have to do is update the Client ID on the configuration file for the sample application, with the Client ID that you receive when you register your application on the development portal https://apps.dev.microsoft.com/, which by the way aims to be as friction-less as possible:

And here is what the editing view for the application details looks like:

Another nice thing about this new portal is the simplicity of how you can apply the 'Implicit Flow' to your application registration by clicking on a simple check box: Allow Implicit Flow, very nice!

Summary

The Microsoft Graph is pretty nifty, although there are still a few rough edges that may cause users new to the Microsoft Graph to stumble a bit. But this is expected as things are quickly changing and merging, which is by no means an easy feat to accomplish. Nevertheless, the vision for the new Microsoft Graph is to create "One endpoint to rule them all", the endpoint of power! And in doing so these types of changes are needed, so as long as you know what to expect there should not be too many surprises:

In any case, I hope that some of this information was useful and will help you in getting started on your journey through the Microsoft Graph. I look forward to diving in deeper into the Microsoft Graph API and sharing my findings with the community.

Until next time, happy coding!