Configurer l’authentification d’un fournisseur d’identité OAuth tiers

  • Article

Remarque

Pour que l’authentification fonctionne pour votre onglet sur les clients mobiles, vérifiez que vous utilisez la version 1.4.1 ou ultérieure de la bibliothèque de client JavaScript Microsoft Teams (TeamsJS).

Votre application Microsoft Teams peut avoir besoin d’interagir avec différents services, tels que Facebook, Twitter et Teams. La plupart de ces services nécessitent une authentification et une autorisation pour l’accès. Teams stocke les informations de profil utilisateur dans Microsoft Entra ID à l’aide de Microsoft Graph. Cet article se concentre principalement sur l’utilisation de l’ID Microsoft Entra pour l’authentification afin d’accéder à ces informations.

OAuth 2.0, une norme ouverte pour l’authentification, est utilisé par Microsoft Entra ID et de nombreux autres fournisseurs de services. La compréhension d’OAuth 2.0 est essentielle lorsque vous traitez l’authentification dans Teams et l’ID Microsoft Entra. Les exemples fournis utilisent le flux d’octroi implicite OAuth 2.0, qui récupère les informations de profil de l’utilisateur à partir de Microsoft Entra ID et de Microsoft Graph.

Le code de l’article provient de l’exemple d’application Teams Exemple d’authentification Microsoft Teams (Nœud). Il contient un onglet statique qui demande un jeton d’accès pour Microsoft Graph et affiche les informations de profil de base de l’utilisateur actuel à partir de Microsoft Entra’ID.

Pour obtenir une vue d’ensemble du flux d’authentification pour les onglets, consultez Flux d’authentification dans les onglets.

Le flux d’authentification dans les onglets diffère du flux d’authentification dans les bots.

Remarque

Cette rubrique reflète la version 2.0.x de la bibliothèque de client JavaScript Microsoft Teams (TeamsJS). Si vous utilisez une version antérieure, reportez-vous à la vue d’ensemble de la bibliothèque TeamsJS pour obtenir des conseils sur les différences entre la dernière version de TeamsJS et les versions antérieures.

Configurer votre application pour utiliser Microsoft Entra ID comme fournisseur d’identité

Les fournisseurs d’identité prenant en charge OAuth 2.0 n’authentifient pas les demandes provenant d’applications non inscrites. Par conséquent, il est essentiel d’inscrire vos applications à l’avance. Pour inscrire une application avec l’ID Microsoft Entra, procédez comme suit :

  1. Ouvrez le portail d’inscription d’application.

  2. Sélectionnez votre application pour afficher ses propriétés, ou sélectionnez le bouton « Nouvelle inscription ». Recherchez la section URI de redirection pour l’application.

  3. Sélectionnez Web dans le menu déroulant et mettez à jour l’URL vers votre point de terminaison d’authentification. Dans les exemples d’applications TypeScript/Node.js et C# disponibles sur GitHub, les URL de redirection suivent un modèle similaire :

    URL de redirection : https://<hostname>/bot-auth/simple-start

Remplacez par <hostname> votre hôte réel. Cet hôte peut être un site d’hébergement dédié, tel qu’Azure, Glitch, ou un tunnel ngrok pour localhost sur votre machine de développement, tel que abcd1234.ngrok.io. Si vous ne disposez pas de ces informations, vérifiez que vous avez terminé ou hébergé votre application (ou l’exemple d’application). Reprenez ce processus lorsque vous disposez de ces informations.

Remarque

Vous pouvez choisir n’importe quel fournisseur OAuth tiers, tel que LinkedIn, Google, etc. Le processus d’activation de l’authentification pour ces fournisseurs est similaire à l’utilisation de l’ID Microsoft Entra en tant que fournisseur OAuth tiers. Pour plus d’informations sur l’utilisation d’un fournisseur OAuth tiers, visitez le site web du fournisseur en question.

Lancer le flux d’authentification

Remarque

Si le partitionnement de stockage tiers expérimental est activé, l’authentification tierce échoue. L’application demande l’authentification à plusieurs reprises, car les valeurs ne sont pas stockées localement.

Déclenchez le flux d’authentification par une action utilisateur. Évitez d’ouvrir automatiquement la fenêtre contextuelle d’authentification, car cela est susceptible de déclencher le bloqueur de fenêtres contextuelles du navigateur et dérouter l’utilisateur.

Ajoutez un bouton à votre page de configuration ou de contenu pour permettre à l’utilisateur de se connecter si nécessaire. Vous pouvez le faire dans l’onglet page de configuration ou dans n’importe quelle page de contenu.

