Authentifier et autoriser avec l’API de dialogue Office

  • Article

Utilisez toujours l’API de boîte de dialogue Office pour authentifier et autoriser les utilisateurs avec votre complément Office. Vous devez également utiliser l’API de boîte de dialogue Office si vous implémentez l’authentification de secours lorsque l’authentification unique (SSO) ne peut pas être utilisée.

Les compléments Office s’exécutent dans un iframe lorsqu’ils sont ouverts dans Office sur le Web. De nombreuses autorités d’identité, également appelées Secure Token Services (STS), empêchent leur page de connexion de s’ouvrir dans un iframe. Il s’agit notamment de Google, d’Facebook et de services protégés par le Plateforme d'identités Microsoft (anciennement Azure AD V 2.0), tels qu’un compte Microsoft, un compte Microsoft 365 Éducation ou professionnel, ou tout autre compte commun. Les fonctionnalités de sécurité implémentées dans l’affichage web lorsque les compléments Office s’exécutent dans Office sur Windows ou Office sur Mac peuvent empêcher le bon fonctionnement des pages de connexion.

Pour que l’autorisation fonctionne correctement, la page de connexion doit s’ouvrir dans un navigateur ou un contrôle webview distinct instance. C’est pourquoi Office fournit l’API de boîte de dialogue Office, en particulier la méthode displayDialogAsync .

Remarque

La boîte de dialogue ouverte avec cette API présente les caractéristiques suivantes.

  • C'est non modal.
  • Il s’agit d’une instance de navigateur totalement distincte du volet de tâches, ce qui signifie :
    • Il a son propre environnement d’exécution, son propre objet de fenêtre et ses propres variables globales.
    • Il n’existe pas d’environnement d’exécution partagé dans le volet des tâches.
    • Il ne partage pas le même stockage de session (propriété Window.sessionStorage ) que le volet Office.
  • La première page ouverte dans la boîte de dialogue doit être hébergée dans le même domaine que le volet Office, y compris le protocole, les sous-domaines et le port, le cas échéant.
  • La boîte de dialogue peut renvoyer des informations au volet Office à l’aide de la méthode messageParent . Nous vous recommandons d’appeler cette méthode uniquement à partir d’une page hébergée dans le même domaine que le volet Office, y compris le protocole, les sous-domaines et le port. Sinon, il existe des complications dans la façon dont vous appelez la méthode et traitez le message. Pour plus d’informations, consultez Messagerie inter-domaines au runtime hôte.

Par défaut, la boîte de dialogue s’ouvre dans un nouveau contrôle d’affichage web, et non dans un iframe. Cela garantit qu’il peut ouvrir la page de connexion d’un fournisseur d’identité. Comme vous le verrez plus loin dans cet article, les caractéristiques de la boîte de dialogue Office ont des implications sur la façon dont vous utilisez les bibliothèques d’authentification ou d’autorisation telles que Microsoft Authentication Library (MSAL) et Passport.

Remarque

Pour configurer la boîte de dialogue pour qu’elle s’ouvre dans un iframe flottant, passez l’option displayInIframe: true dans l’appel à displayDialogAsync. Ne le faites pas lorsque vous utilisez l’API de boîte de dialogue Office pour la connexion.

Flux d’authentification avec la boîte de dialogue Office

Voici un flux d’authentification classique.

Diagramme montrant la relation entre le volet Office et les processus de l’explorateur de dialogues.

  1. La première page qui s’ouvre dans la boîte de dialogue est une page (ou une autre ressource) hébergée dans le domaine du complément ; autrement dit, le même domaine que la fenêtre du volet Office. Cette page peut avoir une interface utilisateur qui indique uniquement « Veuillez patienter, nous vous redirigeons vers la page où vous pouvez vous connecter à NAME-OF-PROVIDER ». Le code de cette page construit l’URL de la page de connexion du fournisseur d’identité avec des informations qui sont transmises à la boîte de dialogue comme décrit dans Transmettre des informations à la boîte de dialogue ou sont codées en dur dans un fichier de configuration du complément, tel qu’un fichier web.config.
  2. La fenêtre de dialogue redirige alors l’utilisateur vers la page de connexion. L’URL inclut un paramètre de requête qui indique au fournisseur d’identité de rediriger la fenêtre de dialogue une fois que l’utilisateur s’est connecté à une page spécifique. Nous allons appeler cette page redirectPage.html dans cet article. Les résultats de la tentative de connexion peuvent être transmis au volet Office avec un appel de messageParent sur cette page. Nous recommandons que ce soit une page dans le même domaine que la fenêtre hôte.
  3. Le service du fournisseur d’identité traite la requête GET entrante à partir de la fenêtre de dialogue. Si l’utilisateur est déjà connecté, il redirige immédiatement la fenêtre versredirectPage.html et inclut les données utilisateur sous la forme d’un paramètre de requête. Si l’utilisateur n’est pas déjà connecté, la page de connexion du fournisseur s’affiche dans la fenêtre et l’utilisateur se connecte. Pour la plupart des fournisseurs, si l’utilisateur ne peut pas se connecter correctement, le fournisseur affiche une page d’erreur dans la fenêtre de boîte de dialogue et ne redirige pas vers redirectPage.html. L’utilisateur doit fermer la fenêtre en sélectionnant le X dans le coin. Si l’utilisateur se connecte avec succès, la fenêtre de dialogue est redirigée versredirectPage.html et les données utilisateur sont incluses sous la forme d’un paramètre de requête.
  4. Lorsque la page redirectPage.html s’ouvre, elle appellemessageParent pour indiquer le succès ou l’échec au volet des tâches et éventuellement indiquer également des données utilisateur ou des données d’erreur. Les autres messages possibles incluent le passage d’un jeton d’accès ou le volet des tâches dans lequel le jeton est stocké.
  5. L’événement DialogMessageReceived se déclenche dans le volet des tâches, et son gestionnaire ferme la fenêtre de dialogue et effectue éventuellement d’autres traitements du message.

