Sign up for Office 365
Learn more about Office 365
In my previous post, I showed some more advanced filtering capabilities using the Graph Explorer. The Graph Explorer tool is an easy to use tool to try different queries and see the returned data. It does “hide” some of the underlying protocol, including how to authenticate to the Graph API, and what the actual http calls look like. In this post I’ll go into details about this, and I’ll be using Fiddler to expose the protocol - Fiddler is a great tool for debugging your application, and great for hand-crafting http requests and reviewing the detailed responses (http://fiddler2.com/get-fiddler). I believe by being able to see the protocol in detail, it helps you to write your code later, and also gives you a good reference for how to troubleshoot issues.
Now for a few details about Authentication to the Graph API to access directory information. First, every call to the Graph API must be authenticated – the exceptions are:
You could replace contoso.com with Foobar in the examples above, and still get the same, valid results. This is because the data returned to these two queries are not specific to any tenant at this time – this is system wide data.
All other queries, are scoped per tenant, and must be authenticated. Accessing https://graph.widows.net/contoso.com/users requires separate authentication, than a call to https://graph.windows.net/fabrikam.com/users
So how is a Graph API call authenticated? First, under the Tenant hosted in Azure Active directory, there needs to be an object, specifically, a service principal object, that represents the client application. There must also be an application credential associated with this service principal object, that contains the Application ID and Application Secret – these are configured under the Azure AD tenant, very similar to how a user is provisioned under a tenant, and has a User Name and Password – the application credentials allow the application to authenticate to a particular tenant. The client application must first call the Azure Authentication endpoint, and request a token for the Graph API, and the tenant for which they want to access information from. In this request, it includes Application ID and Secret – if those are validated by the Azure Authentication endpoint, then a token is issued to the client application. The application then includes this token in subsequent requests to access the Graph API for the tenant – the token does have an expiration, so the client application will eventually need a new token.
To see all of this first hand, you can install Fiddler, and try this for yourself. This example is for the demo Azure AD company, GraphDir1.onMicrosoft.com – this demo company has about 28 users, 14 groups and is licensed for Office 365 Enterprise.
In the Request Body, add the following:
This Request body contains four important pieces of information for the Azure Authentication endpoint:
a) The OAuth “grant type”, in this case it is OAuth client credentials (I will review OAuth 2.0 later and supported authentication flows).
b) the requested resource: https://graph.window.net
c) the Client ID (App ID): d266d7cc-13c7-4e89-aaac-8c699cf6aff2
d) the Client Secret (App password): 8K+0OX6pvUZtaGo4YdUogT9xiF15aqyx1HbSvEg8Sec=
If all of the above information is validated by Azure Authentication, and there is a valid service principal is provisioned under the tenant GraphDir1.onMicrosoft.com with the above client ID and Secret, then a token will be returned to the application. So, in Fiddler, you should see under Inspector, a returned JSON object looking like object shown below. The most important element, is the “access_token” value – this should a very long, guid like value starting with the “eyJ..” – this is the actual token value. It is base 64 encoded (you could cut and paste the value and put it into a base64decoder tool to see more details of the token). For you reference this token is a “JWT” token, pronounced ‘jawt’, which stands for a JSON Web Token.
Now that you have a valid token, copy the value. To do this in Fiddler, you can highlight the access_token field, and right-click and select Copy. You will use in step 2.
2. Make the Graph API call with the valid token: we can now hand-craft a Graph API call. In Fiddler, under Composer we’ll execute a GET users query. Execute a GET to the following URL (yes, you will need to specify the api-version as part of the query).
In the Request Headers windows in Fiddler Compose, add the token to a header property called Authorization, as shown here. Note, I don’t show the entire token to save space, and I put “Bearer “ just in front of the token value. Also specify the return content formatting type.
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aE……
If everything was entered correctly, then your call should be successful, and return a HTTP OK 200 response, along with a list of Users in JSON format – in the Inspector Tab, select JSON, to look at the Java Script Object Notation formatted results of users.
You can continue to do other Graph queries for this same demo company, using the same token - tokens are valid for a few hours.
You may be curious as to how to configure a service principal under the tenant, where the Application ID and Secret are available from, and also what/how Authorization is allowed for an application – for example, the example AppID and Secret that I shared above is associated with a service principal that is only allowed to READ data from this demo company – it will not be able to execute any Write Operations. The short answer is that the configuration of applications for a tenant is done through the Azure Management Portal, enabling a Tenant Administrator to add applications to their organization and to configure the correct application permissions. Customers who own a tenant via their Office 365, Intune or Dynamics CRM subscriptions, can use the Azure management portal, by signing up for an Azure Trial, and use the management portal to manage application registration and configuration. In my upcoming post, I’ll demonstrate this, along with introducing how you can build a multi-tenant application, which can be offered to tenants who are in Azure Ad. In the meantime, you can watch a video on this here: http://channel9.msdn.com/Series/Windows-Azure-Active-Directory/Programming-Windows-Azure-Active-Directory-Deep-Dive
Next I'll show how to setup Application ID's, Secrets, and configuring authorization, and making your application a multi-tenant application that other tenants can use.
Very useful, thank you!
241 Microsoft Team blogs searched, 64 blogs have new articles. 227 new articles found searching from
In my previous Post , I reviewed how to authenticate to the Graph API using OAuth 2.0 Client credentials
Thank you for this post. How to authenticate office 365 users using Graph API. Please help!