É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 autoriser des autorisations utilisateur supplémentaires, telles que pour afficher le profil utilisateur de l’application, lire le 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 l’ID Microsoft Entra

Vous pouvez configurer des étendues Graph supplémentaires dans l’ID Microsoft Entra 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 d’abord y donner son consentement. Par la suite, votre application d’onglet 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 des autorisations d’application, également appelée scénario d’accès d’application uniquement. Seuls les administrateurs peuvent accorder le consentement pour les autorisations d’application. Pour plus d’informations, consultez 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 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 des 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 nécessiter, 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 plateforme à partir d’une applicationweb ou monopage.

   

   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 l’ID Microsoft Entra 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. Pour ce faire, utilisez le flux Microsoft Entra on-behalf-of (OBO).

L’implémentation actuelle de l’authentification unique (SSO) est limitée aux autorisations de niveau 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 SSO 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 l’ID Microsoft Entra, vous devez obtenir l’ID de jeton auprès 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 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 retourne 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 jeton dans MSAL.NET pour mettre en cache le nouveau jeton d’accès pour plusieurs, si nécessaire.

Obtenir le consentement

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

De l’administrateur du locataire

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 de client JavaScript (TeamsJS) Microsoft Teams, gardez à l’esprit les considérations suivantes :

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

1. Le jeton récupéré à l’aide getAuthToken() de doit être échangé côté serveur à l’aide du flux Microsoft Entra OBO pour accéder à ces autres API Graph. Veillez à utiliser le point de terminaison 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 d’accéder aux données de l’utilisateur. Dans ce cas, votre échange échoue avec l’erreur invalid_grant ou interaction_required . Les exemples d’erreurs invalid_grant incluent lorsque le consentement est requis ou auth_code, l’assertion ou le jeton d’actualisation est expiré, révoqué, mal formé ou absent. Les exemples de interaction_required incluent quand l’authentification multifacteur ou l’inscription d’appareils d’entreprise est requise.

3. Si l’échange échoue en raison d’erreurs invalid_grant ou interaction_required , vous devez inviter l’utilisateur à donner son consentement. Étant donné que l’interaction utilisateur ne peut se produire qu’à partir du client, votre serveur doit retourner à votre application cliente une indication indiquant 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 Microsoft Entra.

4. Pour demander à l’utilisateur le consentement pour que votre application accède à ses données, vous devez inclure la prompt=consent propriété dans votre paramètre de chaîne de requête à l’ID Microsoft Entra.

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

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

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

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

Si un utilisateur n’a pas accordé le consentement de l’application Microsoft Entra pour ces étendues, votre appel OBO échoue avec invalid_grant ou interaction_required une 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 l’ID Microsoft Entra qui propage ce consentement et la demande OBO effectuée. Cela peut entraîner l’échec de l’appel OBO avec le même invalid_grant ou interaction_required des erreurs.

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

Le mécanisme d’attente et de nouvelle tentative doit effectuer le suivi si un utilisateur a consenti aux étendues requises. Si un appel d’API qui inclut une requête 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, l’ID Microsoft Entra envoie le consentement dans un délai de trois à cinq secondes. Dans l’un de nos exemples d’applications, 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 donné son consentement à toutes les étendues requises et vous devrez peut-être l’inviter à donner à nouveau son consentement.

Cette approche permet de réduire le risque que l’utilisateur soit invité à donner son consentement plusieurs 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