Partager via

Vue d’ensemble de l’authentification et de l’autorisation dans les compléments Office

  • Article

Les compléments Office autorisent l’accès anonyme par défaut, mais vous pouvez demander aux utilisateurs de se connecter pour utiliser votre complément avec un compte Microsoft, un compte Microsoft 365 Éducation ou professionnel 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 complément peut également obtenir le consentement de l’utilisateur pour accéder à ses données Microsoft Graph (telles que son profil Microsoft 365, ses fichiers OneDrive et ses données SharePoint) ou à 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.

Ressources clés pour l’authentification et l’autorisation

Cette documentation explique comment créer et configurer des compléments Office pour implémenter correctement l’authentification et l’autorisation. Toutefois, de nombreux concepts et technologies de sécurité mentionnés ne sont pas concernés par cette documentation. Par exemple, les concepts de sécurité généraux tels que les flux OAuth, la mise en cache de jetons ou la gestion des identités ne sont pas expliqués ici. Cette documentation ne documente pas non plus quelque chose de spécifique à Microsoft Azure ou au Plateforme d'identités Microsoft. Nous vous recommandons de consulter les ressources suivantes si vous avez besoin d’informations supplémentaires dans ces domaines.

Scénarios d’authentification unique

L’utilisation de l’authentification unique (SSO) est pratique pour l’utilisateur, car il ne doit se connecter qu’une seule fois à Office. Ils n’ont pas besoin de se connecter séparément à votre complément. L’authentification unique n’est pas prise en charge sur toutes les versions d’Office. Vous devez donc toujours implémenter une autre approche de connexion à l’aide de la Plateforme d'identités Microsoft. Pour plus d’informations sur les versions d’Office prises en charge, consultez Définir les conditions de l’API d’identité

Obtenir l’identité de l’utilisateur via l’authentification unique

Souvent, votre complément a uniquement besoin de l’identité de l’utilisateur. Par exemple, vous pouvez simplement personnaliser votre complément et afficher le nom de l’utilisateur dans le volet des tâches. Vous pouvez également souhaiter qu’un ID unique associe l’utilisateur à ses données dans votre base de données. Pour ce faire, il suffit d’obtenir le jeton d’accès pour l’utilisateur auprès d’Office.

Pour obtenir l’identité de l’utilisateur via l’authentification unique, appelez la méthode getAccessToken. La méthode retourne un jeton d’accès qui est également un jeton d’identité contenant plusieurs revendications, unique à l’utilisateur connecté actuel, y compris preferred_username, name, sub et oid. Pour plus d’informations sur ces propriétés, consultez jetons d’ID de la Plateforme d’identités Microsoft. Pour obtenir un exemple du jeton retourné par getAccessToken, consultez Exemple de jeton d’accès.

Si l’utilisateur n’est pas connecté, Office ouvre une boîte de dialogue et utilise la Plateforme d'identités Microsoft pour demander à l’utilisateur de se connecter. Ensuite, la méthode retournera un jeton d’accès ou génère une erreur si elle ne parvient pas à connecter l’utilisateur.

Dans un scénario où vous devez stocker des données pour l’utilisateur, reportez-vous à jetons d’ID de la plateforme d’identités Microsoft pour plus d’informations sur la façon d’obtenir une valeur à partir du jeton pour identifier l’utilisateur de manière unique. Utilisez cette valeur pour rechercher l’utilisateur dans une table utilisateur ou une base de données utilisateur que vous gérez. Utilisez la base de données pour stocker les informations relatives aux utilisateurs, comme les préférences utilisateur ou l’état du compte utilisateur. Étant donné que vous utilisez l’authentification unique, vos utilisateurs ne se connectent pas séparément à votre complément. Vous n’avez donc pas besoin de stocker un mot de passe pour l’utilisateur.

Avant de commencer à implémenter l’authentification utilisateur avec l’authentification unique, veillez à bien connaître l’article Activer l’authentification unique pour les compléments Office.

Accéder à vos API Web via l’authentification unique

Si votre complément a des API côté serveur qui nécessitent un utilisateur autorisé, appelez la méthode getAccessToken pour obtenir un jeton d’accès. Le jeton d’accès fournit l’accès à votre propre serveur web (configuré via une inscription d’application Microsoft Azure). Lorsque vous appelez des API sur votre serveur web, vous passez également le jeton d’accès pour autoriser l’utilisateur.

Le code suivant montre comment construire une requête HTTPS GET vers l’API de serveur Web du complément pour obtenir des données. Le code s’exécute côté client, par exemple dans un volet Office. Il obtient d’abord le jeton d’accès en appelant getAccessToken. Il construit ensuite un appel AJAX avec l’en-tête et l’URL d’autorisation appropriés pour l’API serveur.

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

Le code suivant montre un exemple de gestionnaire /api/data pour l’appel REST à partir de l’exemple de code précédent. Le code est ASP.NET, code s’exécutant sur un serveur Web. L’attribut [Authorize] nécessite qu’un jeton d’accès valide soit passé à partir du client, ou il retourne une erreur au client.

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

Accès Microsoft Graph via l’authentification unique

