Posted by on Jan 18, 2016 in #Office365Dev | 1 comment

If you haven’t heard, there is an easy way to call a great amount of Microsoft APIs – using one single endpoint. This endpoint, so called the Microsoft Graph (https://graph.microsoft.io/) lets you access everything from data, to intelligence and insights powered by the Microsoft cloud.

No longer will you need to keep track of different endpoints and separate tokens in your solutions – how great is that? This post is an introductory part of getting started with the Microsoft Graph. For changes in the Microsoft Graph, head to: https://graph.microsoft.io/changelog

We will use Azure AD to register our application and obtain OAuth 2.0 tokens that we can use to call the Microsoft Graph. If you’re building a production ready application, this route is for you. This will allow for anyone with an Azure AD user to use their identity in your solution, and for you to call the Microsoft Graph on their behalf.

If you’re interested in covering both Azure AD users and Microsoft accounts – the converged application model (v2.0) may be out of interest for you. This new model lets you register an application once for both Azure AD and Microsoft accounts. But please note, this model is still in preview and may be subject to radical changes – which may break your implementations. Read the limitations and restrictions of the converged application model here: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-limitations/

Register in Azure AD

Head to the current management portal for Azure and locate (or create) your Azure AD tenant: https://manage.windowsazure.com/simonj.onmicrosoft.com#Workspaces/ActiveDirectoryExtension/

Once in your Azure AD tenant, click on the Applications tab and hit the Add button to start registering your application.

azuread1

Select “Add an application my organization is developing” in the dialog and follow the wizard by describing your application using the various fields. If you’re developing a web solution or a native client application, the next fields will differ – as the authentication flow required may be different.

For a web solution (web app/web API); configure a sign-on URL where your users can sign into your solution and an App ID URI which is a unique identifier for your solution within Azure AD.

azuread3

For a native client application, configure a redirect URI that Azure AD should send responses back to. It does not need to be a physical endpoint, but a valid URI that your application can catch responses from.

Add permissions to Microsoft Graph

Once your application has been created, head to the “Permissions to other applications” section and click on the “Add application” button.

addapp

Now select “Microsoft Apps” and hit the add button for the Microsoft Graph item. Finally click on the checkmark button down at the bottom to save your changes.

azuremsgraph

Your last step is to select the permissions that your application needs. If you want to act on behalf of a user (most of you do), you should pick delegated permissions. Acting as the application with so called application permissions may require administrator approval before your solution can be used by users.

addp

If you are familiar with the OAuth 2.0 flow used with Azure AD; the “Access user’s data anytime” permission is for enabling refresh tokens. Use this to exchange for new access tokens whenever yours expire (approximately after an hour).

There are a couple of different OAuth 2.0 flows to consider before starting to acquire access tokens. Depending on what you are building you may pick a different route.

Before moving on, locate your OAuth 2.0 endpoints by clicking the “View Endpoints” button down at the bottom of the configuration page for your Azure AD application. Locate the authorization endpoint and the token endpoint.

oauthendpoints

If your solution is multi-tenant, swap the tenant ID for “common” to form the correct endpoint. In my case above it would be “https://login.microsoftonline.com/common/…”

You need the authorization endpoint and the token endpoint in the OAuth 2.o flows.

OAuth 2.0 Authorization Code Grant Flow

This flow is what most of you will need (unless you’re building a SPA web app with a JavaScript heavy front-end, the implicit grant flow is for you).

The basic idea is that the user will sign in, accept the permissions requested by your application and Azure AD will send your solution via the configured reply URL an authorization code. This authorization code can be exchanged for OAuth 2.0 tokens at the token endpoint.

Your first step is to generate a client secret (key) in the configuration page of your Azure AD application. Be aware that once your client secret is generated, you will never be able to see it again – so store it safely once you get it.

newkey

Now you can construct the authorization URL using the OAuth 2.0 authorization endpoint. This is needed to let users authenticate with your Azure AD application. You’ll find all of the required parameters in the configuration page of your Azure AD application. The final format should look somewhat like this:

GET: https://login.microsoftonline.com/{tenant ID or “common”}/oauth2/authorize?client_id={client ID}&response_type=code&redirect_uri={redirect URI}

Also… be sure to URL encode your redirect URI.

When a user navigates to the above authorization URL in a browser and authenticates… the user will be navigated to your redirect URI with an authorization code as a query parameter like the following:

GET: {redirect URI}?code={authorization code}&session_state={session state}

Extract the authorization code and be ready to POST it along with a couple of more parameters to the token endpoint.

POST: https://login.microsoftonline.com/{tenant ID or “common”}/oauth2/token
Content-Type: application/x-www-form-urlencoded
Body: client_id={client ID}&client_secret={client secret}&grant_type=authorization_code&code={authorization code}&redirect_uri={redirect URI}&resource=https%3A%2F%2Fgraph.microsoft.com%2F

Again, make sure to URL encode your redirect URI and also the client secret in this case. Pay attention to the resource parameter – which specifies the Microsoft Graph endpoint as a resource (URL encoded). This way Azure AD knows that we are requesting tokens that are valid for usage with the Microsoft Graph.

Your response will contain a JSON object with the OAuth 2.0 tokens, permissions (scope), expiration information and more:

response1

Read more about the authorization code grant flow at: https://msdn.microsoft.com/sv-se/library/azure/dn645542.aspx

OAuth 2.0 Implicit Grant Flow

If you’re building a SPA web app you may be in need of the implicit grant flow, as you’ll perform most of your computing on the client-side. Before you can use the implicit grant flow with your Azure AD application – you will need to enable it in your Azure AD application.

Download the manifest of your Azure AD application in the configuration page to your machine.

downloadman

Open the manifest file in any editor, it’s a plain JSON file and should be easy to modify. Find the oauth2AllowImplicitFlow property and change its value from “false” to “true”.

manifest

Save the manifest file and upload it to your configuration page of the Azure AD application.

Once the implicit grant flow is enabled – it’s pretty straight forward to construct your authorization URL. Take the authorization URL created in the authorization code grant flow section and swap the response_type value from “code” to “token”. Also, you need to append the resource parameter to the authorization URL for this flow.

You should end up with something like this:

GET: https://login.microsoftonline.com/{tenant ID or “common”}/oauth2/authorize?client_id={client ID}&response_type=token&redirect_uri={redirect URI}&resource=https%3A%2F%2Fgraph.microsoft.com%2F

When a user navigates to the above authorization URL in a browser and authenticates… the user will be navigated to your redirect URI with an access token and a few more properties using a fragment identifier:

GET: {redirect URI}#access_token={access token}&token_type=Bearer&expires_in={expires in}&session_state={session state}

Catch the properties and be ready to store them until they expire.

accesstoken

With that you should be able to acquire the OAuth 2.0 (access) tokens you need to use with the Microsoft Graph, using either the authorization code flow or the implicit grant flow. Read more about different authentication scenarios at: https://azure.microsoft.com/sv-se/documentation/articles/active-directory-authentication-scenarios/

Enjoy getting everything from data, to intelligence and insights powered by the Microsoft cloud – using a single endpoint… the Microsoft Graph!

-Simon Jaeger