Étendre l’application d’onglet avec des autorisations et des étendues Microsoft Graph

Vous pouvez étendre votre application d’onglet à l’aide de Microsoft Graph pour accorder des autorisations utilisateur supplémentaires, telles que l’affichage du profil utilisateur de l’application, la lecture du courrier, etc. Votre application doit demander des étendues d’autorisation spécifiques pour obtenir les jetons d’accès avec le consentement de l’utilisateur de l’application.

Les étendues de graphique, telles que User.Read ou Mail.Read, indiquent à quoi votre application peut accéder à partir d’un compte d’utilisateur Teams. Vous devez préciser vos périmètres dans la demande d'autorisation. Cet article vous guide tout au long des étapes de configuration des autorisations et des étendues Microsoft Graph pour votre application d’onglet Teams.

Configurer les autorisations d’API dans Microsoft Entra ID

Vous pouvez configurer des étendues de graphique supplémentaires dans Microsoft Entra ID pour votre application. Il s'agit d'autorisations déléguées, qui sont utilisées par les applications nécessitant un accès connecté. Un utilisateur ou un administrateur d’application connecté doit initialement donner son consentement. Par la suite, votre application Tab peut donner son consentement au nom de l’utilisateur connecté lorsqu’elle appelle Microsoft Graph.

Nous vous recommandons d’utiliser des autorisations déléguées pour l’utilisateur connecté. Si votre application n’a pas besoin d’un utilisateur connecté, envisagez d’utiliser les autorisations d’application, également appelées scénario d’accès à l’application uniquement. Seuls les administrateurs peuvent accorder leur consentement pour les autorisations d’application. Pour plus d’informations, voir Autorisations d’application.

Pour configurer les autorisations d'API

1. Ouvrez l'application que vous avez enregistrée dans le portail Azure.

2. Sélectionnez Gérer les>autorisations d’API dans le volet gauche.

   

   La page des autorisations d'API s'affiche.

3. Sélectionnez + Ajouter une autorisation pour ajouter des autorisations d’API Microsoft Graph.

   

   La page Demander les autorisations de l'API s'affiche.

4. Sélectionnez Microsoft Graph.

   

   Les options des autorisations de graphique s'affichent.

5. Sélectionnez Autorisations déléguées ou Autorisations d’application pour afficher la liste des autorisations déléguées ou des autorisations d’application, respectivement.

   

6. Sélectionnez les autorisations pertinentes pour votre application, puis sélectionnez Ajouter des autorisations.

   

   Vous pouvez également entrer le nom de l'autorisation dans la zone de recherche pour le trouver.

   Un message apparaît sur le navigateur indiquant que les autorisations ont été mises à jour.

   

   Les autorisations ajoutées sont affichées dans la page des autorisations de l'API.

   

   Vous avez maintenant configuré votre application avec les autorisations Microsoft Graph.

Configurer l'authentification pour différentes plates-formes

Selon la plateforme ou l’appareil sur lequel vous souhaitez cibler votre application, une configuration supplémentaire peut être nécessaire, comme des URI de redirection, des paramètres d’authentification spécifiques ou des détails spécifiques à la plateforme.

Vous pouvez configurer l'authentification pour plusieurs plates-formes tant que l'URL est unique.

Pour configurer l'authentification pour une plate-forme

1. Ouvrez l'application que vous avez enregistrée dans le portail Azure.

2. Sélectionnez Gestion>Authentification du volet de gauche.

   

   La page Configurations de la plate-forme s'affiche.

3. Sélectionnez + Ajouter une plateforme.

   

   La page Configurer les plateformes s’affiche.

4. Sélectionnez la plate-forme que vous souhaitez configurer pour votre application d'onglet. Vous pouvez choisir le type de plate-forme à partir d’une application Web ou d’une seule page.

   

   Vous pouvez configurer plusieurs plates-formes pour un type de plate-forme particulier. Assurez-vous que l'URI de redirection est unique pour chaque plate-forme que vous configurez.

   La page Web de configuration s'affiche.

   Remarque

   Les configurations sont différentes en fonction de la plateforme que vous sélectionnez.

