Utiliser l’authentification unique (SSO) dans les compléments Office avec Microsoft Graph
Les utilisateurs se connectent à Office (plateformes en ligne, mobiles et de bureau) à l’aide de leur compte Microsoft personnel, de leur compte professionnel, ou scolaire (Office 365).
Le meilleur moyen pour un complément Office d’obtenir un accès autorisé à Microsoft Graph est d’utiliser les informations d’identification pour la connexion Office de l’utilisateur. Cela leur permet d’accéder à leurs données Microsoft Graph sans avoir à se connecter une deuxième fois.
Dans cette unité, vous allez découvrir comment implémenter l'authentification unique dans un complément Office pour soumettre des demandes et récupérer des informations à partir de Microsoft Graph.
Compléments Office, Authentification unique, et Microsoft Graph
Commençons par examiner le fonctionnement du flux d’authentification à l’exécution lorsqu’un complément Office implémente l’authentification unique dans le but d’accéder à Microsoft Graph.
Dans le complément, JavaScript appelle la méthode
getAccessToken()de l’API Office.js. Cette méthode indique à l’application cliente Office qu’elle doit obtenir un jeton d’accès au complément.Remarque
Ce jeton est communément appelé Jeton d’accès bootstrap, car il est remplacé par un deuxième jeton plus loin dans le processus.
Si l’utilisateur n’est pas connecté, l’application cliente Office ouvre une fenêtre contextuelle pour qu’il se connecte.
Si c’est la première fois que l’utilisateur actuel utilise votre complément, il est invité à donner son consentement.
L’application cliente Office demande au jeton d’accès bootstrap à partir du point de terminaison v2.0 Azure AD pour l’utilisateur actuel.
L’ID Microsoft Entra retourne le jeton de démarrage à l’application cliente Office.
L’application cliente Office envoie le jeton d’accès bootstrap au complément dans le cadre de l’objet de résultat renvoyé par l’appel
getAccessToken().JavaScript dans le complément effectue une requête HTTP à une API web qui est hébergée sur le même domaine pleinement qualifié comme le complément et inclut le jeton d’accès bootstrap comme preuve d’autorisation.
Le code côté serveur valide le jeton d’accès bootstrap reçu.
Le code côté serveur utilise le flux OAuth2 On-Behalf-Of (OBO) pour obtenir un jeton d'accès pour Microsoft Graph en échange du jeton d'accès bootstrap.
L’ID Microsoft Entra retourne le jeton d’accès à Microsoft Graph et un jeton d’actualisation, si le complément demande offline_access autorisation, au complément.
Le code côté serveur met en cache le jeton d’accès à Microsoft Graph.
Le code côté serveur effectue des requêtes à Microsoft Graph et inclut le jeton d’accès à Microsoft Graph.
Microsoft Graph renvoie des données au complément, qui peut les transmettre à l’interface utilisateur du complément.
Lorsque le jeton d’accès à Microsoft Graph expire, le code côté serveur peut utiliser son jeton d’actualisation pour obtenir un nouveau jeton d’accès à Microsoft Graph.
Office ne peut pas demander le consentement des autorisations Microsoft Graph
Les étapes décrites ci-dessus indiquent qu’Office peut demander à l’utilisateur d’approuver les autorisations du complément pour la connexion. Toutefois, il est utile de noter qu’Office peut uniquement demander l’approbation de l’étendue profile OpenID. Office ne peut pas demander à l’utilisateur d’approuver une autorisation Microsoft Graph.
Cela peut présenter un problème pour votre complément, car il ne sait pas si ce jeton bootstrap initial peut être utilisé dans le OAuth2 OBO pour obtenir un jeton d’accès pour appeler Microsoft Graph.
Si votre code a besoin d’autorisations sur Microsoft Graph, ou d’autorisations supplémentaires que l’utilisateur n’a pas encore consentées, lorsque Microsoft Graph reçoit le jeton d’amorçage, il échoue avec un code d’erreur spécifique : AADSTS65001. Ce code d’erreur indique que le consentement aux autorisations Microsoft Graph demandées n’a pas encore été accordé.
Dans ce scénario, votre complément doit très bien gérer ce scénario avec un système d’autorisation de secours qui invite l’utilisateur à approuver les autorisations Microsoft Graph nécessaires.
Éviter plusieurs allers-retours : l’échec rapide
Une chose que vous remarquerez à partir de ces étapes est les nombreux allers-retours vers Microsoft Entra ID. Et particulièrement lors de la demande d’utilisation d’un jeton d’accès à utiliser avec Microsoft Graph. Votre complément doit commencer plusieurs allers-retours pour savoir si l’utilisateur doit approuver davantage d’autorisations pour Microsoft Graph.
La méthode getAccessToken() dans le SDK Office.js accepte un objet d’options que vous pouvez utiliser pour implémenter une approche Échec rapide. Si vous passez { forMSGraphAccess: true } à cette méthode, l’ID Microsoft Entra effectue une vérification supplémentaire avant de retourner le jeton de démarrage.
Si l'utilisateur a consenti aux autorisations Microsoft Graph demandées, votre complément recevra le jeton d'amorçage que vous pourrez utiliser pour échanger avec Microsoft Graph à l'aide du flux OAuth2 OBO afin d'obtenir un jeton d'accès qui pourra être utilisé pour appeler Microsoft Graph.
Toutefois, si l’utilisateur n’a pas consenti aux autorisations Microsoft Graph demandées, l’ID Microsoft Entra répond avec une erreur 13012 . Votre code peut gérer cette erreur en revenant au système d’autorisation de remplacement. Cette autre procédure ouvre une boîte de dialogue et invite l’utilisateur à approuver les autorisations Microsoft Graph nécessaires.
Ainsi, votre complément peut éviter plusieurs demandes simplement pour savoir si l’utilisateur doit donner son consentement pour les autorisations Microsoft Graph.
Le code dans le projet d’authentification unique du complément Office par défaut inclut le code réutilisable nécessaire à l’implémentation de ce processus d’autorisation secours. Ils se trouvent tous sous la forme de fichiers ./helpers/fallbackauth*.* , une collection de fichiers HTML et JavaScript qui implémentent la boîte de dialogue contextuelle.
Appeler Microsoft Graph à partir du code côté client
Pour envoyer une demande à Microsoft Graph, vous devez d’abord appeler cette méthode getAccessToken(). Dans cet exemple, nous allons vous faire passer l’option allowSignInPrompt: true que vous pouvez utiliser si le complément peut être utilisé au moment où il est lancé et qu’aucun utilisateur ne s’est encore inscrit.
const sso = require("office-addin-sso");
// ...
let bootstrapToken = await OfficeRuntime.auth.getAccessToken({ allowSignInPrompt: true });
Ensuite, vous allez essayer d’échanger ce jeton bootstrap pour un jeton d’accès qui peut être utilisé pour appeler Microsoft Graph. C’est à ce niveau que démarre le flux OAuth2 OBO :
let exchangeResponse = await sso.getGraphToken(bootstrapToken);
En supposant que l’utilisateur a approuvé les autorisations Microsoft Graph nécessaires, vous pouvez demander les informations de profil de l’utilisateur à partir de Microsoft Graph en appelant la méthode makeGraphApiCall() incluse dans le package JavaScript office-addin-sso fourni :
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Si vous avez besoin de plus de contrôle sur la requête à Microsoft Graph, notamment en appelant un point de terminaison spécifique ou en fournissant plus de contrôle sur les paramètres de l'URL, vous pouvez utiliser lagetGraphData() méthode :
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Comme mentionné précédemment, si l’utilisateur n’a pas accordé son consentement à Microsoft Graph pour les autorisations nécessaires, ou s’il doit se connecter, tous les extraits de code mentionnés précédemment peuvent être encapsulés dans un try-catch bloc qui gère les erreurs d’authentification et d’autorisation retournées par l’ID Microsoft Entra. Dans ce cas, il implémente le système de boîte de dialogue d’autorisation de secours :
const fallbackAuthHelper = require("./fallbackAuthHelper");
// ...
try {
// 1. get bootstrap token
// 2. exchange bootstrap token for access token
// 3. call Microsoft Graph
} catch (exception) {
if (exception.code) {
if (sso.handleClientSideErrors(exception)) {
fallbackAuthHelper.dialogFallback();
}
} else {
sso.showMessage("EXCEPTION: " + JSON.stringify(exception));
}
}