Dela via

Begränsningar för identifierar-URI:er för Microsoft Entra-program

Egenskapen identifierUri – även kallad Application ID URI – för ett Microsoft Entra-program är en egenskap som vanligtvis konfigureras för resursprogram (API). Att konfigurera den här egenskapen på ett säkert sätt är viktigt för resursens säkerhet.

Säkra mönster

Följande API- och HTTP-schemabaserade program-ID URI-format stöds. Ersätt platshållarvärdena enligt beskrivningen i listan som följer tabellen.

Program-ID som stöds
URI-format		 Exempel på app-ID-URI:er
<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:// verifieradCustomDomain>/<sträng> https://contoso.com/productsapi
<https:// sträng.><verifiedCustomDomain> https://product.contoso.com
<https:// sträng.><verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
<api:// sträng.><verifiedCustomDomainOrInitialDomain>/<string> api://contoso.com/productsapi
  • <appId> – programidentifieraregenskapen (appId) för programobjektet.
  • <string> – strängvärdet för värden eller api-sökvägssegmentet.
  • <tenantId> – ett GUID som genereras av Azure för att representera klientorganisationen i Azure.
  • < > , där - < är det första domännamnet som klientskapare angav när klientorganisationen skapades.
  • <verifiedCustomDomain> – en verifierad anpassad domän som konfigurerats för din Microsoft Entra-klientorganisation.

Anmärkning

Om du använder api:// -schemat lägger du till ett strängvärde direkt efter "api://". Till exempel api://< sträng.> Strängvärdet kan vara ett GUID eller en godtycklig sträng. Om du lägger till ett GUID-värde måste det matcha antingen app-ID:t eller klientorganisations-ID:t. Om du använder ett strängvärde måste det använda antingen en verifierad anpassad domän eller en ursprunglig domän för din klientorganisation. Rekommendationen är att använda api://< appId>.

Viktigt!

URI-värdet för program-ID får inte sluta med snedstrecket "/".

Viktigt!

URI-värdet för program-ID måste vara unikt i din klientorganisation.

Implementera säkra säkerhetsmönster med riktlinjer

Microsoft har infört en säkerhetsinställning som skyddar mot osäker konfiguration av identifierar-URI:er (kallas även app-ID-URI:er) i Microsoft Entra-program. Den här säkerhetsinställningen säkerställer att nyligen tillagda URI:er i v1-program följer de säkra mönster som beskrivs ovan.

Policybeteende

När den här inställningen är aktiverad tillämpas de säkra mönstren strikt. Om någon i din organisation försöker lägga till en identifierar-URI som inte följer de säkra mönstren får de ett felmeddelande som:

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.

Program som har konfigurerats för att använda v2.0 Entra-ID-token genom att ange api.requestedAccessTokenVersion egenskapen för programmet till 2, undantas som standard. Program som har konfigurerats för att använda SAML-protokollet för enkel inloggning genom att ange preferredSingleSignOnMode egenskapen för tjänstens huvudnamn till SAML, undantas också som standard.

Befintliga identifierar-URI:er som redan har konfigurerats i appen påverkas inte och alla appar fortsätter att fungera som vanligt. Detta påverkar bara nya uppdateringar av Microsoft Entra-appkonfigurationer.

När den inte är aktiverad kan vissa osäkra mönster fortfarande användas. Till exempel kan URI:er för formatet api://{string} fortfarande läggas till. Men även när inställningen är inaktiverad kan en verifierad klient eller en initial domän fortfarande krävas i vissa scenarier, till exempel när du använder schemat https://.

Aktivera och hantera principen

Microsoft kanske redan har aktiverat den här principen i din organisation för att förbättra säkerheten. Du kan kontrollera genom att köra det här skriptet.

Även om Microsoft har aktiverat principen i din organisation har en innehavaradministratör fortfarande fullständig kontroll över den. De kan bevilja undantag till ett specifikt Microsoft Entra-program, till sig själva, till en annan användare i organisationen eller till någon tjänst eller process som organisationen använder. Eller så kan en administratör inaktivera principen (rekommenderas inte).

Microsoft aktiverar inte principen i din organisation om den upptäcker att din organisation har processer som kan störas av ändringen. I stället kan en administratör i din organisation aktivera det själva (rekommenderas).

Vägledning för utvecklare

Läs det här avsnittet om du är utvecklare och försöker lägga till en identifierar-URI (även kallat app-ID-URI) till ett Microsoft Entra-API som du äger, men du fick det här felet.

