Beperkingen voor id-URI's van Microsoft Entra-toepassingen

De identifierUri - ook wel bekend als Application ID URI - eigenschap van een Microsoft Entra-toepassing is een eigenschap die doorgaans is geconfigureerd voor resourcetoepassingen (API). Het veilig configureren van deze eigenschap is essentieel voor de beveiliging van de resource.

Veilige patronen

De volgende URI-indelingen voor toepassings-id's op basis van API- en HTTP-schema’s worden ondersteund. Vervang de waarden van de tijdelijke aanduidingen zoals beschreven in de lijst onder de tabel.

Ondersteunde toepassings-id URI-indelingen	Voorbeelden van URI’s van toepassings-id’s
<api:// appId>	api://00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<appId>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<tekenreeks>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/api
<api:// tekenreeks>/<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:// tekenreeks>.<verifiedCustomDomain>	https://product.contoso.com
<https:// tekenreeks>.<verifiedCustomDomain>/<string>	https://product.contoso.com/productsapi
<api:// tekenreeks>.<verifiedCustomDomainOrInitialDomain>/<string>	api://contoso.com/productsapi

• <appId>: de eigenschap van de toepassings-id (appId) van het toepassingsobject.
• <string>: de tekenreekswaarde voor de host of het API-padsegment.
• <tenantId>: een GUID die door Azure wordt gegenereerd om de tenant in Azure weer te geven.
• <tenantInitialDomain> - <tenantInitialDomain.onmicrosoft.com>, waarbij <tenantInitialDomain> de initiële domeinnaam is die de maker van de tenant heeft opgegeven bij het maken van de tenant.
• <verifiedCustomDomain> : een geverifieerd aangepast domein dat is geconfigureerd voor uw Microsoft Entra-tenant.

Opmerking

Als u het api://-schema gebruikt, voegt u direct na api:// een tekenreekswaarde toe. Bijvoorbeeld: api://<tekenreeks>. Deze tekenreekswaarde kan een GUID of een willekeurige tekenreeks zijn. Als u een GUID-waarde toevoegt, moet deze overeenkomen met de app-id of de tenant-id. Als u een tekenreekswaarde gebruikt, moet deze een geverifieerd aangepast domein of een oorspronkelijk domein van uw tenant gebruiken. De aanbeveling is om api://< appId> te gebruiken.

Belangrijk

De URI-waarde van de toepassings-id mag niet eindigen met een slash "/"-teken.

Belangrijk

De URI-waarde van de toepassings-id moet uniek zijn binnen uw tenant.

Veilige patronen afdwingen met beleid

Microsoft heeft een beveiligingsinstelling geïntroduceerd die beschermt tegen onveilige configuratie van id-URI's (ook wel app-id-URI's genoemd) in Microsoft Entra-toepassingen. Deze beveiligingsinstelling zorgt ervoor dat nieuw toegevoegde URI's in v1-toepassingen voldoen aan de hierboven beschreven veilige patronen .

Gedrag van beleid

Wanneer deze instelling is ingeschakeld, worden de veilige patronen strikt afgedwongen. Wanneer ingeschakeld, als iemand in uw organisatie een identificatie-URI probeert toe te voegen die niet voldoet aan de beveiligde patronen, krijgt deze een foutmelding zoals:

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.

Toepassingen die zijn geconfigureerd voor het gebruik van v2.0 Entra ID-tokens, door de api.requestedAccessTokenVersion eigenschap van de toepassing in te 2stellen, worden standaard uitgesloten. Toepassingen die geconfigureerd zijn om het SAML-protocol voor eenmalige aanmelding te gebruiken, door de preferredSingleSignOnMode eigenschap van de service-principal in te stellen op SAML, worden ook standaard uitgesloten.

De bestaande id-URI's die al in de app zijn geconfigureerd, worden niet beïnvloed en alle apps blijven werken als normaal. Dit is alleen van invloed op nieuwe updates voor app-configuraties van Microsoft Entra.

Wanneer deze niet is ingeschakeld, kunnen sommige onveilige patronen nog steeds worden gebruikt. URI's van de indeling api://{string} kunnen bijvoorbeeld nog steeds worden toegevoegd. Zelfs wanneer de instelling is uitgeschakeld, kan een geverifieerde of initiële tenant nog steeds vereist zijn in sommige scenario's, bijvoorbeeld wanneer u het https:// schema gebruikt.

Het beleid inschakelen en beheren

Microsoft heeft dit beleid mogelijk al ingeschakeld in uw organisatie om de beveiliging te verbeteren. U kunt dit controleren door dit script uit te voeren.

Zelfs als Microsoft het beleid in uw organisatie heeft ingeschakeld, heeft een tenantbeheerder nog steeds volledige controle over het beleid. Ze kunnen uitzonderingen verlenen aan een specifieke Microsoft Entra-toepassing, aan zichzelf, aan een andere gebruiker in de organisatie of aan een service of proces dat de organisatie gebruikt. Of een beheerder kan het beleid uitschakelen (niet aanbevolen).

Microsoft schakelt het beleid in uw organisatie niet in als het detecteert dat uw organisatie processen heeft die mogelijk worden onderbroken door de wijziging. In plaats daarvan kan een beheerder in uw organisatie deze zelf inschakelen (aanbevolen).