Prise en charge de plusieurs fournisseurs d’identité

Si votre complément offre à l’utilisateur un choix de fournisseurs, tels qu’un compte Microsoft, Google ou Facebook, vous avez besoin d’une première page locale (voir la section précédente) qui fournit une interface utilisateur permettant à l’utilisateur de sélectionner un fournisseur. La sélection déclenche la construction de l’URL de connexion et la redirection vers celle-ci.

Autorisation du complément pour une ressource externe

Sur le web nouvelle génération, les applications web sont des principaux de sécurité au même titre que les utilisateurs. L'application possède sa propre identité et ses propres autorisations pour une ressource en ligne telle que Microsoft 365, Google Plus, Facebook ou LinkedIn. L’application est inscrite auprès du fournisseur de ressources avant d’être déployée. L’inscription inclut :

  • La liste des autorisations dont l’application a besoin.
  • l’URL à laquelle le service de ressources doit renvoyer un jeton d’accès lorsque l’application accède au service.

Lorsqu’un utilisateur appelle une fonction dans l’application qui accède aux données de l’utilisateur dans le service de ressources, l’utilisateur est invité à se connecter au service, puis à accorder à l’application les autorisations dont elle a besoin pour les ressources de l’utilisateur. Ensuite, le service redirige la fenêtre de connexion vers l’URL précédemment inscrite et transmet le jeton d’accès. L’application utilise le jeton d’accès pour accéder aux ressources de l’utilisateur.

Vous pouvez utiliser les API de dialogue Office pour gérer ce processus à l’aide d’un flux semblable à celui décrit pour la connexion des utilisateurs. Les seules différences sont les suivantes :

  • Si l’utilisateur n’a pas précédemment accordé à l’application les autorisations dont elle a besoin, il est invité à le faire dans la boîte de dialogue après s’être connecté.
  • Votre code dans la fenêtre de boîte de dialogue envoie le jeton d’accès à la fenêtre hôte en utilisant messageParent pour envoyer le jeton d’accès stringifié ou en stockant le jeton d’accès où la fenêtre hôte peut le récupérer (et en utilisant messageParent pour indiquer à la fenêtre hôte que le jeton est disponible). Le jeton a une limite de temps, mais tant qu’elle n’est pas écoulée, la fenêtre hôte peut l’utiliser pour accéder directement aux ressources de l’utilisateur sans demander d’autre confirmation.

Quelques exemples de compléments d’authentification qui utilisent l’API de boîte de dialogue Office à cet effet sont répertoriés dans les exemples.

Utiliser des bibliothèques d’authentification avec la boîte de dialogue

Étant donné que la boîte de dialogue Office et le volet Office s’exécutent dans des instances d’exécution de navigateur différentes, vous devez utiliser les bibliothèques d’authentification/autorisation différemment de la façon dont elles sont utilisées lorsque l’authentification et l’autorisation ont lieu dans la même fenêtre. Les sections suivantes décrivent les façons dont vous pouvez et ne pouvez pas utiliser ces bibliothèques.

Vous ne pouvez généralement pas utiliser le cache interne de la bibliothèque pour stocker des jetons

En règle générale, les bibliothèques associées à l’authentification fournissent un cache en mémoire pour stocker le jeton d’accès. Si des appels ultérieurs au fournisseur de ressources (par exemple, Google, Microsoft Graph, Facebook, etc.) sont apportés, la bibliothèque vérifie tout d’abord si le jeton dans son cache a expiré. Si celui-ci n’a pas expiré, la bibliothèque renvoie le jeton mis en cache plutôt que d’effectuer un autre aller-retour vers le SJS pour un nouveau jeton. Toutefois, ce modèle n’est pas utilisable dans les compléments Office. Étant donné que le processus de connexion se produit dans le navigateur de la boîte de dialogue Office instance, le cache de jetons se trouve dans ce instance.

