Sdílet prostřednictvím

Omezení URI identifikátorů aplikací Microsoft Entra

Vlastnost identifierUri aplikace Microsoft Entra , označovaná také jako Application ID URI – je vlastnost obvykle nakonfigurovaná pro aplikace prostředků (API). Zabezpečená konfigurace této vlastnosti je důležitá pro zabezpečení prostředku.

Zabezpečené vzory

Podporují se následující formáty rozhraní API a identifikátoru URI ID aplikace založené na schématu HTTP. Nahraďte zástupné hodnoty, jak je popsáno v seznamu za tabulkou.

Podporované ID aplikace
Formáty identifikátorů URI		 Příklady identifikátorů URI ID aplikace
<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:// řetěd/><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:// řetěžka>.<verifiedCustomDomain> https://product.contoso.com
<https:// řetěžka>.<verifiedCustomDomain>/<string> https://product.contoso.com/productsapi
<api:// řetěsce>.<verifiedCustomDomainOrInitialDomain>/<string> api://contoso.com/productsapi
  • appId – vlastnost identifikátoru aplikace (appId<) objektu aplikace.>
  • <string> – hodnota řetězce pro hostitele nebo segment cesty rozhraní API.
  • <tenantId> – IDENTIFIKÁTOR GUID vygenerovaný v Azure, který představuje tenanta v Rámci Azure.
  • <tenantInitialDomain tenantInitialDomain.onmicrosoft.com> - <>, kde <tenantInitialDomain> je počáteční název domény tvůrce tenanta zadaný při vytváření tenanta.
  • <verifiedCustomDomain – Ověřená vlastní doména> nakonfigurovaná pro vašeho tenanta Microsoft Entra.

Poznámka:

Pokud použijete schéma api:// , přidáte řetězcovou hodnotu přímo za "api://". Například <.> Tato hodnota řetězce může být IDENTIFIKÁTOR GUID nebo libovolný řetězec. Pokud přidáte hodnotu GUID, musí se shodovat s ID aplikace nebo ID tenanta. Pokud použijete řetězcovou hodnotu, musí použít buď ověřenou vlastní doménu, nebo počáteční doménu vašeho tenanta. Doporučujeme použít api://< appId>.

Důležité

Hodnota identifikátoru URI ID aplikace nesmí končit znakem lomítka "/".

Důležité

Hodnota identifikátoru URI ID aplikace musí být v rámci vašeho tenanta jedinečná.

Vynucení zabezpečených vzorů pomocí zásad

Společnost Microsoft zavedla nastavení zabezpečení, které chrání před nezabezpečenou konfigurací identifikátorů URI (označovaných také jako identifikátory URI id aplikace) v aplikacích Microsoft Entra. Toto nastavení zabezpečení zajišťuje, aby nově přidané identifikátory URI v aplikacích v1 splňovaly výše uvedené vzory zabezpečení .

Chování zásad

Pokud je toto nastavení povolené, vynucují se zabezpečené vzory přísně. Pokud je tato možnost povolená, pokud se někdo ve vaší organizaci pokusí přidat identifikátor URI, který nevyhovuje zabezpečeným vzorům, zobrazí se jim chyba, například:

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.

Aplikace nakonfigurované tak, aby používaly tokeny Entra ID v2.0, jsou ve výchozím nastavení vyloučeny nastavením vlastnosti aplikace na api.requestedAccessTokenVersion. Aplikace nakonfigurované tak, aby používaly protokol SAML pro jednotné přihlašování nastavením preferredSingleSignOnMode vlastnosti instančního objektu na SAML, jsou také ve výchozím nastavení vyloučeny.

Stávající identifikátory URI, které už jsou v aplikaci nakonfigurované, nebudou ovlivněny a všechny aplikace budou dál fungovat jako normální. To ovlivní pouze nové aktualizace konfigurací aplikací Microsoft Entra.

Pokud není povolená, můžou se stále používat některé nezabezpečené vzory. Identifikátory URI formátu api://{string} se dají přidat i nadále. I když je ale nastavení zakázáno, může se i přesto v některých scénářích vyžadovat ověřený nájemce nebo počáteční doména – například při použití schématu https://.

Povolení a správa politiky

Microsoft už možná tuto zásadu ve vaší organizaci povolil, aby zlepšila zabezpečení. Tento skript můžete zkontrolovat spuštěním tohoto skriptu.

I když Microsoft povolil zásady ve vaší organizaci, správce tenanta nad ní stále má plnou kontrolu. Můžou udělit výjimky konkrétní aplikaci Microsoft Entra sami sobě, jinému uživateli v organizaci nebo jakékoli službě nebo procesu, který organizace používá. Nebo může správce zásadu zakázat (nedoporučuje se).

Microsoft zásady ve vaší organizaci nepovolí, pokud zjistí, že vaše organizace má procesy, které by mohly narušit změnu. Místo toho ho správce ve vaší organizaci může povolit sami (doporučeno).

Pokyny pro vývojáře