5. Entrez les détails de configuration de la plate-forme.

   

   1. Entrez l'URI de redirection. L'URI doit être unique.
   2. Entrez l'URL de déconnexion du canal frontal.
   3. Sélectionnez les jetons que vous souhaitez que Microsoft Entra ID envoie pour votre application.

6. Sélectionnez Configurer.

   La plateforme est configurée et affichée dans la page Configurations de la plateforme.

Acquérir un jeton d'accès pour MS Graph

Vous devez acquérir un jeton d’accès pour Microsoft Graph. Vous pouvez le faire à l’aide du flux Microsoft Entra pour le compte de (OBO).

L’implémentation actuelle de l’authentification unique (SSO) est limitée aux autorisations au niveau de l’utilisateur, qui ne sont pas utilisables pour effectuer des appels Graph. Pour obtenir les autorisations et les étendues nécessaires pour effectuer un appel Graph, les applications d’authentification unique doivent implémenter un service web personnalisé pour échanger le jeton reçu de la bibliothèque JavaScript Teams contre un jeton qui inclut les étendues nécessaires. Vous pouvez utiliser Microsoft Authentication Library (MSAL) pour récupérer le jeton du côté client.

Une fois que vous avez configuré les autorisations Graph dans Microsoft Entra ID, vous devez obtenir l’ID de jeton à partir du client Teams, puis l’échanger avec le jeton côté serveur.

Obtenir l’ID de jeton à partir du client Teams

Voici un exemple d’obtention de l’ID de jeton à partir du client Teams :

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

Échanger l’ID de jeton avec le jeton côté serveur

Voici un exemple de flux OBO pour extraire le jeton d’accès à partir du client Teams à l’aide de MSAL :

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

Si vous devez accéder aux données Microsoft Graph, configurez votre code côté serveur pour :