Det finns tre möjliga sätt att lägga till en identifierar-URI i din app. Vi rekommenderar dem i följande ordning:

  1. Använd ett av de säkra URI-mönstren

  2. Om du påträffade det här felet innebär det att ditt API för närvarande använder v1.0-token. Du kan avblockera dig själv genom att uppdatera tjänsten för att acceptera v2.0-token. V2.0-token liknar v1.0, men det finns vissa skillnader. När tjänsten har hanterat v2.0-token kan du uppdatera appkonfigurationen så att Microsoft Entra skickar v2.0-token. Ett enkelt sätt att göra detta är via manifestredigeraren i Microsoft Entra administrationscenter Appregistreringsupplevelse:

    Skärmbild av upplevelsen för uppdateringstokens version.

    Du bör dock fortsätta med försiktighet när du gör den här ändringen. Detta beror på att när appen har uppdaterats till v2.0-tokenformatet kommer den inte att kunna växla tillbaka till v1.0-token om den har inkompatibla identifierar-URI:er konfigurerade, såvida den inte har beviljats ett undantag (se alternativ 3).

  3. Om du behöver lägga till en icke-kompatibel identifierar-URI i din app innan du kan uppdatera till v2.0-tokenformatet kan du be administratören att bevilja appen ett undantag.

Ytterligare säkerhetsinställningar

Microsoft erbjuder också en mer restriktiv säkerhetsprincip för egenskapen identifierUris . Den här mer restriktiva principen kallas nonDefaultUriAddition.

När det här skyddet är aktiverat kan nya URI:er för anpassade identifierare inte läggas till i något program i organisationen, förutom i kända säkra scenarier. Mer specifikt, om något av följande villkor är uppfyllt, kan en identifierar-URI fortfarande läggas till:

  • Identifierar-URI:n som läggs till i appen är en av URI:erna "standard", vilket innebär att den är i formatet api://{appId} eller api://{tenantId}/{appId}
  • Appen accepterar v2.0 Entra-token. Detta gäller om appens api.requestedAccessTokenVersion egenskap är inställd på 2.
  • Appen använder SAML-protokollet för enkel inloggning (SSO). Detta gäller om tjänstens huvudnamn för appen har sin preferredSingleSignOnMode egenskap inställd på SAML.
  • Ett undantag har beviljats av en administratör för appen som URI:n läggs till i eller till den användare eller tjänst som utför tillägget.

Om någon i organisationen försöker lägga till en anpassad identifierar-URI i ett v1-program när det här skyddet är aktiverat får de ett felmeddelande som:

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.

Den här mer restriktiva principen kan hjälpa dig att skydda din organisation från vanliga tokenvalideringsfel i anspråket audience . Vi rekommenderar att du aktiverar det om möjligt, men Microsoft aktiverar det inte för din räkning.

Om du vill aktivera den här mer restriktiva principen i din organisation kan du köra det här skriptet.

Precis som den andra principen kan administratörer också bevilja undantag till den här principen eller inaktivera den när den har aktiverats.

Vanliga frågor

Vad är identifierar-URI:er?

Identifierar-URI:er (kallas även app-ID-URI:er) gör det möjligt för en resursutvecklare (API) att ange ett strängvärde för sitt program som identifierare. Klienter som hämtar en token för API:et kan använda det här strängvärdet under en OAuth-begäran. Om ett API till exempel hade konfigurerat en identifierar-URI https://api.contoso.comför kan klienter i API:et ange det värdet i OAuth-begäranden till Microsoft Entra. Den här URI:n används som målgruppspåstående i v1.0-åtkomsttokenen.

Identifierar-URI:er konfigureras med hjälp av sidan Exponera ett API i appregistreringar. I Appregistreringar kallas identifierar-URI:n för en program-ID-URI. detta är synonymt med identifierar-URI.

Skärmbild av URI-konfigurationsupplevelsen för identifierare.

Hur fungerar dessa principer?

Tvingande åtgärder aktiveras genom att konfigurera en organisations apphanteringsprinciper. En klientadministratör kan aktivera eller inaktivera den. Microsoft aktiverar det som standard i vissa organisationer under månaderna juni och juli 2025.

Lär dig hur du kontrollerar om skyddet har aktiverats i din organisation

Även om Microsoft aktiverar den här inställningen som standard behåller innehavaradministratörerna kontrollen över den. De kan aktivera, inaktivera eller bevilja undantag till den.