Partager via

Restrictions sur les URI d’identificateur des applications Microsoft Entra

La identifierUri propriété - également appelée Application ID URI - d’une application Microsoft Entra est une propriété généralement configurée sur les applications de ressource (API). La configuration de cette propriété de manière sécurisée est essentielle à la sécurité de la ressource.

Modèles sécurisés

L’API et les formats d’URI d’ID d’application basée sur le schéma HTTP suivants sont pris en charge. Remplacez les valeurs d’espace réservé comme décrit dans la liste qui suit le tableau.

ID d’application pris en charge
Formats d’URI		 Exemples d’URI d’ID d’application
<api:// appId> api://00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId/>appId<> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<string> api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
<api:// string>/<appId> api://productapi/00001111-aaaa-2222-bbbb-3333cccc4444
<https:// tenantInitialDomain.onmicrosoft.com/>< string> https://contoso.onmicrosoft.com/productsapi
<https:// verifiedCustomDomain>/<string> https://contoso.com/productsapi
<https:// string>.<verifiedCustomDomain> https://product.contoso.com
<https:// string>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
<api://string>.<verifiedCustomDomainOrInitialDomain>/<string> api://contoso.com/productsapi
  • <appId> : propriété d’identificateur d’application (appId) de l’objet application.
  • <string> : valeur de chaîne pour l’hôte ou le segment de chemin d’accès de l’API.
  • <tenantId> : GUID généré par Azure pour représenter le locataire dans Azure.
  • <tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, où <tenantInitialDomain> est le nom de domaine initial que le créateur du locataire a spécifié lors de la création du locataire.
  • <verifiedCustomDomain> : domaine personnalisé vérifié configuré pour votre tenant Microsoft Entra.

Remarque

Si vous utilisez le schéma api:// , vous ajoutez une valeur de chaîne directement après « api:// ». Par exemple, api://<chaîne>. Cette valeur de chaîne peut être un GUID ou une chaîne arbitraire. Si vous ajoutez une valeur GUID, elle doit correspondre à l’ID d’application ou à l’ID de locataire. Si vous utilisez une valeur de chaîne, elle doit utiliser un domaine personnalisé vérifié ou un domaine initial de votre locataire. La recommandation consiste à utiliser api://< appId>.

Importante

La valeur de l’URI d’ID d’application ne doit pas se terminer par une barre oblique « / ».

Importante

La valeur de l’URI de l’ID d’application doit être unique au sein de votre locataire.

Application de modèles sécurisés avec une stratégie

Microsoft a introduit un paramètre de sécurité qui protège contre la configuration non sécurisée des URI d’identificateur (également appelés « URI d’ID d’application ») sur les applications Microsoft Entra. Ce paramètre de sécurité garantit que les URI nouvellement ajoutés sur les applications v1 sont conformes aux modèles sécurisés décrits ci-dessus.

Comportement de stratégie

Lorsque ce paramètre est activé, les modèles sécurisés sont strictement appliqués. Lorsqu’elle est activée, si une personne de votre organisation tente d’ajouter un URI d’identificateur qui ne respecte pas les modèles sécurisés, il reçoit une erreur telle que :

Failed to add identifier URI {uri}. All newly added URIs must contain a tenant verified domain, tenant ID, or app ID, as per the default tenant policy of your organization. See https://aka.ms/identifier-uri-addition-error for more information on this error.

Les applications configurées pour utiliser des jetons Entra ID v2.0, en définissant la propriété api.requestedAccessTokenVersion de l'application à 2, sont exemptées par défaut. Les applications configurées pour utiliser le protocole SAML pour l'authentification unique, en définissant la propriété du service principal preferredSingleSignOnMode sur SAML, sont également exemptées par défaut.

Les URI d’identificateur existants déjà configurés sur l’application ne seront pas affectés, et toutes les applications continueront de fonctionner normalement. Cela affecte uniquement les nouvelles mises à jour des configurations d’application Microsoft Entra.

Lorsqu’il n’est pas activé, certains modèles non sécurisés peuvent toujours être utilisés. Par exemple, les URI du format api://{string} peuvent toujours être ajoutés. Toutefois, même lorsque le paramètre est désactivé, un locataire vérifié ou un domaine initial peut toujours être requis dans certains scénarios, par exemple lors de l’utilisation du https:// système.

Activation et gestion de la stratégie

Microsoft a peut-être déjà activé cette stratégie dans votre organisation pour améliorer sa sécurité. Vous pouvez vérifier en exécutant ce script.

Même si Microsoft a activé la stratégie dans votre organisation, un administrateur client a toujours un contrôle total sur celui-ci. Ils peuvent accorder des exemptions à une application Microsoft Entra spécifique, à eux-mêmes, à un autre utilisateur de l’organisation, ou à tout service ou processus que l’organisation utilise. Ou, un administrateur peut désactiver la stratégie (non recommandé).

Microsoft n’active pas la stratégie dans votre organisation si elle détecte que votre organisation a des processus susceptibles d’être perturbés par la modification. Au lieu de cela, un administrateur de votre organisation peut l’activer lui-même (recommandé).

Aide pour les développeurs