Richtlijnen voor ontwikkelaars

Lees deze sectie als u een ontwikkelaar bent en u probeert een id-URI (ook wel app-id-URI genoemd) toe te voegen aan een Microsoft Entra-API die u bezit, maar u hebt deze fout ontvangen.

Er zijn drie mogelijke manieren waarop u een id-URI aan uw app kunt toevoegen. We raden ze aan in de volgende volgorde:

1. Een van de beveiligde URI-patronen gebruiken

2. Als u deze fout hebt aangetroffen, betekent dit dat uw API momenteel v1.0-tokens gebruikt. U kunt uzelf deblokkeren door uw service bij te werken om v2.0-tokens te accepteren. V2.0-tokens zijn vergelijkbaar met v1.0, maar er zijn enkele verschillen. Zodra uw service v2.0-tokens kan verwerken, kunt u uw app-configuratie bijwerken zodat Microsoft Entra deze v2.0-tokens verzendt. Een eenvoudige manier om dit te doen, is via de manifesteditor in de App Registraties-ervaring van het Microsoft Entra-beheercentrum:

   

   Wees echter voorzichtig bij het aanbrengen van deze wijziging. Dit komt omdat nadat de app is bijgewerkt naar de v2.0-tokenindeling, deze niet meer kan worden teruggezet naar v1.0-tokens als er niet-compatibele id-URI's zijn geconfigureerd, tenzij er een uitzondering is verleend (zie optie 3).

3. Als u een niet-compatibele id-URI aan uw app moet toevoegen voordat u de v2.0-tokenindeling kunt bijwerken, kunt u de beheerder vragen om uw app een uitzondering te verlenen.

Aanvullende beveiligingsinstellingen

Microsoft biedt ook een meer beperkend beveiligingsbeleid voor de identifierUris eigenschap. Dit meer beperkende beleid wordt genoemd nonDefaultUriAddition.

Wanneer deze beveiliging is ingeschakeld, kunnen nieuwe aangepaste id-URI's niet worden toegevoegd aan een toepassing in die organisatie, met uitzondering van bekende veilige scenario's. Als aan een van de volgende voorwaarden wordt voldaan, kan er nog steeds een id-URI worden toegevoegd:

• De id-URI die aan de app wordt toegevoegd, is een van de 'standaard'-URI's, wat betekent dat deze de indeling heeft of api://{appId}api://{tenantId}/{appId}
• De app accepteert v2.0 Entra-tokens. Dit is waar als de eigenschap van api.requestedAccessTokenVersion de app is ingesteld op 2.
• De app maakt gebruik van het SAML-protocol voor eenmalige aanmelding (SSO). Dit geldt als de service-principal voor de app de preferredSingleSignOnMode eigenschap heeft ingesteld op SAML.
• Er is een uitzondering verleend door een beheerder aan de app waaraan de URI wordt toegevoegd of aan de gebruiker of service die de toevoeging uitvoert.

Zodra deze beveiliging is ingeschakeld, zal iedereen in uw organisatie die probeert een aangepaste id-URI aan een v1-toepassing toe te voegen, een foutmelding ontvangen zoals:

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.

Dit meer beperkende beleid kan uw organisatie helpen beschermen tegen veelvoorkomende tokenvalidatiefouten in de audience claim. U wordt aangeraden deze indien mogelijk in te schakelen, maar Microsoft schakelt dit niet namens u in.

Als u dit meer beperkende beleid in uw organisatie wilt inschakelen, kunt u dit script uitvoeren.

Net als bij het andere beleid kunnen beheerders ook uitzonderingen aan dit beleid verlenen of uitschakelen nadat het is ingeschakeld.

Veelgestelde vragen

Wat zijn id-URI's?

Met id-URI's (ook wel 'App ID URI's' genoemd) kan een resourceontwikkelaar (API) een tekenreekswaarde voor de toepassing opgeven als id. Clients die een token voor de API verkrijgen, kunnen deze tekenreekswaarde gebruiken tijdens een OAuth-aanvraag. Als een API bijvoorbeeld een id-URI https://api.contoso.comvan had geconfigureerd, kunnen clients van de API die waarde opgeven in OAuth-aanvragen voor Microsoft Entra. Deze identificatie-URI wordt gebruikt als de "audience claim" in v1.0-toegangstokens.

Id-URI's worden geconfigureerd met behulp van de pagina 'Een API beschikbaar maken' in app-registraties. In app-registraties wordt de id-URI aangeduid als een toepassings-id-URI; dit staat synoniem voor id-URI.

Hoe werken deze beleidsregels?

De afdwingingen worden ingeschakeld door het beleid voor app-beheer van een organisatie te configureren. Een tenantbeheerder kan deze in- of uitschakelen. Microsoft schakelt het standaard in bij sommige organisaties in de maanden juni en juli 2025.

Meer informatie over het controleren of de beveiliging is ingeschakeld in uw organisatie

Hoewel Microsoft deze instelling standaard inschakelt, behouden tenantbeheerders de controle over deze instelling. Ze kunnen het in- of uitschakelen of uitzonderingen hierop verlenen.