Activer l’authentification unique pour les extensions de message basées sur l’API

Article
10/28/2024

La méthode d’authentification unique (SSO) pour l’extension de message basée sur l’API utilise l’identité Teams d’un utilisateur d’application pour lui fournir l’accès à votre application. Un utilisateur qui s’est connecté à Teams n’a pas besoin de se reconnecter à votre application dans l’environnement Teams. Microsoft Entra’authentification unique permet à l’application d’obtenir en mode silencieux un jeton utilisateur émis pour sa ressource par Microsoft Entra. L’application peut ensuite authentifier ce jeton et récupérer les informations de profil utilisateur sans le consentement de l’utilisateur.

Configuration requise

Avant de commencer, vérifiez que vous disposez des éléments suivants :

Un compte Azure avec un abonnement actif.
Connaissance de base du Microsoft Entra ID et du développement d’applications Teams.

L’image suivante montre le fonctionnement de l’authentification unique lorsqu’un utilisateur de l’application Teams tente d’accéder à l’application d’extension de message basée sur l’API :

L’utilisateur appelle l’application d’extension de message basée sur l’API dans Teams et appelle une commande qui nécessite une authentification.
L’application envoie une requête au service principal Teams avec l’ID d’application et l’étendue requise (access_as_user).
Le service principal Teams vérifie si l’utilisateur a donné son consentement à l’application et à l’étendue. Si ce n’est pas le cas, il affiche un écran de consentement à l’utilisateur.
Si l’utilisateur y consent, Microsoft Entra génère un jeton d’accès pour l’utilisateur et l’application et l’envoie à l’application dans l’en-tête d’autorisation de la demande.
L’application valide le jeton et extrait les informations utilisateur du jeton, telles que le nom, l’e-mail et l’ID d’objet.
Une fois l’authentification réussie, l’utilisateur est autorisé à accéder à l’extension de message basée sur l’API.

Pour activer l’authentification unique pour l’extension de message basée sur l’API, procédez comme suit :

Inscrire une nouvelle application dans Microsoft Entra ID.
Configurez l’étendue du jeton d’accès.
Authentifiez le jeton.
Mettre à jour le manifeste de l’application.

Inscrire une nouvelle application dans Microsoft Entra ID

Ouvrez le Portail Azure sur votre navigateur web.
Sélectionnez l’icône Inscriptions d'applications.

La page Inscriptions d'applications s’affiche.
Sélectionnez l’icône + Nouvelle inscription.

La page Inscrire une application s’affiche.
Entrez le nom de l’application que vous souhaitez afficher à l’utilisateur de l’application. Vous pouvez modifier le nom ultérieurement si vous le souhaitez.

Sélectionnez le type de compte d’utilisateur qui peut accéder à votre application. Vous pouvez sélectionner des options monolocataires ou multilocataires dans les répertoires de l’organisation ou restreindre l’accès aux comptes Microsoft personnels uniquement.

Options pour les types de comptes pris en charge

Option	Sélectionnez cette option pour...
Comptes dans cet annuaire d’organisation uniquement (Microsoft uniquement - Monolocataire)	Créez une application pour une utilisation uniquement par des utilisateurs (ou des invités) dans votre client. Souvent appelée application personnalisée conçue pour votre organisation (application métier), cette application est une application monolocataire dans le Plateforme d'identités Microsoft.
Comptes dans n’importe quel annuaire organisationnel (n’importe quel locataire Microsoft Entra ID - Multilocataire)	Permettre aux utilisateurs de n’importe quel locataire Microsoft Entra d’utiliser votre application. Cette option est appropriée si, par exemple, vous créez une application SaaS et que vous envisagez de la mettre à la disposition de plusieurs organisations. Ce type d’application est appelé application multilocataire dans le Plateforme d'identités Microsoft.
Comptes dans n’importe quel annuaire organisationnel (tout locataire Microsoft Entra ID - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox)	Ciblez un large ensemble de clients. En sélectionnant cette option, vous inscrivez une application multilocataire qui peut également prendre en charge les utilisateurs d’applications qui ont des comptes Microsoft personnels.
Comptes Microsoft personnels uniquement	Créez une application uniquement pour les utilisateurs disposant de comptes Microsoft personnels.

Remarque

Vous n’avez pas besoin d’entrer l’URI de redirection pour activer l’authentification unique pour une application d’extension de message basée sur l’API.

Sélectionnez Inscrire. Un message s’affiche sur le navigateur indiquant que l’application a été créée.

La page avec l’ID d’application et d’autres détails de l’application s’affiche.
Notez et enregistrez l’ID d’application à partir de l’ID d’application (client) pour mettre à jour le manifeste de l’application ultérieurement.

Votre application est inscrite dans Microsoft Entra ID. Vous disposez maintenant de l’ID d’application pour votre application d’extension de message basée sur l’API.

Configurer l’étendue du jeton d’accès

Une fois que vous avez créé une inscription d’application, configurez les options d’étendue (autorisation) pour l’envoi du jeton d’accès au client Teams et autorisez les applications clientes approuvées pour activer l’authentification unique.

