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

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 l’ID Microsoft Entra à l’aide de Microsoft Graph. Cet article se concentre principalement sur l’utilisation de l’ID Microsoft Entra pour l’authentification permettant d’accéder à ces informations.

L’ID Microsoft Entra et de nombreux autres fournisseurs de services utilisent OAuth 2.0, une norme ouverte pour l’authentification. Il est essentiel de comprendre OAuth 2.0 lors du traitement de 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 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 l’ID Microsoft Entra.

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.

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

OAuth 2.0 prenant en charge les fournisseurs d’identité n’authentifie 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, veillez à terminer ou à héberger votre application (ou l’exemple d’application). Reprenez ce processus lorsque vous disposez de ces informations.

Lancer le flux d’authentification

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.

L’ID Microsoft Entra, 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 pour héberger le fournisseur d’identité que le client Teams affiche dans une fenêtre contextuelle. Dans l’exemple suivant, la 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-auth/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);
});

microsoftTeams.authentication.authenticate({
    url: window.location.origin + "/tab-auth/simple-start-v1",
    width: 600,
    height: 535,
    successCallback: function (result) {
        getUserProfile(result.accessToken);
    },
    failureCallback: function (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 peut entraîner 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 principal 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 à l’ID Microsoft Entra.

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);
});

microsoftTeams.getContext(function (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: "YOUR_APP_ID_HERE",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab-auth/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
        login_hint: context.loginHint,
    };

    let authorizeEndpoint = "https://login.microsoftonline.com/" + context.tid + "/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 valeur pour la login_hint connexion à Microsoft Entra, ce qui signifie que l’utilisateur peut avoir besoin d’en 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 l’ID Microsoft Entra 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 l’ID Microsoft Entra 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 l’ID Microsoft Entra 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 l’ID Microsoft Entra à window.location.hash l’aide de la fonction d’assistance getHashParameters() . 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 qu’un bloqueur de fenêtres contextuelles a bloqué la fenêtre.

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.

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 :

Voir aussi

• Planifier l’authentification des utilisateurs
• Concevoir votre onglet pour Microsoft Teams
• Authentification en mode silencieux
• Ajouter l’authentification à votre extension de message
• Prise en charge de l’authentification unique pour les bots