Microsoft Entra’ID, comme la plupart des fournisseurs d’identité, n’autorise pas son contenu à être placé dans un iframe. Cela signifie que vous devez ajouter une page contextuelle pour héberger le fournisseur d’identité. Dans l’exemple suivant, cette page est /tab-auth/simple-start. Utilisez la authentication.authenticate() fonction de la bibliothèque TeamsJS pour lancer cette page lorsque le bouton est sélectionné.

import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
    url: window.location.origin + "/tab/simple-start-v2",
    width: 600,
    height: 535})
.then((result) => {
    console.log("Login succeeded: " + result);
    let data = localStorage.getItem(result);
    localStorage.removeItem(result);
    let tokenResult = JSON.parse(data);
    showIdTokenAndClaims(tokenResult.idToken);
    getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
    console.log("Login failed: " + reason);
    handleAuthError(reason);
});

Notes

  • L’URL que vous transmettez à authenticate() est la page de démarrage du flux d’authentification. Dans cet exemple, il s’agit de /tab-auth/simple-start. Cela doit correspondre à ce que vous avez inscrit dans le portail d’inscription des applications Microsoft Entra.

  • Le flux d’authentification doit commencer sur une page qui se trouve sur votre domaine. Ce domaine doit également être répertorié dans la section validDomains du manifeste. L’échec de l’opération entraîne une fenêtre contextuelle vide.

  • Si vous ne parvenez pas à utiliser authenticate(), la fenêtre contextuelle risque de ne pas se fermer à la fin du processus de connexion, ce qui entraîne un problème.

Accédez à la page d’autorisation à partir de votre page contextuelle

Lorsque votre page contextuelle (/tab-auth/simple-start) s’affiche, le code suivant est exécuté. L’objectif main de la page est de rediriger vers votre fournisseur d’identité afin que l’utilisateur puisse se connecter. Cette redirection peut être effectuée côté serveur à l’aide de HTTP 302, mais dans ce cas, elle est effectuée côté client à l’aide d’un appel à window.location.assign(). Cela permet app.getContext() également d’être utilisé pour récupérer des informations d’indication, qui peuvent être passées à Microsoft Entra’ID.

app.getContext().then((context) => {
    // Generate random state string and store it, so we can verify it in the callback
    let state = _guid(); // _guid() is a helper function in the sample
    localStorage.setItem("simple.state", state);
    localStorage.removeItem("simple.error");

    // Go to the Azure AD authorization endpoint
    let queryParams = {
        client_id: "{{appId}}",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
        // is used as hinting information
        login_hint: context.user.loginHint,
    };

    let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
    window.location.assign(authorizeEndpoint);
});

Une fois l’autorisation terminée, l’utilisateur est redirigé vers la page de rappel que vous avez spécifiée pour votre application à /tab-auth/simple-end.

Notes

  • Consultez obtenir des informations de contexte utilisateur pour obtenir de l’aide sur la création de demandes d’authentification et d’URL. Par exemple, vous pouvez utiliser le nom de connexion de l’utilisateur comme login_hint valeur pour Microsoft Entra connexion, ce qui signifie que l’utilisateur peut avoir besoin de taper moins. N’oubliez pas que vous ne devez pas utiliser ce contexte directement comme preuve d’identité, car un attaquant peut charger votre page dans un navigateur malveillant et lui fournir les informations souhaitées.
  • Bien que le contexte de l’onglet fournisse des informations utiles concernant l’utilisateur, n’utilisez pas ces informations pour authentifier l’utilisateur, que vous les obteniez en tant que paramètres d’URL de votre URL de contenu d’onglet ou en appelant la app.getContext() fonction dans la bibliothèque de client JavaScript Microsoft Teams (TeamsJS). Un acteur malveillant pourrait appeler l’URL de contenu de votre onglet avec ses propres paramètres, et une page web empruntant l’identité de Microsoft Teams pourrait charger l’URL de contenu de votre onglet dans une iFrame et retourner ses propres données à la fonction getContext(). Vous devez traiter les informations relatives à l’identité dans le contexte de l’onglet simplement comme des indicateurs et les valider avant de les utiliser.
  • Le paramètre state est utilisé pour confirmer que le service appelant l’URI de rappel est le service que vous avez appelé. Si le state paramètre du rappel ne correspond pas au paramètre que vous avez envoyé pendant l’appel, l’appel de retour n’est pas vérifié et doit être arrêté.
  • Il n’est pas nécessaire d’inclure le domaine du fournisseur d’identité dans la validDomains liste dans le fichier manifest.json de l’application.

Page de rappel

Dans la dernière section, vous avez appelé le service d’autorisation Microsoft Entra et transmis des informations sur l’utilisateur et l’application afin que Microsoft Entra ID puisse présenter à l’utilisateur sa propre expérience d’autorisation monolithique. Votre application n’a aucun contrôle sur ce qui se passe dans cette expérience. Tout ce qu’il sait, c’est ce qui est retourné quand Microsoft Entra ID appelle la page de rappel que vous avez fournie (/tab-auth/simple-end).

