Convertir une application monolocataire en application multilocataire sur Microsoft Entra ID

  • Article

Si vous proposez une application SaaS (Software as a Service) à de nombreuses organisations, vous pouvez configurer votre application pour qu’elle accepte les connexions à partir de n’importe quel locataire Microsoft Entra en la convertissant en application multilocataire. Les utilisateurs de n’importe quel client Microsoft Entra pourront se connecter à votre application après votre consentement afin d’utiliser leur compte avec votre application.

Pour les applications existantes avec leur propre système de compte (ou d’autres connexions provenant d’autres fournisseurs de cloud), vous devez ajouter un code de connexion avec OAuth2, OpenID Connect ou SAML et placer un bouton « Se connecter avec Microsoft » dans votre application.

Dans ce guide pratique, vous allez effectuer les quatre étapes nécessaires pour convertir une application monolocataire en application multilocataire Microsoft Entra :

  1. Mettre à jour votre inscription d’application pour qu’elle soit multilocataire
  2. Mettre à jour votre code pour envoyer des demandes au point de terminaison /common
  3. Mettre à jour votre code pour gérer plusieurs valeurs issuer
  4. Comprendre le consentement de l’utilisateur et de l’administrateur et apporter des modifications de code appropriées

Si vous souhaitez essayer d’utiliser l’un de nos exemples, reportez-vous à Créer une application web SaaS multilocataire qui appelle Microsoft Graph à l’aide de Microsoft Entra ID et OpenID Connect

Prérequis

Conversion d’une inscription en inscription multilocataire

Par défaut, les inscriptions d’application web ou d’API dans Microsoft Entra ID sont monolocataires lors de la création. Pour effectuer l’inscription multilocataire, connectez-vous au Centre d’administration Microsoft Entra et sélectionnez l’inscription de l’application que vous souhaitez mettre à jour. Une fois l’inscription de l’application ouverte, sélectionnez le volet Authentification et accédez à la section Types de comptes pris en charge. Remplacez le paramètre par Comptes dans un annuaire organisationnel.

Lorsqu’une application monolocataire est créée dans le Centre d’administration Microsoft Entra, l’un des éléments répertoriés dans la page Vue d’ensemble est l’URI d’ID d’application. Il s’agit de l’une des méthodes d’identification d’une application dans les messages de protocole. Vous pouvez l’ajouter à tout moment. L’URI d’ID d’application pour les applications monolocataires peut être globalement unique au sein de ce locataire. En revanche, pour les applications multilocataires, il doit être globalement unique à l’échelle de tous les locataires de manière à ce que Microsoft Entra ID puisse trouver l’application dans l’ensemble des locataires.

Par exemple, si contoso.onmicrosoft.com est le nom de votre locataire, https://contoso.onmicrosoft.com/myapp est un URI d’ID d’application valide. Si l’URI d’ID d’application ne suit pas ce modèle, une application ne peut pas être définie comme multilocataire.

Mettre à jour votre code pour envoyer des demandes à /common

