Implémenter l’authentification unique (SSO) pour les compléments Office

  • 11 minutes

L’authentification unique (SSO) permet à votre complément d’authentifier des utilisateurs. À l’aide de cette méthode, votre complément peut authentifier l’utilisateur pour récupérer des informations d’identité ou pour les obtenir à partir d’un autre point de terminaison sécurisé tel que Microsoft Graph. Pour ce faire, votre complément doit appeler une API web côté serveur inscrite avec l’ID Microsoft Entra.

Dans cette partie, vous allez découvrir le fonctionnement de l’authentification avec les compléments Office et l’utilisation de l’authentification unique pour vos compléments Office.

Authentification et autorisation dans les compléments Office

Les applications web et les compléments Office autorisent l’accès anonyme par défaut, mais vous pouvez demander aux utilisateurs de s’authentifier avec une connexion. Par exemple, vous pouvez exiger que vos utilisateurs soient connectés avec un compte Microsoft, un compte Microsoft 365 Education ou un compte de travail, ou un autre compte commun. Cette tâche est appelée authentification des utilisateurs, car elle permet au complément de déterminer l’identité de l’utilisateur.

Votre add-in peut également obtenir le consentement de l'utilisateur pour accéder à ses données Microsoft Graphique (telles que son profil Microsoft 365, ses fichiers OneDrive et ses données SharePoint) ou à des données d'autres sources externes telles que Google, Facebook, LinkedIn, SalesForce et GitHub. Cette tâche est appelée autorisation de complément (ou d’application), car c’est le complément qui est autorisé, et non l’utilisateur.

Vous avez le choix entre deux méthodes pour effectuer l’authentification et l’autorisation.

  • Authentification unique Office (SSO) : système qui permet à la connexion de l’utilisateur à Office de fonctionner également comme une connexion au complément. Si vous le souhaitez, le complément peut également utiliser les informations d’identification Office de l’utilisateur pour autoriser le complément à accéder à Microsoft Graph.
  • Authentification et autorisation des applications web avec l’ID Microsoft Entra : il s’agit de la façon dont les compléments Office (et d’autres applications web) authentifient les utilisateurs et les applications autorisées avant qu’il n’y ait un système d’authentification unique Office, et il est toujours utilisé dans les scénarios où l’authentification unique Office ne peut pas l’être. Il existe également des scénarios dans lesquels vous voulez que vos utilisateurs se connectent à votre complément séparément, même lorsque l’authentification unique est disponible. Par exemple, si vous voulez qu’ils aient la possibilité de se connecter au complément avec un ID différent de celui avec lequel ils sont actuellement connectés à Office.

Compléments Office et authentification unique

Microsoft a ajouté la prise en charge de l’authentification unique aux compléments Office en 2020. Cette fonctionnalité réduit la fréquence à laquelle un utilisateur est invité à se connecter à des services tiers.

La prise en charge de l’authentification unique Office est implémentée en combinaison avec le code de vos compléments personnalisés, la prise en charge de l’authentification unique dans le KIT de développement logiciel (SDK) JavaScript du runtime Office et l’ID Microsoft Entra. Pour prendre en charge l’authentification unique, un complément Office doit avoir une inscription d’application Microsoft Entra correspondante. L’inscription de cette application définit les autorisations que le complément prend en charge et permet aux applications du d’intervenir pour le compte de l’utilisateur.

En utilisant cette prise en charge de l’authentification unique, les compléments peuvent demander les informations de profil de l’utilisateur ou des informations de Microsoft Graph.

Les utilisateurs peuvent approuver les compléments Office pour eux-mêmes afin d’autoriser le complément à obtenir leurs informations de profil. Le complément peut ensuite utiliser ces informations de profil fournies par l’ID Microsoft Entra et Office comme ID de l’utilisateur actuellement connecté.

Les administrateurs peuvent donner leur accord au nom de l’ensemble de votre organisation via un processus de déploiement centralisé, de sorte que chaque utilisateur n’a pas à passer par un processus d’accord individuel.

L’authentification unique de complément Office prend en charge les deux types de comptes pris en charge par Microsoft : comptes professionnels et scolaires (comptes Microsoft Entra) et comptes Microsoft (MSA).

L'authentification unique des compléments Office est prise en charge dans les clients web Office et ces clients de bureau :

  • Windows v16.0.12215.20006 (ou ultérieure)
  • macOS v16.32.19102902 (ou ultérieure)

Comprendre le flux d’authentification unique

Voyons comment fonctionne le processus d’authentification unique à l’exécution.

Diagramme de vue d’ensemble du flux de processus d’exécution de l’authentification unique.

  1. Dans le complément, JavaScript appelle une nouvelle API Office.js getAccessToken(). Cette méthode indique à l’application cliente Office qu’elle doit obtenir un jeton d’accès au complément.
  2. Si l’utilisateur n’est pas connecté, l’application cliente Office ouvre une fenêtre contextuelle pour qu’il se connecte.
  3. L’utilisateur est invité à donner son consentement s’il s’agit de la première fois que l’utilisateur actuel utilise votre complément.
  4. L’application cliente Office demande le jeton de complément au point de terminaison Azure AD v2.0 pour l’utilisateur actuel.
  5. L’ID Microsoft Entra envoie le jeton de complément à l’application cliente Office.
  6. L’application cliente Office envoie le jeton de complément au complément dans le cadre de l’objet de résultat renvoyé par l’appelgetAccessToken().
  7. JavaScript dans le complément peut analyser le jeton et extraire les informations dont il a besoin.
  8. Optionnellement, le complément peut envoyer une requête HTTP à son côté serveur pour plus de données sur l’utilisateur, telles que les préférences de l’utilisateur. Alternativement, le jeton d’accès lui-même pourrait être envoyé au contrôle serveur pour analyse et validation.