Dans cette page, vous devez déterminer la réussite ou l’échec en fonction des informations retournées par Microsoft Entra ID et appelez authentication.notifySuccess() ou authentication.notifyFailure(). Si la connexion a réussi, vous avez accès aux ressources de service.

// Split the key-value pairs passed from Azure AD
// getHashParameters is a helper function that parses the arguments sent
// to the callback URL by Azure AD after the authorization call
let hashParams = getHashParameters();
if (hashParams["error"]) {
    // Authentication/authorization failed
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
} else if (hashParams["access_token"]) {
    // Get the stored state parameter and compare with incoming state
    let expectedState = localStorage.getItem("simple.state");
    if (expectedState !== hashParams["state"]) {
        // State does not match, report error
        localStorage.setItem("simple.error", JSON.stringify(hashParams));
        authentication.notifyFailure("StateDoesNotMatch");
    } else {
        // Success -- return token information to the parent page.
        // Use localStorage to avoid passing the token via notifySuccess; instead we send the item key.
        let key = "simple.result";
        localStorage.setItem(key, JSON.stringify({
            idToken: hashParams["id_token"],
            accessToken: hashParams["access_token"],
            tokenType: hashParams["token_type"],
            expiresIn: hashParams["expires_in"]
        }));
        authentication.notifySuccess(key);
    }
} else {
    // Unexpected condition: hash does not contain error or access_token parameter
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
    authentication.notifyFailure("UnexpectedFailure");
}

Ce code analyse les paires clé-valeur reçues de Microsoft Entra’ID à window.location.hash l’aide de la fonction d’assistancegetHashParameters(). S’il trouve une access_token, et que la valeur state est identique à celle fournie au début du flux d’authentification, elle retourne le jeton d’accès à l’onglet en appelant notifySuccess(); sinon, il signale une erreur avec notifyFailure().

Notes

NotifyFailure() présente les raisons d’échec prédéfinies suivantes :

  • CancelledByUser l’utilisateur a fermé la fenêtre contextuelle avant de terminer le flux d’authentification.

    Remarque

    Nous vous recommandons de ne pas utiliser same-origin les valeurs ou same-origin-allow-popups pour Cross-Origin-Opener-Policy l’en-tête de réponse sur les pages de connexion, car cela interrompt la connexion à la fenêtre parente et provoque le retour prématuré de l’appel d’API d’authentification avec une CancelledByUser erreur.

  • FailedToOpenWindow Impossible d’ouvrir la fenêtre contextuelle. Lors de l’exécution de Microsoft Teams dans un navigateur, cela signifie généralement que la fenêtre a été bloquée par un bloqueur de fenêtres contextuelles.

En cas de réussite, vous pouvez actualiser ou recharger la page et afficher le contenu pertinent pour l’utilisateur authentifié. Si l’authentification échoue, un message d’erreur s’affiche.

Votre application peut définir son propre cookie de session afin que l’utilisateur n’ait pas besoin de se reconnecter lorsqu’il revient à votre onglet sur l’appareil actuel.

Remarque

  • Chrome 80, dont la publication est prévue début 2020, introduit de nouvelles valeurs de cookie et impose des stratégies de cookie par défaut. Il est recommandé de définir l’utilisation prévue pour vos cookies plutôt que de vous appuyer sur le comportement par défaut du navigateur. ConsultezAttribut de cookie SameSite (mise à jour 2020).
  • Pour obtenir le jeton approprié pour les utilisateurs invités et gratuits de Microsoft Teams, vérifiez que vos applications utilisent le point de terminaison https://login.microsoftonline.com/**{tenantId}**spécifique au locataire . Vous pouvez acquérir le tenantId à partir du contexte de message ou d’onglet du bot. Si vos applications utilisent https://login.microsoftonline.com/common, les utilisateurs peuvent recevoir des jetons incorrects, ce qui les amène à se connecter au locataire « d’origine » plutôt qu’au locataire auquel ils sont actuellement connectés.

Pour plus d’informations sur l’authentification unique (SSO), consultez l’article Authentification silencieuse.

Exemple de code

Exemple de code montrant le processus d’authentification par onglet à l’aide de l’ID Microsoft Entra :

Exemple de nom Description .NET Node.js Manifeste
Onglet SSO Cet exemple d’application montre Microsoft Entra’authentification unique pour les onglets dans Teams. View Affichage,
Kit de ressources Teams		 N/A
Authentification unique Tab, Bot et Message Extension (ME) Cet exemple montre l’authentification unique pour Tab, Bot et ME- search, action, link unfurl. View View View

Voir aussi