Dans certains scénarios, non seulement vous avez besoin de l’identité de l’utilisateur, mais vous devez également accéder aux ressources Microsoft Graph pour le compte de l’utilisateur. Par exemple, vous devrez peut-être envoyer un e-mail ou créer une conversation dans Teams pour le compte de l’utilisateur. Ces actions et bien plus encore peuvent être effectuées via Microsoft Graph. Vous devrez suivre ces étapes :

  1. Obtenez le jeton d’accès pour l’utilisateur actuel via l’authentification unique en appelant getAccessToken. Si l’utilisateur n’est pas connecté, Office ouvre une boîte de dialogue et connecte l’utilisateur avec le Plateforme d'identités Microsoft. Une fois que l’utilisateur se connecte, ou si l’utilisateur est déjà connecté, la méthode retourne un jeton d’accès.
  2. Transmettez le jeton d’accès à votre code côté serveur.
  3. Du côté serveur, utilisez le flux on-Behalf-Of OAuth 2.0 On-Behalf-Of pour échanger le jeton d’accès contre un nouveau jeton d’accès contenant l’identité d’utilisateur déléguée et les autorisations nécessaires pour appeler Microsoft Graph.

Remarque

Pour une sécurité optimale afin d’éviter toute fuite du jeton d’accès, effectuez toujours le flux On-Behalf-Of côté serveur. Appelez Microsoft Graph API à partir de votre serveur, et non du client. Ne retournez pas le jeton d’accès au code côté client.

Avant de commencer à implémenter l’authentification unique pour accéder à Microsoft Graph dans votre complément, veillez à bien connaître les articles suivants.

Vous devez également lire au moins l’un des articles suivants qui vous guideront tout au long de la création d’un complément Office pour utiliser l’authentification unique et accéder à Microsoft Graph. Même si vous ne suivez pas la procédure, celles-ci contiennent des informations utiles sur la façon dont vous implémentez l’authentification unique et le flux On Behalf Of.

Scénarios autres que l’authentification unique

Dans certains scénarios, vous ne souhaiterez peut-être pas utiliser l’authentification unique. Par exemple, vous devrez peut-être vous authentifier à l’aide d’un fournisseur d’identité différent de celui de la plateforme d’identités Microsoft. En outre, l’authentification unique n’est pas prise en charge dans tous les scénarios. Par exemple, les versions antérieures d’Office ne prennent pas en charge l’authentification unique. Dans ce cas, vous devez revenir à un autre système d’authentification pour votre complément.

S’authentifier auprès de la Plateforme d’identités Microsoft.

Votre complément peut connecter des utilisateurs à l’aide de la Plateforme d’identités Microsoft en tant que fournisseur d’authentification. Une fois que vous avez connecté l’utilisateur, vous pouvez utiliser le Plateforme d'identités Microsoft pour autoriser le complément à Microsoft Graph ou à d’autres services gérés par Microsoft. Utilisez cette approche comme autre méthode de connexion lorsque l’authentification unique via Office n’est pas disponible. En outre, il existe des scénarios dans lesquels vous souhaitez que vos utilisateurs se connectent à votre complément séparément, même lorsque l’authentification unique est disponible ; par exemple, si vous souhaitez 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.

Il est important de noter que le Plateforme d'identités Microsoft n’autorise pas l’ouverture de sa page de connexion dans un iframe. Lorsqu’un complément Office s’exécute dans Office sur le Web, le volet Office est un iframe. Cela signifie que vous devrez ouvrir la page de connexion à l’aide d’une boîte de dialogue ouverte avec l’API de boîte de dialogue Office. Cela a une incidence sur la manière dont vous utilisez les bibliothèques d’aide à l’authentification. Pour plus d’informations, consultez Authentification avec l’API de boîte de dialogue Office.

Pour plus d’informations sur l’implémentation de l’authentification avec la plateforme d’identités Microsoft, consultez lavue d’ensemble de la Plateforme d’identités Microsoft (v2.0). La documentation contient de nombreux didacticiels et guides, ainsi que des liens vers des exemples et des bibliothèques pertinents. Comme expliqué dans Authentification avec l’API de boîte de dialogue Office, vous devrez peut-être ajuster le code dans les exemples pour qu’il s’exécute dans la boîte de dialogue Office.

Accès à Microsoft Graph sans authentification unique

Vous pouvez obtenir l’autorisation données Microsoft Graph pour votre complément en obtenant un jeton d’accès pour Microsoft Graph à partir de la plateforme d’identités Microsoft. Vous pouvez le faire sans compter sur l’authentification unique via Office (ou si l’authentification unique a échoué ou n’est pas prise en charge). Pour plus d’informations sur la manière de procéder, consultez Accès à Microsoft Graph sans authentification unique qui contient davantage de détails et des liens vers des exemples.

Accès à des sources de données non-Microsoft

Les services en ligne populaires, dont Google, Facebook, LinkedIn, SalesForce et GitHub, permettent aux développeurs d’accorder aux utilisateurs l’accès à leurs comptes dans d’autres applications. Vous avez ainsi la possibilité d’inclure ces services dans votre complément Office. Pour obtenir une vue d’ensemble des méthodes que votre complément peut utiliser, voir Autoriser des services externes dans votre complément Office.

Importante

Avant de commencer le codage, déterminez si la source de données autorise l’ouverture de sa page de connexion dans un iframe. Lorsqu’un complément Office s’exécute dans Office sur le Web, le volet Office est un iframe. Si la source de données n’autorise pas l’ouverture de sa page de connexion dans un iframe, vous devez ouvrir la page de connexion dans une boîte de dialogue ouverte avec l’API de boîte de dialogue Office. Pour plus d’informations, consultez Authentification avec l’API de boîte de dialogue Office.

Voir aussi