Pour configurer l’étendue et autoriser les applications clientes approuvées, vous devez :

Ajouter l’URI d’ID d’application : Configurez les options d’étendue (autorisation) pour votre application. Exposez une API web et configurez l’URI de l’ID d’application.
Configurer l’étendue de l’API : définissez l’étendue de l’API et les utilisateurs qui peuvent donner leur consentement pour une étendue. Vous pouvez autoriser uniquement les administrateurs à donner leur consentement pour des autorisations à privilèges plus élevés.
Configurer l’application cliente autorisée : créez des ID client autorisés pour les applications que vous souhaitez préautoriser. Cela permet à l’utilisateur de l’application d’accéder aux étendues d’application (autorisations) que vous avez configurées, sans nécessiter de consentement supplémentaire. Préautorisez uniquement les applications clientes auxquelles vous faites confiance, car les utilisateurs de votre application n’ont pas la possibilité de refuser le consentement.

URI ID d'application

Sélectionnez Gérer>Exposer une API dans le volet gauche.

La page Exposer une API s’affiche.
Sélectionnez Ajouter pour générer l’URI d’ID d’application sous la forme .api://{AppID}

La section permettant de définir l’URI de l’ID d’application s’affiche.
Entrez l’URI de l’ID d’application au format expliqué ici.
- L’URI d’ID d’application est prérempli avec l’ID d’application (GUID) au format api://{AppID}.
- Le format d’URI de l’ID d’application doit être : api://fully-qualified-domain-name.com/{AppID}.
- Insérez le fully-qualified-domain-name.com entre api:// et {AppID} (autrement dit, le GUID). Par exemple, api://example.com/{AppID}.
Importante
- Si vous créez un bot autonome, entrez l’URI de l’ID d’application en tant que api://botid-{YourBotId}. Ici, {YourBotId} est votre ID d’application Microsoft Entra.
- Si vous créez une application avec un bot, une extension de message et un onglet, entrez l’URI de l’ID d’application en tant que api://fully-qualified-domain-name.com/botid-{YourClientId}, où {YourClientId} est votre ID d’application bot.
- Si vous créez une application avec une extension de message ou des fonctionnalités d’onglet sans le bot, entrez l’URI d’ID d’application en tant que api://fully-qualified-domain-name.com/{YourClientId}, où {YourClientId} est votre ID d’application Microsoft Entra.
- URI d’ID d’application pour l’application avec plusieurs fonctionnalités : si vous créez une extension de message basée sur l’API, entrez l’URI d’ID d’application en tant que api://fully-qualified-domain-name.com/{YourClientId}, où {YourClientId} est votre ID d’application Microsoft Entra.
- Format du nom de domaine : utilisez uniquement des lettres minuscules pour le nom de domaine.
Sélectionnez Enregistrer.

Un message s’affiche dans le navigateur indiquant que l’URI de l’ID d’application a été mis à jour.

L’URI de l’ID d’application s’affiche sur la page.
Notez et enregistrez l’URI de l’ID d’application pour mettre à jour le manifeste de l’application ultérieurement.

Configurer l’étendue de l’API

Remarque

L’extension de message basée sur l’API prend uniquement en charge l’étendue access_as_user .
L’API reçoit un jeton d’accès Microsoft Entra dont l’étendue est définie access_as_user sur inscrite dans le Portail Azure. Toutefois, le jeton n’est pas autorisé à appeler d’autres API en aval, telles que Microsoft Graph.

Sélectionnez + Ajouter une étendue dans les étendues définies par cette section d’API.

La page Ajouter une étendue s’affiche.
Entrez les détails de la configuration de l’étendue.
1. Entrez le nom de l’étendue. Ce champ est obligatoire.
2. Sélectionnez l’utilisateur qui peut donner son consentement pour cette étendue. L’option par défaut est Admins uniquement.
3. Entrez le nom d’affichage du consentement de l’administrateur. Ce champ est obligatoire.
4. Entrez la description du consentement de l’administrateur. Ce champ est obligatoire.
5. Entrez le nom d’affichage du consentement de l’utilisateur.
6. Entrez la description du consentement de l’utilisateur.
7. Sélectionnez l’option Activé pour l’état.
8. Sélectionnez Ajouter une étendue.
Un message s’affiche sur le navigateur indiquant que l’étendue a été ajoutée.

La nouvelle étendue que vous avez définie s’affiche sur la page.

Configurer l’application cliente autorisée

Parcourez la page Exposer une API jusqu’à la section Application cliente autorisée , puis sélectionnez + Ajouter une application cliente.

La page Ajouter une application cliente s’affiche.
Entrez l’ID client Microsoft 365 approprié pour les applications que vous souhaitez autoriser pour l’application web de votre application.

Remarque

Les ID de client Microsoft 365 pour les applications mobiles, de bureau et web pour Teams sont les ID réels que vous devez ajouter.
1. Sélectionnez l’un des ID client suivants :
  
  Utiliser l’ID client Pour autoriser...
  
  1fec8e78-bce4-4aaf-ab1b-5451cc387264 Application mobile ou de bureau Teams
  
  5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Application web Teams
