Accueil Nos publications Blog Intégrez Microsoft Graph dans vos applications
.NET
Niveau
13/02/2019 7 min

Intégrez Microsoft Graph dans vos applications

Introduction

Avec l’évolution de ses produits et services, Microsoft disposait de plusieurs API (AAD, Office365, etc.).

Afin de faciliter les tâches pour les développeurs, le géant a finalement eu recours à l’unification des ses API en un seul. C’est le Microsoft Graph.

Pourquoi Microsoft Graph ?

Microsoft Graph est la première couche avec laquelle interagir lorsque l’on veut utiliser la plupart des API existantes de Microsoft et les intégrer dans nos applications.

C’est pour cela que Microsoft a offert aux développeurs une API, avec laquelle on peut implémenter et intégrer plusieurs de ses services, du plus basique au plus complexe, dans un seul environnement.

Les APIs exposées sont :

  • Azure Active Directory
  • Les services Office 365 : SharePoint, OneDrive, Outlook/Exchange, Microsoft Teams, OneNote, le Planificateur et Excel
  • Les services Enterprise Mobility and Security : Identity Manager, Intune, Advanced Threat Analytics et Advanced Threat Protection
  • Les services de Windows 10
  • Education

En effet, ces services font partie de la nouvelle offre Microsoft 365.

Et pour la firme de Redmond, Microsoft Graph est l’API pour Microsoft 365.

Source : Microsoft Graph

Cette API est utilisée dans plusieurs applications business, notons par exemple DocuSign qui l’utilise pour permettre l’intégration transparente avec la solution eSignature afin d’optimiser le processus d’accord.

Graph Explorer

Nous pouvons commencer directement l’intégration de l’API dans notre application.

Mais, pourquoi ne pas tester les fonctionnalités avant de passer au développement ?

Ce test est possible grâce au Graph Explorer : une interface qui nous permet d’invoquer les différentes actions de l’API sans besoin d’écrire du code.

En général, pour exécuter une action dans Microsoft Graph, il faut utiliser une URL sous ce format :

https://graph.microsoft.com/{version}/{action}

Version : numéro ou indicateur de la version à utiliser.

Actuellement, MS Graph possède deux versions : 1.0 et beta