Tuto část si přečtěte, pokud jste vývojář a pokoušíte se přidat identifikátor URI (označovaný také jako identifikátor URI ID aplikace) do rozhraní Microsoft Entra API, které vlastníte, ale zobrazila se tato chyba.

Existují tři možné způsoby, jak do aplikace přidat identifikátor URI. Doporučujeme je v následujícím pořadí:

  1. Použití jednoho ze vzorů zabezpečených identifikátorů URI

  2. Pokud k této chybě došlo, znamená to, že vaše rozhraní API aktuálně používá tokeny v1.0. Můžete se odblokovat aktualizací služby tak, aby přijímala tokeny v2.0. Tokeny V2.0 se podobají verzi 1.0, ale existují určité rozdíly. cs-CZ: Jakmile bude vaše služba schopná zpracovat tokeny v2.0, můžete aktualizovat konfiguraci aplikace, aby jim Microsoft Entra posílal tokeny v2.0. Snadný způsob, jak to udělat, je prostřednictvím editoru manifestu v prostředí registrace aplikací v Centru pro správu Microsoft Entra:

    Snímek obrazovky s prostředím aktualizace verze tokenu

    Měli byste postupovat opatrně při provádění těchto změn. Důvodem je to, že jakmile je aplikace aktualizovaná na formát tokenu v2.0, nebude moct přepnout zpět na tokeny verze 1.0, pokud nemá nakonfigurované identifikátory URI nedodržující předpisy, pokud mu nebyla udělena výjimka (viz možnost 3).

  3. Pokud potřebujete do aplikace přidat identifikátor URI nedodržujícího předpisy, než budete moct aktualizovat formát tokenu v2.0, můžete požádat správce, aby aplikaci udělil výjimku.

Další nastavení zabezpečení

Microsoft také nabízí více omezující zásady zabezpečení pro identifierUris vlastnost. Tato přísnější zásada je nazývána nonDefaultUriAddition.

Pokud je tato ochrana povolená, nové URI vlastních identifikátorů se nedají přidat do žádné aplikace v této organizaci, s výjimkou známých bezpečných scénářů. Konkrétně platí, že pokud jsou splněny některé z následujících podmínek, je možné přidat identifikátor URI:

  • Identifikátor URI přidaný do aplikace je jedním z "výchozích" identifikátorů URI, což znamená, že je ve formátu api://{appId} nebo api://{tenantId}/{appId}
  • Aplikace přijímá v2.0 tokeny Entra. To platí, pokud je vlastnost aplikace api.requestedAccessTokenVersion nastavena na 2.
  • Aplikace používá protokol SAML pro jednotné přihlašování (SSO). To platí, pokud má služební principál pro aplikaci nastavenou vlastnost preferredSingleSignOnMode na SAML.
  • Výjimku udělil správce aplikaci, do které se přidává identifikátor URI, nebo uživateli nebo službě provádějícímu přidání.

Když je tato ochrana povolená, pokud se někdo z vaší organizace pokusí přidat do aplikace v1 vlastní identifikátor URI, zobrazí se jim chyba typu:

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.

Tato přísnější zásada může pomoct chránit vaši organizaci před běžnými chybami ověřování tokenů audience v deklaraci identity. Pokud je to možné, doporučujeme ho povolit, ale Microsoft ho vaším jménem nepovolí.

Pokud chcete tuto přísnější zásadu ve vaší organizaci povolit, můžete tento skript spustit.

Stejně jako ostatní zásady můžou správci také udělit výjimky této zásadě nebo je po povolení zakázat .

Nejčastější dotazy

Co jsou identifikátory URI?

Identifikátory URI (označované také jako identifikátory URI ID aplikace) umožňují vývojáři prostředku (API) zadat jako identifikátor řetězcovou hodnotu aplikace. Klienti, kteří získali token pro rozhraní API, můžou tuto hodnotu řetězce použít během požadavku OAuth. Například pokud by rozhraní API nakonfigurovalo identifikátor URI https://api.contoso.com, mohli by klienti tohoto rozhraní API tuto hodnotu zadat v požadavcích OAuth na Microsoft Entra. Tento identifikátor URI se používá jako deklarace identity cílové skupiny v přístupových tokenech v1.0.

Identifikátory URI se konfigurují pomocí stránky Vystavit rozhraní API v registracích aplikací. V registracích aplikací se identifikátor URI označuje jako URI ID aplikace; to je synonymum pro identifikátor URI.

Snímek obrazovky s prostředím konfigurace identifikátoru URI

Jak tyto zásady fungují?

Vynucení je zapnuté konfigurací zásad správy aplikací organizace. Správce tenanta ho může zapnout nebo vypnout. Microsoft ji ve výchozím nastavení povoluje v některých organizacích v měsících červen a červenec 2025.

Zjistěte, jak zkontrolovat, jestli je ve vaší organizaci povolená ochrana.

I když Microsoft toto nastavení ve výchozím nastavení povoluje, správci tenantů si toto nastavení zachovají pod kontrolou. Můžou ho zapnout, vypnout nebo udělit výjimce.