Implémentation de l’authentification unique dans des compléments Office

Pour qu’un complément Office prenne en charge l’authentification unique, vous devez faire ces choses :

  1. Inscrire une application Microsoft Entra
  2. Associer un complément Office à l’application Microsoft Entra
  3. Implémenter un code côté client pour obtenir un jeton d’accès à partir du client Office d’hébergement

Nous allons étudier chacune de ces choses.

Inscrire une application Microsoft Entra

La première étape consiste à inscrire une application Microsoft Entra pour le complément.

Les applications Microsoft Entra utilisées pour prendre en charge l’authentification unique dans les compléments Office ont de nombreuses exigences. Par exemple, elles doivent être des applications multitenant, exposer les autorisations access_as_user et approuver à toutes les applications clientes Office qui appellent l’application.

Les outils de développement fournis par Microsoft incluent l’utilitaire configure-sso qui inscrit l’application Microsoft Entra avec tous les paramètres requis pendant votre processus de développement.

Une autre unité de ce module explique en détail comment créer une application Microsoft Entra à utiliser par un complément Office qui implémente l’authentification unique.

Associer le complément Office à l’application Microsoft Entra

Une fois l’application Microsoft Entra créée, elle doit être associée au complément Office. Cette opération est effectuée dans le fichier manifest.xml de la section <WebApplicationInfo> :

<WebApplicationInfo>
  <Id>056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Id>
  <Resource>api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Resource>
  <Scopes>
    <Scope>User.Read</Scope>
    <Scope>profile</Scope>
    <Scope>openid</Scope>
  </Scopes>
</WebApplicationInfo>

Trois parties de cette section doivent être mises à jour pour l’application :

  • ID : IL s’agit de l’ID client de l’application Microsoft Entra inscrite.
  • Ressource : il s’agit de l’URL du complément, qui est la même chose que l’URI utilisé lors de l’inscription du complément dans l’ID Microsoft Entra. La partie domaine de l’URI doit correspondre au domaine utilisé dans l’une des URL utilisées dans la section <Resources> du fichier manifest.xml du complément.
  • Étendues : il s’agit des autorisations, ou étendues, dont le complément a besoin à partir de l’ID Microsoft Entra.

Importante

Les valeurs profile et openiddes autorisations OpenID sont toujours nécessaires pour votre complément. Il peut s’agir des seules autorisations nécessaires, sauf si votre complément doit appeler un autre service, tel que Microsoft Graph.

De plus, certaines bibliothèques que votre complément utilise peuvent nécessiter des autorisations supplémentaires. Par exemple, MSAL.NET nécessite l’autorisation offline_access.

Implémenter un code côté client

Pour terminer, un complément doit implémenter un code côté client pour implémenter et prendre en charge l'authentification unique. Si vous utilisez les outils fournis par Microsoft, votre projet de complément inclut plus souvent le code réutilisable pour prendre en charge l’authentification unique. Cela est vrai si vous utilisez soit les Outils de développement Microsoft Office pour Visual Studio 2019 pour un complément ASP.NET ou le Générateur Yeoman pour Microsoft Office pour le code VS d’un complément basé sur Node.js.

La méthode api [OfficeRuntime.Auth.getAccessToken()](/javascript/api/office-runtime/officeruntime.auth) est utilisée par le complément pour demander un jeton d’accès auprès du client Office d’hébergement.

Le client Office demande un jeton d’accès à l’ID Microsoft Entra à l’aide de l’application précédemment inscrite avec l’ID Microsoft Entra.

Le jeton retourné par l’ID Microsoft Entra peut être utilisé pour identifier l’utilisateur, mais peut également être utilisé comme jeton de démarrage pour obtenir un jeton d’accès qui peut être utilisé pour envoyer des demandes à Microsoft Graph (en supposant que le complément et l’utilisateur ont reçu des autorisations Microsoft Graph spécifiques).

Utiliser le jeton d’accès pour identifier l’utilisateur

Votre complément peut avoir besoin d’identifier l’utilisateur. Dans ce cas, votre complément fournit généralement ce jeton à votre propre système principal qui utilise le jeton pour stocker les préférences d’un utilisateur ou d’autres informations spécifiques de l’utilisateur actuellement connecté.

Dans ce scénario, le jeton renvoyé inclut quelques propriétés qui peuvent être utiles à votre application :

  • Nom : Nom d'affichage de l’utilisateur
  • preferred_username : UPN, ou adresse de l’utilisateur
  • Old : ID d’objet unique de l’utilisateur : cette valeur doit être utilisée pour identifier l’utilisateur dans votre système principal, car les propriétés Nom et preferred_username peuvent être modifiées par l’utilisateur ou un administrateur.
  • Tid : ID de client unique auquel appartient l’utilisateur

Utiliser le jeton d’accès dans votre propre API

Si vous utilisez le jeton d’accès dans votre propre API, vous devez implémenter les meilleures pratiques acceptées lors du transfert du jeton reçu d’Office. Cela inclut la validation du jeton pour s’assurer qu’il a été créé par l’ID Microsoft Entra, qu’il provient de l’autorité attendue, que le complément est l’audience prévue du jeton, que le jeton n’a pas expiré et que l’étendue est définie sur access_as_user.

Utiliser le jeton d’accès pour accéder à Microsoft Graph.

Dans le scénario où votre complément doit accéder à Microsoft Graph, votre code peut utiliser le jeton fourni par Office pour votre complément et démarrer le flux OAuth2 (OBO). Lorsque le jeton est utilisé de cette façon, il est appelé « jeton bootstrap », car il est utilisé uniquement pour obtenir un jeton d’accès qui peut être utilisé pour appeler Microsoft Graph.