Ceci est lié au fait qu’une bibliothèque fournit généralement des méthodes à la fois interactives et «silencieuses» pour obtenir un jeton. Lorsque vous pouvez effectuer les deux appels d’authentification et de données à la ressource dans la même instance de navigateur, votre code appelle la méthode silencieuse pour obtenir un jeton juste avant que votre code n’ajoute le jeton à l’appel de données. La méthode silencieuse vérifie la présence d’un jeton non expiré dans le cache et le renvoie, le cas échéant. Sinon, la méthode silencieuse appelle la méthode interactive qui redirige vers la connexion du STS. Une fois la connexion terminée, la méthode interactive retourne le jeton, mais le met également en cache en mémoire. En revanche, lorsque l’API de boîte de dialogue Office est utilisée, les données appellent la ressource, qui appellent la méthode silencieuse, se trouvent dans l’instance de navigateur du volet des tâches. Le cache de jetons de la bibliothèque n’existe pas dans cette instance.

En guise d’alternative, le navigateur de dialogue de votre complément instance peut appeler directement la méthode interactive de la bibliothèque. Lorsque cette méthode retourne un jeton, votre code doit stocker explicitement le jeton à un endroit où le navigateur du volet Office instance peut le récupérer, par exemple un stockage local ou une base de données côté serveur.

Remarque

Les modifications apportées à la sécurité du navigateur affectent votre stratégie de gestion des jetons.

  • Si votre complément s’exécute dans Office sur le Web dans le Version antérieure de Microsoft Edge (non Chromium) ou le navigateur Safari, la boîte de dialogue et le volet Office ne partagent pas le même stockage local et ne peuvent donc pas être utilisés pour communiquer entre eux.
  • À compter de la version 115 des navigateurs basés sur Chromium, tels que Chrome et Edge, le partitionnement du stockage est testé pour empêcher le suivi intersites par canal latéral spécifique (voir aussi stratégies de navigateur Microsoft Edge). Cela signifie que les données stockées par les API de stockage, telles que le stockage local, ne sont disponibles que pour les contextes ayant la même origine et le même site de niveau supérieur. Pour contourner ce problème, dans votre navigateur, accédez à chrome://flags ou edge://flags, puis définissez l’indicateur De partitionnement de stockage tiers expérimental (#third-party-storage-partitioning) sur Désactivé. Dans la mesure du possible, nous vous recommandons de transmettre des données entre la boîte de dialogue et le volet Office à l’aide des méthodes messageParent et messageChild , comme décrit dans Utiliser l’API de boîte de dialogue Office dans vos compléments Office.

Une autre option consiste à transmettre le jeton au volet des tâches avec la méthodemessageParent. Cette alternative est uniquement possible si la méthode interactive stocke le jeton d’accès à un endroit où votre code peut le lire. Parfois, la méthode interactive d’une bibliothèque est conçue pour stocker le jeton dans une propriété privée d’un objet qui n’est pas accessible à votre code.

Vous ne pouvez généralement pas utiliser l’objet « contexte d’authentification » de la bibliothèque

Il arrive souvent qu’une bibliothèque liée à l’authentification ait une méthode qui récupère un jeton de façon interactive et crée également un objet «contexte d’authentification» que la méthode renvoie. Le jeton est une propriété de l’objet (potentiellement privé et inaccessible directement à partir de votre code). Cet objet possède les méthodes pour recevoir les données de la ressource. Ces méthodes incluent le jeton dans les requêtes HTTP qu’ils font au fournisseur de ressources (par exemple, Google, Microsoft Graph, Facebook, etc.).

Ces objets auth-context et les méthodes qui les créent ne sont pas utilisables dans les compléments Office. Étant donné que la connexion se produit dans le navigateur de la boîte de dialogue Office instance, l’objet doit y être créé. Mais les appels de données à la ressource se trouvent dans l’instance de navigateur du volet des tâches et il n’est pas possible d’utiliser l’objet d’une instance à l’autre. Par exemple, vous ne pouvez pas passer l’objet avec messageParent, car messageParent ne peut passer que des valeurs de chaîne. Un objet JavaScript avec des méthodes ne peut pas être stringified de manière fiable.

Utilisation des bibliothèques avec l’API de boîte de dialogue Office

En plus ou au lieu de, des objets «contexte d’authentification» monolithiques, la plupart des bibliothèques fournissent des API à un niveau d’abstraction inférieur qui permettent à votre code de créer moins d’objets d’assistance monolithiques. Par exemple, MSAL.NET v. 3.x.x dispose d’une API pour construire une URL de connexion et d’une autre API qui construit un objet AuthResult qui contient un jeton d’accès dans une propriété accessible à votre code. Pour consulter des exemples d’MSAL.net dans un complément Office, voir :complément Office Microsoft Graph ASP.NET et complément Outlook Microsoft Graph ASP.NET. Pour obtenir un exemple d’utilisation msal.js dans un complément, voir complément Office Microsoft Graph React.

Pour plus d’informations sur les bibliothèques d’authentification et d’autorisation, voir Microsoft Graph : bibliothèques recommandées et autres services externes : bibliothèques.

Exemples

Voir aussi