La version beta (https://graph.microsoft.com/beta) n’est pas conçue pour l’utilisation en production et elle peut changer à tout moment. Elle était mise en place afin de tester et valider l’ajout, la modification ou la suppression des fonctionnalités.

La version 1.0 (https://graph.microsoft.com/1.0) est la version actuelle qui contient des fonctionnalités prêtes à l’utilisation en production.

Connexion

Pour commencer, rendez-vous sur la page de l’explorer.

Connectez-vous avec votre compte Microsoft.

Une fois connecté, vous pouvez accéder aux différents exemples.

Visualiser les différents exemples

Pour visualiser et tester les exemples disponibles, il faut les activer ou les désactiver par catégories.

Profil de l’utilisateur

Pour avoir le profil de l’utilisateur connecté, il faut utiliser l’URL basique en ajoutant /me

Liste des emails

Pour avoir la liste des emails de l’utilisateur connecté, il faut utiliser l’URL basique en ajoutant /me/messages

Intégration

Passons maintenant à l’intégration de l’API Microsoft Graph dans notre application.

Enregistrement de l’application

Il faut tout d’abord enregistrer l’application dans le portail d’enregistrement de l’application Microsoft.

Cette procédure est obligatoire afin d’établir l’identificateur (Application ID) et la clé (Key) de l’application qui vont être utilisés par notre application pour faire des appels à l’API.

 

Puis, il faut ajouter une nouvelle application.

 

 

 

 

 

Une fois sur la page d’enregistrement, il faut ajouter un nom et cliquer sur Create.

 

 

 

 

 

L’application est maintenant créée dans le portail.

Il faut préciser quel type d’application on va utiliser.

Pour cela, il faut aller dans les détails de l’application en cliquant sur le nom.

Pour sélectionner la plateforme, il faut cliquer sur Add Platform.

Dans notre cas, c’est une application console, donc on sélectionne Native Application.

Permissions

Avant de passer au développement, il faut préciser les permissions de l’application.

Ces dernières sont utilisées pour contrôler l’accès de l’application aux différentes ressources comme les informations des utilisateurs ou les groupes.

Il existe deux types de permissions :

  • Déléguées : ce type est destiné aux actions invoquées par un utilisateur connecté. Autrement dit, l’utilisateur délègue ses permissions à l’application.
  • Application : ce type est utilisé par les applications directement

Dans notre exemple, nous voulons récupérer les informations de l’utilisateur ainsi que ses emails. Donc, nous devons ajouter la permission User.Read.

Dans ce cas, nous n’avons pas besoin de le faire, car cette permission est ajoutée par défaut lors de la création de l’application.

Access Token

La première tâche dans le processus d’utilisation de Microsoft Graph est l’obtention du jeton d’accès ou Acces Token.

Ce jeton contient des informations à propos de l’application et ses permissions.

Il faut l’ajouter dans le Header de chaque requête pour pouvoir accéder aux ressources.

Accès au nom de l’utilisateur vs Accès sans utilisateur

L’appel aux ressources de Microsoft Graph se fait soit au nom d’un utilisateur (connecté/autorisé), soit à partir de l’application (démons ou service d’arrière plan) directement.

Dans les deux cas, il faut obtenir le jeton d’accès.

Dans la suite de l’article, nous utilisons la première solution : Accès au nom de l’utilisateur.

 

Nous attaquons maintenant la partie code.

Pour interroger l’API, nous avons deux choix :

  • REST API
  • SDK pour .Net, Java, Android, iOS, etc.

REST API

Pour intégrer le REST API dans notre application (Web par exemple), il nous suffit d’utiliser les URLs comme montré dans le Graph Explorer.

Obtenir le Token

Pour obtenir le token, on passe par deux étapes :

  • Autorisation ou connexion de l’utilisateur : https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  • Demande du token : https://login.microsoftonline.com/common/oauth2/v2.0/token

La réponse du token contient le jeton d’accès lui-même, ses informations (type, scope/permissions, durée de validité) ainsi qu’un jeton d’actualisation (Refresh Token) qui permet d’acquérir un nouveau jeton après l’expiration du jeton d’accès en cours.

Information d’un utilisateur

Pour récupérer les informations de l’utilisateur en cours, il faut appeler l’URL : https://graph.microsoft.com/v1.0/me

Liste des emails

Pour récupérer la liste des emails de l’utilisateur en cours, il faut appeler l’URL : https://graph.microsoft.com/v1.0/me/messages

 

SDK

Et si nous voulons simplifier le processus de développement, nous avons également la possibilité de profiter du SDK.

Pour l’utiliser, nous prenons l’exemple d’une application console en C#.

Pour ce faire, il faut installer les packages nuget Microsoft.Graph et Microsoft.Identity.Client.

Connexion : Obtenir le Token


using System;
using System.Threading.Tasks;
using Microsoft.Identity.Client;

class Program
{
private static readonly string ClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
private static readonly string[] Scopes = { "User.Read" };

static void Main(string[] args)
{
// Get Token
string token = GetTokenAsync().Result;

// Write token
Console.WriteLine(token);

Console.ReadKey();
}

private static async Task GetTokenAsync()
{
PublicClientApplication clientApp = new PublicClientApplication(ClientId);
AuthenticationResult authResult = await clientApp.AcquireTokenAsync(Scopes);
return authResult.AccessToken;
}
}

Le Client ID est appelé Application ID dans le portail.

Le Scope est la permission utilisée (User.Read).

À l’aide du SDK, on appelle la méthode AcquireTokenAsync() afin de récupérer le token.

Information d’un utilisateur

Passons maintenant aux actions.

Commençons par la récupération des informations de l’utilisateur.


using System;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Microsoft.Graph;
using Microsoft.Identity.Client;

class Program
{
private static readonly string ClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
private static readonly string[] Scopes = { "User.Read" };
private static readonly string BaseUrl = "https://graph.microsoft.com/v1.0";

static void Main(string[] args)
{
// Get Client
GraphServiceClient graphClient = GetClient();

// Send request to get user's informations
User user = graphClient.Me.Request().GetAsync().Result;

Console.WriteLine($"Id : {user.Id}");
Console.WriteLine($"Email : {user.UserPrincipalName}");
Console.WriteLine($"Display Name : {user.DisplayName}");

Console.ReadKey();
}

private static async Task GetTokenAsync()
{
PublicClientApplication clientApp = new PublicClientApplication(ClientId);
AuthenticationResult authResult = await clientApp.AcquireTokenAsync(Scopes);
return authResult.AccessToken;
}

private static GraphServiceClient GetClient()
{
return new GraphServiceClient(
BaseUrl,
new DelegateAuthenticationProvider(async (requestMessage) =>
{
requestMessage.Headers.Authorization = new AuthenticationHeaderValue("bearer", await GetTokenAsync());
}));
}
}

On commence par initialiser un GraphServiceClient en ajoutant en Header le token déjà récupéré.

Ensuite, on appelle l’action Me.Request() qui nous retourne l’utilisateur connecté et ses informations.

Liste des emails

Et terminons avec la liste des emails.


using System;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Microsoft.Graph;
using Microsoft.Identity.Client;

class ProgramMessages
{
private static readonly string ClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
private static readonly string[] Scopes = { "Mail.Read" };
private static readonly string BaseUrl = "https://graph.microsoft.com/v1.0";

static void Main(string[] args)
{
// Get Client
GraphServiceClient graphClient = GetClient();

// Send request to get user's messages
var messages = graphClient.Me.Messages.Request().GetAsync().Result;

foreach (var msg in messages)
{
Console.WriteLine($"Sender : {msg.Sender.EmailAddress.Address}");
Console.WriteLine($"Subject : {msg.Subject}");
}

Console.ReadKey();
}

private static async Task GetTokenAsync()
{
PublicClientApplication clientApp = new PublicClientApplication(ClientId);
AuthenticationResult authResult = await clientApp.AcquireTokenAsync(Scopes);
return authResult.AccessToken;
}

private static GraphServiceClient GetClient()
{
return new GraphServiceClient(
BaseUrl,
new DelegateAuthenticationProvider(async (requestMessage) =>
{
requestMessage.Headers.Authorization = new AuthenticationHeaderValue("bearer", await GetTokenAsync());
}));
}
}

Ici, on réitère les mêmes étapes en changeant l’action par Me.Messages.Request() qui retourne la liste des emails de l’utilisateur connecté.

Conclusion

Microsoft Graph est une initiative de Microsoft qui vise l’unification de ses API dans un seul endroit.

Nous avons parcouru, dans cet article, quelques fonctionnalités de ce service comme la connexion, la récupération des informations de l’utilisateur ainsi que la liste de ses emails.

Mais cette API contient plusieurs autres fonctionnalités à découvrir dépendamment du besoin.

 

Pour aller plus loin :

Microsoft Graph Developer

Microsoft Graph sur GitHub

© SOAT
Toute reproduction est interdite sans autorisation de l’auteur.

Rédigé par :

Firas Mdimagh