Posted by on Jan 21, 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 the new converged authentication model (app model v2.0 preview) to register our application and obtain OAuth 2.0 tokens that we can use to call the Microsoft Graph.  Using the converged authentication model will allow for anyone with an Azure AD user or a Microsoft account to use their identity in your solution, and for you to call the Microsoft Graph on their behalf.

If you’re building a production ready application, this route may not be you – instead, have a look at the Azure AD authentication model which is stable and generally available: http://simonjaeger.com/microsoft-graph-authentication-with-azure-ad/

Please know that using the converged authentication model may limit the features available to you when using the Microsoft Graph. Read more about the limitations at: https://azure.microsoft.com/en-us/documentation/articles/active-directory-v2-limitations/

Register in the Application Registration Portal

Find your way to the new Application Registration Portal at: https://apps.dev.microsoft.com/ 

Sign in with either an Azure AD user or a Microsoft account (converged authentication right there!) and click the “Add an app” button in the top right corner.

newcapp

Enter a unique name for you application and hit the “Create application” button. This can be changed later.

If you’re familiar with the Azure AD authentication model, you might be looking for the place to define your application as a web solution or a native client application… this has now been converged into one single application entity.

cappname

Once your application has been created – let’s define the platforms that our application will be available on.

On the configuration page of your application, locate the “Platforms” section and click the “Add Platform” button. Choose a platform, “Web” or “Mobile application” and continue. If your application will be available on both platforms, repeat the process and create another platform entry.

newplat

If you have added a “Web” platform you must configure at least one “Redirect URI” – this is where granted credentials will be sent once a user successfully authenticates. Make sure that your service can respond and catch credentials at the specified URI. It does not need to be a physical endpoint, but a valid URI that your application can catch responses from.

redirect

Make sure to save your changes for the platforms to be added to your application.

Permissions

If you are familiar with the Azure AD authentication model (http://simonjaeger.com/microsoft-graph-authentication-with-azure-ad/), you would be used to define permissions in your application at this point. Permissions defining the different resources and capabilities that your application wants access to. In turn, this is what the user would be presented with when accessing and authorizing your application.

In the converged authentication model this is no longer required. Instead the permissions are passed in as a scope parameter when going through the OAuth 2.0 flows.

OAuth 2.0 Endpoints

The converged authentication model uses the common (multi-tenant) endpoints in Azure AD as the OAuth 2.0 endpoints.

The two endpoints are:
Authorization: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Tokenhttps://login.microsoftonline.com/common/oauth2/v2.0/token

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 your solution will be sent an authorization code via the configured redirect URI. This authorization code can be exchanged for OAuth 2.0 tokens at the token endpoint.

Your first step is to generate a client secret (password) in the configuration page of your 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.

Click the “Generate New Password” button in the “Application Secrets” section.

newapppass

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 application.

A scope parameter is required in your authorization URL. Please view this page to locate the desired scopes required by your application: http://graph.microsoft.io/docs/authorization/converged_auth 

When constructing the URL, you need to add the Microsoft Graph URL to the beginning of the scope like this:

https://graph.microsoft.com/User.Read

If you are using OpenID Connect – you should add the openid scope to your scope string. Also, if you would like to be able to claim refresh tokens (used to exchange for new access tokens whenever yours expire) you should add the offline_access scope. The openid scope and offline_access scopes do not need the Microsoft Graph endpoint included when adding them to the scope string.

Combine multiple scopes by adding a space in between each scope. Forming a scope string like this:

https://graph.microsoft.com/User.Read https://graph.microsoft.com/Mail.Read offline_access

The final format should look somewhat like this (be sure to URL encode your redirect URI and the scope string):

GET: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={application ID}&response_type=code&redirect_uri={redirect URI}&scope={scope string}

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}

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/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&code={authorization code}&client_id={application id}&client_secret={client secret}&scope={scope string}

Again, make sure to URL encode your redirect URI, scope string and also the client secret in this case. Your response will contain a JSON object with the OAuth 2.0 tokens, scope (permissions), expiration information and more:

ctoken

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 application – you will need to make sure that it’s enabled in your application configuration.

cimplicflow

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”.

You should end up with something like this:

GET: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={application ID}&response_type=token&redirect_uri={redirect URI}&scope={scope string}

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}&scope={scope string}

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

caccesstoken

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. In addition, anyone with either an Azure AD user or a Microsoft account can use their identity to access your solution – and for you as developers, it’s a single application definition in the Application Registration Portal!

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