2. Sélectionnez l’URI d’ID d’application que vous avez créé pour votre application dans Étendues autorisées afin d’ajouter l’étendue à l’API web que vous avez exposée.
3. Sélectionnez Ajouter une application.
  
  Un message s’affiche sur le navigateur indiquant que l’application cliente autorisée a été ajoutée.
  
  L’ID client de l’application autorisée s’affiche sur la page.

Utiliser l’ID client	Pour autoriser...
1fec8e78-bce4-4aaf-ab1b-5451cc387264	Application mobile ou de bureau Teams
5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Application web Teams

Remarque

Vous pouvez autoriser plusieurs applications clientes. Répétez les étapes de cette procédure pour configurer une autre application cliente autorisée.

Vous avez correctement configuré l’étendue de l’application, les autorisations et les applications clientes. Veillez à noter et à enregistrer l’URI de l’ID d’application. Ensuite, vous configurez la version du jeton d’accès.

Authentifier le jeton

Lorsque l’extension de message appelle l’API pendant l’authentification, elle reçoit une requête avec le jeton d’accès de l’utilisateur. L’extension de message ajoute ensuite le jeton dans l’en-tête d’autorisation de la requête HTTP sortante. Le format d’en-tête est Authorization: Bearer <token_value>. Par exemple, lorsqu’une extension de message effectue un appel d’API à un service qui nécessite une authentification. L’extension construit une requête HTTP comme suit :

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Une fois que l’extension de message basée sur l’API a obtenu un en-tête de requête avec un jeton, procédez comme suit :

Authentifier : vérifiez le jeton pour l’audience, l’étendue, l’émetteur et les revendications de signature à case activée si le jeton est destiné à votre application. Pour plus d’informations sur les revendications, consultez Revendications de jeton d’ID.

L’exemple suivant montre le jeton web JSON (JWT) avec un en-tête et une réponse :

Jeton V2
Jeton V1

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "api://00000002-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/{tenantid}/",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "acr": "1",
  "aio": "AXQAi/8IAAAA",
  "amr": ["pwd"],
  "appid": "c44b4083-3bb0-49c1-b47d-974e53cbdf3c",
  "appidacr": "0",
  "ipaddr": "192.168.1.1",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "scp": "access_as_user",
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  }

Utiliser le jeton : extrayez les informations utilisateur du jeton, telles que le nom, l’adresse e-mail et l’ID d’objet, puis utilisez le jeton pour appeler la propre API de l’application d’extension de message. Pour plus d’informations sur les références aux revendications avec des détails sur les revendications incluses dans les jetons d’accès, consultez Revendications de jeton d’accès.

Mettre à jour le manifeste de l’application

Mettez à jour les propriétés suivantes dans le fichier manifeste de l’application :

webApplicationInfo: la webApplicationInfo propriété est utilisée pour activer l’authentification unique pour votre application afin d’aider les utilisateurs de l’application à accéder en toute transparence à votre application d’extension de message basée sur l’API. L’URI d’ID d’application que vous avez inscrit dans Microsoft Entra ID est configuré avec l’étendue de l’API que vous avez exposée. Pour plus d'informations, voir webApplicationInfo ..
microsoftEntraConfiguration: active l’authentification unique pour votre application. Configurez la supportsSingleSignOn propriété sur true pour prendre en charge l’authentification unique et réduire le besoin de plusieurs authentifications. Si la propriété a la valeur false ou est laissée vide, l’utilisateur ne peut pas charger l’application dans Teams et la validation de l’application échoue.

Pour configurer le manifeste de l’application :

Ouvrez l’application d’extension de message basée sur l’API.
Ouvrez le dossier manifeste de l’application.
Remarque
- Le dossier manifeste de l’application doit se trouver à la racine de votre dossier d’application. Pour plus d’informations, consultez Créer un package d’application Microsoft Teams.
- Pour plus d’informations sur la création d’un manifest.json, consultez le schéma du manifeste d’application.
Ouvrez le fichier manifest.json.
Ajoutez l’extrait de code suivant à la webApplicationInfo section de votre fichier manifeste d’application :
```
"webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
```
où,
- {Microsoft Entra AppId}est l’ID d’application que vous avez créé lors de l’inscription de votre application dans Microsoft Entra ID. C’est le GUID.
- api://subdomain.example.com/{Microsoft Entra AppId}est l’URI d’ID d’application que vous avez inscrit lors de la création de l’étendue dans Microsoft Entra ID.

Ajoutez l’extrait de code suivant à la composeExtensions section de votre fichier manifeste d’application :

"authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

Enregistrez le fichier manifeste de l’application.

Félicitations ! Vous avez activé l’authentification unique pour vos extensions de message basées sur l’API.

Partager via

Activer l’authentification unique pour les extensions de message basées sur l’API

Configuration requise

Inscrire une nouvelle application dans Microsoft Entra ID

Configurer l’étendue du jeton d’accès

URI ID d'application

Configurer l’étendue de l’API

Configurer l’application cliente autorisée

Authentifier le jeton

Mettre à jour le manifeste de l’application

Voir aussi

Ressources supplémentaires