Lisez cette section si vous êtes développeur et que vous essayez d’ajouter un URI d’identificateur (également appelé URI d’ID d’application) à une API Microsoft Entra que vous possédez, mais vous avez reçu cette erreur.

Il existe trois façons possibles d’ajouter un URI d’identificateur à votre application. Nous les recommandons dans l’ordre suivant :

  1. Utiliser l’un des modèles d’URI sécurisés

  2. Si vous avez rencontré cette erreur, cela signifie que votre API utilise actuellement des jetons v1.0. Vous pouvez vous débloquer en mettant à jour votre service pour accepter les jetons v2.0. Les jetons V2.0 sont similaires à v1.0, mais il existe certaines différences. Une fois que votre service est en mesure de gérer les jetons v2.0, vous pouvez mettre à jour la configuration de votre application afin que Microsoft Entra les envoie des jetons v2.0. Pour ce faire, vous pouvez facilement utiliser l’éditeur de manifeste dans l’expérience d’inscriptions d’applications du Centre d’administration Microsoft Entra :

    Capture d'écran de l'expérience de la mise à jour de la version du jeton.

    Toutefois, vous devez procéder avec prudence lors de cette modification. Cela est dû au fait que lorsque l’application a été mise à jour au format de jeton v2.0, elle ne pourra pas revenir aux jetons v1.0 s’il a configuré des URI d’identificateur non conformes, sauf s’il a reçu une exemption (voir l’option 3).

  3. Si vous devez ajouter un URI d’identificateur non conforme à votre application avant de pouvoir effectuer une mise à jour vers le format de jeton v2.0, vous pouvez demander à votre administrateur d’accorder à votre application une exemption.

Paramètres de sécurité supplémentaires

Microsoft propose également une politique de sécurité plus restrictive concernant la propriété identifierUris. Cette stratégie plus restrictive est appelée nonDefaultUriAddition.

Lorsque cette protection est activée, de nouvelles URI d’identificateur personnalisés ne peuvent pas être ajoutées à une application de cette organisation, à l’exception des scénarios sécurisés connus. Plus précisément, si l’une des conditions suivantes est remplie, un URI d’identificateur peut toujours être ajouté :

  • L’URI d’identificateur ajouté à l’application est l’une des URI « par défaut », ce qui signifie qu’elles sont au format api://{appId} ou api://{tenantId}/{appId}.
  • L’application accepte v2.0 les jetons Entra. Cette valeur est vraie si la propriété de l’application api.requestedAccessTokenVersion est définie sur 2.
  • L’application utilise le protocole SAML pour l’authentification unique (SSO). Cela est vrai si le principal d'application de l’application a sa propriété preferredSingleSignOnMode définie sur SAML.
  • Une exemption a été accordée par un administrateur à l’application auquel l’URI est ajouté, ou à l’utilisateur ou au service effectuant l’ajout.

Une fois cette protection activée, si une personne de votre organisation tente d’ajouter un URI d’identificateur personnalisé à une application v1, elle reçoit une erreur telle que :

The newly added URI {uri} must comply with the format 'api://{appId}' or 'api://{tenantId}/{appId}' as per the default app management policy of your organization. If the requestedAccessTokenVersion is set to 2, this restriction may not apply. See https://aka.ms/identifier-uri-addition-error for more information on this error.

Cette politique plus restrictive peut aider à protéger votre organisation contre les erreurs courantes de validation des jetons dans l'attribut audience. Nous vous recommandons de l’activer si possible, mais Microsoft ne l’active pas en votre nom.

Pour activer cette stratégie plus restrictive dans votre organisation, vous pouvez exécuter ce script.

À l’instar de l’autre stratégie, les administrateurs peuvent également accorder des exemptions à cette stratégie ou les désactiver une fois qu’elles ont été activées.

Questions fréquentes (FAQ)

Qu’est-ce que les URI d’identification ?

Les URI d’identificateur (également appelés « URI d’ID d’application ») permettent au développeur d’une ressource (API) de spécifier une valeur de chaîne pour leur application comme identificateur. Les clients qui obtiennent un jeton pour l’API peuvent utiliser cette valeur de chaîne pendant une requête OAuth. Par exemple, si une API avait configuré un URI d’identificateur, https://api.contoso.comles clients de l’API pouvaient spécifier cette valeur dans les requêtes OAuth adressées à Microsoft Entra. Cet URI d’identificateur est utilisé comme attribut audience dans les jetons d’accès v1.0.

Les URI d’identificateur sont configurés à l’aide de la page « Exposer une API » dans les inscriptions d’applications. Dans les enregistrements d’applications, l’URI d’identificateur est appelé URI d’ID d’application ; cela est synonyme d’URI d’identificateur.

Capture d’écran de l’expérience de configuration de l’URI d’identificateur.

Comment fonctionnent ces stratégies ?

Les mises en œuvre sont activées en configurant les stratégies de gestion des applications d’une organisation. Un administrateur client peut l’activer ou le désactiver. Microsoft l’active par défaut dans certaines organisations au cours des mois de juin et de juillet 2025.

Découvrez comment vérifier si la protection a été activée dans votre organisation

Même si Microsoft active ce paramètre par défaut, les administrateurs clients conservent le contrôle sur celui-ci. Ils peuvent l’activer, le désactiver ou lui accorder des exceptions.