Avec une application multilocataire, l’application ne peut pas déterminer immédiatement de quel locataire provient l’utilisateur, donc les requêtes ne peuvent pas être envoyées au point de terminaison d’un locataire. Au lieu de cela, les requêtes sont envoyées à un point de terminaison commun (https://login.microsoftonline.com/common) qui sert à tous les locataires Microsoft Entra, agissant en tant que hub central qui gère les requêtes.

Ouvrez votre application dans votre IDE et modifiez votre code et modifiez la valeur de votre ID de locataire sur /common. Ce point de terminaison n’est pas un locataire ou un émetteur lui-même. Quand la plateforme d’identités Microsoft reçoit une demande sur le point de terminaison /common, elle connecte l’utilisateur et découvre ainsi de quel locataire il provient. Ce point de terminaison fonctionne avec tous les protocoles d’authentification pris en charge par Microsoft Entra ID (OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation).

La réponse de connexion envoyée à l’application contient un jeton représentant l’utilisateur. La valeur issuer du jeton indique à une application de quel client provient l’utilisateur. Quand le point de terminaison /common retourne une réponse, la valeur issuer dans le jeton correspond au locataire de l’utilisateur.

Remarque

Il existe, en réalité, 2 autorités pour des applications multilocataires :

  • https://login.microsoftonline.com/common pour des applications qui traient les comptes d’un annuaire d’organisation (tout annuaire Microsoft Entra) et des comptes Microsoft personnels (par exemple, Skype, Xbox).
  • https://login.microsoftonline.com/organizations pour des applications qui traitent les comptes d’un annuaire organisationnel (n’importe quel annuaire Microsoft Entra) :

Les explications de ce document utilisent common. Vous pouvez également le remplacer par organizations si votre application ne prend pas en charge les comptes personnels Microsoft.

Mise à jour de votre code pour gérer plusieurs valeurs issuer

Les applications web et les API web reçoivent et valident les jetons de la plateforme d’identités Microsoft. Les applications clientes natives ne valident pas les jetons d’accès et doivent les traiter comme des valeurs opaques. Au lieu de cela, elles demandent et reçoivent des jetons de la plateforme d’identités Microsoft et le font pour les envoyer aux API, où ils sont validés.

Les applications multilocataires doivent effectuer davantage de vérifications lors de la validation d’un jeton. Une application multilocataire est configurée pour consommer des métadonnées de clés à partir des URL de clés /organizations ou /common. L’application doit vérifier que la propriété issuer dans les métadonnées publiées correspond à la revendication iss dans le jeton, outre la vérification habituelle que la revendication iss dans le jeton contient la revendication d’ID de tenant (tid). Pour obtenir plus d’informations, consultez Valider les jetons.

Pour qu’un utilisateur puisse se connecter à une application dans Microsoft Entra ID, cette application doit être représentée dans le client de l’utilisateur. Cela permet à l’organisation d’effectuer différentes tâches, par exemple appliquer des stratégies uniques lorsque les utilisateurs de leurs clients se connectent à l’application. Pour une application monolocataire, vous pouvez utiliser l’inscription via le Centre d’administration Microsoft Entra.

Pour une application multilocataire, l’inscription initiale de l’application réside dans le locataire Microsoft Entra utilisé par le développeur. Lorsqu’un utilisateur d’un autre client se connecte à l’application pour la première fois, Microsoft Entra ID l’invite à donner son consentement pour les autorisations demandées par l’application. S’il donne son consentement, une représentation de l’application appelée principal du service est créée dans le client de l’utilisateur, et la connexion peut alors continuer. Une délégation est également créée dans le répertoire qui enregistre le consentement de l’utilisateur pour l’application. Pour plus d’informations sur les objets ServicePrincipal et Application de l’application et sur les liens qui les unissent, voir Objets principal de service et application.

Diagramme illustrant le consentement d’un utilisateur pour une application mononiveau.

Ce processus de consentement dépend des autorisations demandées par l’application. La plateforme d’identité Microsoft prend en charge deux types d’autorisations :

  • Déléguée : cette autorisation accorde à une application la possibilité d’agir comme un utilisateur connecté pour un sous-ensemble d’actions que l’utilisateur peut effectuer. Par exemple, vous pouvez accorder à une application l’autorisation déléguée pour lire le calendrier de l’utilisateur connecté.
  • Application seule : cette autorisation est directement accordée à l’identité de l’application. Par exemple, vous pouvez accorder à une application une autorisation application seule pour lire la liste des utilisateurs d’un client, quels que soient les clients connectés à l’application.

Certaines autorisations peuvent être accordées par un utilisateur standard, tandis que d’autres nécessitent le consentement de l’administrateur d’un client.

Pour en savoir plus sur le consentement de l’utilisateur et de l’administrateur, consultez Configurer le workflow du consentement administrateur.

Les autorisations application seule nécessitent toujours le consentement de l’administrateur d’un client. Si votre application demande une autorisation application seule et qu’un utilisateur tente de se connecter à l’application, un message d’erreur indiquant que l’utilisateur n’est pas en mesure de donner son consentement s’affiche.

Certaines autorisations déléguées nécessitent également le consentement de l’administrateur d’un client. Par exemple, la possibilité de réécrire dans Microsoft Entra ID en tant que l’utilisateur connecté requiert le consentement de l’administrateur d’un client. Comme pour les autorisations application uniquement, si un utilisateur standard tente de se connecter à une application qui demande une autorisation déléguée nécessitant le consentement de l’administrateur, l’application reçoit une erreur. Le fait qu’une autorisation nécessite le consentement d’un administrateur est déterminé par le développeur qui a publié la ressource, et ces informations sont disponibles dans la documentation de cette ressource. La documentation sur les autorisations pour l’API Microsoft Graph indique les autorisations qui nécessitent le consentement de l’administrateur.

Si votre application utilise des autorisations qui nécessitent un consentement administrateur, songez à ajouter un bouton ou un lien afin que l’administrateur puisse lancer l’action. La requête que votre application envoie pour cette action est une demande d’autorisation OAuth2/OpenID Connect ordinaire, mais qui inclut également le paramètre de chaîne de requête prompt=consent. Une fois que l’administrateur a donné son consentement et que le principal de service est créé dans le locataire du client, les demandes de connexion ultérieures n’ont pas besoin du paramètre prompt=consent. Comme l’administrateur a décidé que les autorisations demandées sont acceptables, les autres utilisateurs n’ont plus à donner leur consentement par la suite.

L’administrateur d’un client peut empêcher les utilisateurs standard de donner son consentement aux applications. Si cette fonctionnalité est désactivée, le consentement de l’administrateur est toujours requis pour que l’application soit utilisée dans le client. Vous pouvez tester votre application avec le consentement de l’utilisateur final désactivé, dans le centre d’administration Microsoft Entra. Dans Applications d’entreprise>Consentement et autorisations, cochez l’option Ne pas autoriser le consentement de l’utilisateur.

Le paramètre prompt=consent peut également être utilisé par les applications qui demandent des autorisations ne nécessitant pas le consentement de l’administrateur. Un exemple d’utilisation de cela est quand l’application requiert une expérience où l’administrateur du client « s’inscrit » une fois, et qu’aucun autre utilisateur n’est invité à donner son consentement à partir de ce moment.

Si une application requiert le consentement de l’administrateur, et qu’un administrateur se connecte sans que le paramètre prompt=consent soit envoyé, le consentement de l’administrateur s’applique uniquement pour son compte d’utilisateur. Les utilisateurs standard ne pourront toujours pas se connecter ou donner leur consentement à l’application. Cette fonctionnalité s’avère utile si vous souhaitez donner à l’administrateur du locataire la possibilité d’explorer votre application avant d’autoriser l’accès à d’autres utilisateurs.

Votre application peut comporter plusieurs niveaux, chacun représenté par sa propre inscription dans Microsoft Entra ID. Par exemple, une application native qui appelle une API web ou une application web qui appelle une autre API web. Dans ces deux cas, le client (application native ou application web) demande des autorisations pour appeler la ressource (API web). Pour que le client puisse donner son consentement pour un client, toutes les ressources nécessitant des autorisations doivent déjà exister dans ce client. Si cette condition n’est pas remplie, Microsoft Entra ID renvoie une erreur indiquant que la ressource doit d’abord être ajoutée.

Plusieurs niveaux dans un seul client

Cela peut poser problème si votre application logique implique deux ou plusieurs inscriptions d’application, par exemple un client et une ressource distincts. Comment obtenir la ressource dans le locataire externe en premier ? Microsoft Entra ID traite ce cas en permettant au client et aux ressources d’être consentis en une seule étape. L’utilisateur voit l’ensemble des autorisations demandées par le client et les ressources sur la page de consentement. Pour activer ce comportement, l’inscription d’application de la ressource doit inclure l’ID d’application du client en tant que knownClientApplications dans son manifeste d’application. Par exemple :

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Ceci est illustré dans un exemple d’application multilocataire. Le diagramme ci-dessous décrit le processus de consentement pour une application multiniveau enregistrée dans un seul client.

Diagramme illustrant le consentement pour une application cliente multiniveau connue.

Plusieurs niveaux dans plusieurs clients

Un cas similaire se produit si les différents niveaux d’une application sont enregistrés dans différents clients. Prenons par exemple le cas de la création d’une application cliente native qui appelle l’API Exchange Online. Pour développer l’application native, et pour que l’application native s’exécute ensuite sur un client, le principal du service Exchange Online doit être présent. Dans ce cas, le développeur et l’utilisateur doivent acheter Exchange Online afin de créer le principal du service sur leurs clients.

Dans le cas d’une API générée par une organisation autre que Microsoft, le développeur de l’API doit fournir un moyen à ses clients de donner leur consentement à l’application sur leurs clients. La conception recommandée est que le développeur tiers génère l’API de façon à pouvoir également fonctionner comme un client web pour implémenter l’inscription. Pour ce faire :

  1. Suivez les sections précédentes pour vous assurer que l’API implémente les exigences de code/d’inscription d’application multilocataire.
  2. Outre l’exposition des rôles/étendues de l’API, vérifiez que l’inscription inclut l’autorisation « Se connecter et lire le profil utilisateur » (fournie par défaut).
  3. Implémentez une page de connexion/inscription dans le client web, et suivez le guide Consentement de l’administrateur.
  4. Une fois que l’utilisateur donne son consentement à l’application, les liens du principal de service et de la délégation de consentement sont créés dans son client, et l’application native peut obtenir des jetons pour l’API.

Le diagramme suivant décrit le processus de consentement pour une application multiniveau enregistrée dans différents clients.

Diagramme illustrant le consentement pour une application multiniveau impliquant plusieurs personnes.

Les utilisateurs et les administrateurs peuvent à tout moment révoquer leur consentement pour votre application :

  • Les utilisateurs révoquent l’accès à des applications individuelles en les supprimant de leur liste Applications du panneau d’accès.
  • Les administrateurs révoquent l’accès à des applications en les supprimant à l’aide de la section Applications d’entreprise du centre d’administration Microsoft Entra. Sélectionnez l’application et accédez à l’onglet Autorisations pour révoquer l’accès.

Si un administrateur donne son consentement à une application pour tous les utilisateurs d’un locataire, les utilisateurs ne peuvent pas révoquer l’accès individuellement. Seul l’administrateur peut révoquer l’accès et uniquement pour l’application entière.

Applications multilocataires et mise en cache des jetons d’accès

Les applications multilocataires peuvent également obtenir des jetons d’accès pour appeler des API protégées par Microsoft Entra ID. Une erreur courante lors de l’utilisation de la bibliothèque d’authentification Microsoft (MSAL) avec une application multilocataire consiste à demander initialement un jeton pour un utilisateur en utilisant /common, à recevoir une réponse, puis à demander un nouveau jeton pour ce même utilisateur en utilisant également /common. Comme la réponse de Microsoft Entra ID provient d’un locataire et non de /common, MSAL met en cache le jeton comme provenant du locataire. L’appel suivant à /common pour obtenir un jeton d’accès pour l’utilisateur manque l’entrée de cache et l’utilisateur est invité à se reconnecter. Pour éviter de manquer le cache, assurez-vous que les appels suivants pour un utilisateur déjà connecté sont effectués vers le point de terminaison du client.

Voir aussi