1. Validez le jeton d'accès. Pour plus d’informations, voir Valider le jeton d’accès.
2. Lancez le flux OBO OAuth 2.0 avec un appel à la plate-forme d'identité Microsoft qui inclut le jeton d'accès, certaines métadonnées sur l'utilisateur et les informations d'identification de l'application d'onglet (son ID d'application et son secret client). La plateforme d’identités Microsoft renvoie un nouveau jeton d’accès qui peut être utilisé pour accéder à Microsoft Graph.
3. Obtenir des données à partir de Microsoft Graph en utilisant le nouveau jeton.
4. Utilisez la sérialisation du cache de jetons dans MSAL.NET pour mettre en cache le nouveau jeton d’accès pour plusieurs, si nécessaire.

Obtenir le consentement

Vous pouvez obtenir le consentement de l’application pour les autorisations Graph globalement auprès de l’administrateur, ou individuellement par utilisateur.

De l’administrateur

Un moyen simple de donner son consentement au nom d’une organisation consiste à obtenir le consentement de l’administrateur.

De l’utilisateur

Lorsque vous demandez un consentement utilisateur supplémentaire à l’aide de la fonctionnalité d’authentification de la bibliothèque cliente JavaScript (TeamsJS) de Microsoft Teams, gardez à l’esprit les considérations suivantes :

Pour implémenter l’authentification SSO dans un onglet personnel, procédez comme suit :

1. Le jeton récupéré à l’aide getAuthToken() doit être échangé côté serveur à l’aide du flux OBO Microsoft Entra pour accéder à ces autres API Graph. Assurez-vous d’utiliser le point de terminaison de Microsoft Entra v2 pour cet échange.

2. Lorsque vous essayez d’exécuter l’échange de jetons pour un utilisateur pour la première fois, si Microsoft Entra refuse d’échanger des jetons, cela peut être dû au fait que l’utilisateur n’a pas consenti à accorder à votre application l’autorisation sur les données de l’utilisateur. Dans ce cas, votre échange échoue avec l’erreur invalid_grant ou interaction_required . Parmi les exemples d’erreurs invalid_grant , citons le consentement requis ou auth_code, l’assertion, ou le jeton d’actualisation expiré, révoqué, incorrect ou absent. Par exemple, interaction_required l’authentification multifacteur ou l’inscription d’un appareil d’entreprise est requise.

3. Si l’échange échoue en raison des erreurs ouinteraction_required, vous devez inviter l’utilisateur à donner son invalid_grant consentement. Étant donné que l’interaction utilisateur ne peut se produire qu’à partir du client, votre serveur doit renvoyer une indication à votre application cliente que le consentement est requis. Vous pouvez ensuite utiliser l’interface utilisateur pour demander à l’utilisateur de l’application d’accorder un autre consentement. L’interface utilisateur doit inclure un bouton qui déclenche une boîte de dialogue de consentement de Microsoft Entra.

4. Pour demander à l’utilisateur de donner son consentement pour que votre application accède à ses données, vous devez inclure la prompt=consent propriété dans votre query-string-parameter à Microsoft Entra ID.

   • Au lieu de ?scope={scopes}, utilisez ?prompt=consent&scope={scopes}
   • Assurez-vous que la {scopes} propriété inclut toutes les étendues que vous invitez l’utilisateur. Par exemple : Mail.Read ou User.Read.

   Pour gérer le consentement incrémentiel pour l’application Tab, consultez Consentement utilisateur incrémentiel et dynamique.

5. Une fois que l’utilisateur de l’application a accordé plus d’autorisations, réessayez le flux OBO pour accéder à d’autres API Graph. Pour plus d’informations, voir l’exemple de code d’authentification SSO de l’onglet personnel Teams .

Condition de concurrence lors de l’exécution d’un appel OBO après une exception d’octroi non valide

Si un utilisateur n’a pas accordé de consentement à l’application Microsoft Entra pour ces étendues, votre appel OBO échoue avec invalid_grant ou interaction_required erreur. Cette erreur vous informe que vous devez inviter l’utilisateur à donner son consentement.

Lorsque l’utilisateur a donné son consentement et que vous essayez d’effectuer un appel OBO immédiatement, il existe parfois une condition de concurrence entre Microsoft Entra ID propageant ce consentement et la demande OBO en cours. Cela peut entraîner l’échec de l’appel OBO avec la même invalid_grant ou interaction_required des erreurs.

Si votre application n’est pas consciente de ce comportement, elle peut demander le consentement de l’utilisateur à plusieurs reprises. La meilleure pratique consiste à créer un mécanisme d’attente et de nouvelle tentative significatif pour éviter cette expérience utilisateur sous-optimale.

Le mécanisme d’attente et de nouvelle tentative doit suivre si un utilisateur a consenti aux étendues requises. Si un appel d’API qui inclut une demande OBO échoue avec les erreurs ci-dessus, mais que l’utilisateur a déjà donné son consentement, évitez d’afficher l’invite de consentement à l’utilisateur. Au lieu de cela, attendez un certain temps avant de réessayer l’appel d’API. En règle générale, Microsoft Entra ID envoie le consentement dans les trois à cinq secondes. Dans l’une de nos applications exemples, nous réessayons jusqu’à trois fois avec le double du temps d’attente entre chaque nouvelle tentative, en commençant par une seconde d’attente.

Si après trois à cinq tentatives, le flux OBO échoue toujours, l’utilisateur n’a peut-être pas consenti à toutes les étendues requises et vous devrez peut-être l’inviter à donner son consentement à nouveau.

Cette approche permet de réduire le risque que l’utilisateur soit invité à donner son consentement plus d’une fois.

Exemple de code

Voir aussi

• Flux On-Behalf-Of OAuth 2.0
• Obtenir l'accès pour MS Graph
• Sérialisation du cache de jetons dans MSAL.NET
• Fournisseur Microsoft Teams MSAL2