Ograniczenia dotyczące identyfikatorów URI aplikacji firmy Microsoft Entra

Właściwość identifierUri , nazywana Application ID URI również właściwością aplikacji Microsoft Entra, jest zazwyczaj skonfigurowana w aplikacjach zasobów (API). Bezpieczne konfigurowanie tej właściwości ma kluczowe znaczenie dla zabezpieczeń zasobu.

Bezpieczne wzorce

Obsługiwane są następujące formaty identyfikatorów URI identyfikatora aplikacji opartego na schematach HTTP i interfejsu API. Zastąp wartości symboli zastępczych zgodnie z opisem na liście poniżej tabeli.

Identyfikator obsługiwanej aplikacji Formaty identyfikatora URI	Przykładowe identyfikatory URI identyfikatorów aplikacji
<api:// appId>	api://00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<appId>	api://aaaabbbb-0000-cccc-1111-dddd2222eeee/00001111-aaaa-2222-bbbb-3333cccc4444
<api:// tenantId>/<ciąg>	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:// zweryfikowaneCustomDomain>/<ciąg>	https://contoso.com/productsapi
<https:// ciąg.><verifiedCustomDomain>	https://product.contoso.com
<https:// ciąg.><verifiedCustomDomain>/<string>	https://product.contoso.com/productsapi
<api:// ciąg.><verifiedCustomDomainOrInitialDomain>/<string>	api://contoso.com/productsapi

• <appId> — właściwość identyfikatora aplikacji (appId) obiektu aplikacji.
• <string> — wartość ciągu dla hosta lub segmentu ścieżki interfejsu API.
• <tenantId> — identyfikator GUID wygenerowany przez platformę Azure do reprezentowania dzierżawy na platformie Azure.
• < > , gdzie - < jest początkową nazwą domeny twórcą dzierżawy określonym podczas tworzenia dzierżawy.
• <verifiedCustomDomain> — zweryfikowana domena niestandardowa skonfigurowana dla dzierżawy firmy Microsoft Entra.

Uwaga / Notatka

Jeśli używasz schematu api:// , należy dodać wartość ciągu bezpośrednio po "api://". Na przykład api://< ciąg.> Ta wartość ciągu może być identyfikatorem GUID lub dowolnym ciągiem. Jeśli dodasz wartość identyfikatora GUID, musi być zgodna z identyfikatorem aplikacji lub identyfikatorem dzierżawy. Jeśli używasz wartości ciągu, musi ona używać zweryfikowanej domeny niestandardowej lub początkowej domeny dzierżawy. Zaleceniem jest użycie identyfikatora api://< appId>.

Ważne

Wartość identyfikatora URI identyfikatora aplikacji nie może kończyć się ukośnikiem "/".

Ważne

Wartość identyfikatora URI identyfikatora aplikacji musi być unikatowa w dzierżawie.

Wymuszanie bezpiecznych wzorców za pomocą zasad

Firma Microsoft wprowadziła ustawienie zabezpieczeń chroniące przed niezabezpieczoną konfiguracją identyfikatorów URI (nazywanych również identyfikatorami URI aplikacji) w aplikacjach Microsoft Entra. To ustawienie zabezpieczeń gwarantuje, że nowo dodane identyfikatory URI w aplikacjach w wersji 1 są zgodne z powyższymi bezpiecznymi wzorcami .

Zachowanie zasad

Po włączeniu tego ustawienia bezpieczne wzorce są ściśle wymuszane. Po włączeniu tej opcji, jeśli ktoś w twojej organizacji spróbuje dodać identyfikator URI, który nie jest zgodny z bezpiecznymi wzorcami, zostanie wyświetlony błąd, taki jak:

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.

Aplikacje skonfigurowane do używania tokenów Entra ID w wersji 2.0, ustawiając api.requestedAccessTokenVersion właściwość aplikacji na 2, są domyślnie wykluczone. Aplikacje skonfigurowane do używania protokołu SAML do SSO (jednokrotne logowanie) przez ustawienie właściwości jednostki usługi na wartość preferredSingleSignOnMode, są również domyślnie wykluczone.

Istniejące identyfikatory URI skonfigurowane już w aplikacji nie będą miały wpływu, a wszystkie aplikacje będą nadal działać normalnie. Będzie to miało wpływ tylko na nowe aktualizacje konfiguracji aplikacji Microsoft Entra.

Jeśli nie jest włączona, niektóre niezabezpieczone wzorce mogą być nadal używane. Na przykład można nadal dodawać adresy URI w formacie api://{string}. Jednak nawet jeśli to ustawienie jest wyłączone, w niektórych scenariuszach nadal może być wymagana potwierdzona dzierżawa lub domena początkowa — na przykład podczas używania schematu https://.

Włączanie polityki i zarządzanie nią

Firma Microsoft mogła już włączyć te zasady w organizacji w celu zwiększenia bezpieczeństwa. Możesz to sprawdzić, uruchamiając ten skrypt.

Nawet jeśli firma Microsoft włączyła zasadę w organizacji, administrator dzierżawy nadal ma nad nią pełną kontrolę. Mogą przyznawać wyjątki dla określonej aplikacji Microsoft Entra, dla siebie, innemu użytkownikowi w organizacji lub dowolnej usłudze lub procesowi używanemu przez organizację. Lub administrator może wyłączyć zasady (niezalecane).

Firma Microsoft nie włączy zasad w organizacji, jeśli wykryje, że Organizacja ma procesy, które mogą zostać zakłócone przez zmianę. Zamiast tego administrator w organizacji może włączyć go samodzielnie (zalecane).

Wskazówki dla deweloperów

Przeczytaj tę sekcję, jeśli jesteś deweloperem i próbujesz dodać identyfikator URI (znany również jako identyfikator URI aplikacji) do własnego interfejsu API Microsoft Entra, ale pojawił się ten błąd.

Istnieją trzy możliwe sposoby, aby dodać identyfikator URI do swojej aplikacji. Zalecamy je w następującej kolejności:

1. Używanie jednego z bezpiecznych wzorców identyfikatora URI

2. Jeśli wystąpi ten błąd, oznacza to, że interfejs API używa obecnie tokenów w wersji 1.0. Możesz odblokować się, aktualizując usługę w celu akceptowania tokenów w wersji 2.0. Tokeny w wersji 2.0 są podobne do wersji 1.0, ale istnieją pewne różnice. Gdy usługa będzie mogła obsługiwać tokeny w wersji 2.0, możesz zaktualizować konfigurację aplikacji, aby firma Microsoft Entra wysyłała tokeny w wersji 2.0. W tym celu można łatwo wykonać czynności za pomocą edytora manifestu w środowisku rejestracji aplikacji centrum administracyjnego firmy Microsoft Entra:

   

   Należy jednak zachować ostrożność podczas wprowadzania tej zmiany. Dzieje się tak dlatego, że po zaktualizowaniu aplikacji do formatu tokenu w wersji 2.0 nie będzie można przełączyć się z powrotem do tokenów w wersji 1.0, jeśli ma skonfigurowane niezgodne identyfikatory URI, chyba że przyznano mu wykluczenie (zobacz opcję 3).

3. Jeśli musisz dodać do aplikacji niezgodny identyfikator URI, zanim będzie można zaktualizować go do formatu tokenu w wersji 2.0, możesz poprosić administratora o przyznanie aplikacji wykluczenia.

Dodatkowe ustawienia zabezpieczeń

Firma Microsoft oferuje również bardziej restrykcyjną politykę zabezpieczeń dla identifierUris właściwości. Ta bardziej restrykcyjna polityka jest nazywana nonDefaultUriAddition.

Po włączeniu tej ochrony, nowe niestandardowe URI nie mogą być dodawane do żadnej aplikacji w tej organizacji, z wyjątkiem znanych bezpiecznych scenariuszy. Szczególnie, jeśli którykolwiek z następujących warunków zostanie spełniony, nadal można dodać identyfikator URI.

• Identyfikator URI dodawany do aplikacji jest jednym z domyślnych identyfikatorów URI, co oznacza, że jest w formacie api://{appId} lub api://{tenantId}/{appId}
• Aplikacja akceptuje v2.0 tokeny Entra. Jest to prawda, jeśli właściwość aplikacji api.requestedAccessTokenVersion jest ustawiona na 2.
• Aplikacja używa protokołu SAML do logowania jednokrotnego. Jest to prawda, jeśli jednostka usługi dla aplikacji ma swoją właściwość preferredSingleSignOnMode ustawioną na SAML.
• Administrator udzielił zwolnienia aplikacji, do której dodawany jest identyfikator URI, lub użytkownikowi lub usłudze wykonującej to dodanie.

Po włączeniu tej ochrony, jeśli ktoś w Twojej organizacji spróbuje dodać niestandardowy identyfikator URI do aplikacji w wersji 1, zostanie wyświetlony błąd, jak na przykład:

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.

Te bardziej restrykcyjne zasady mogą pomóc chronić organizację przed typowymi błędami weryfikacji tokenów w oświadczeniu audience . Zalecamy włączenie go, jeśli to możliwe, ale firma Microsoft nie włączy jej w Twoim imieniu.

Aby włączyć te bardziej restrykcyjne zasady w organizacji, możesz uruchomić ten skrypt.

Podobnie jak inne zasady, administratorzy mogą również udzielać wykluczeń tym zasadom lub wyłączać je po jej włączeniu.

Często zadawane pytania

Co to są identyfikatory URI?

Identyfikatory URI (nazywane także URI identyfikatora aplikacji) pozwalają deweloperowi zasobów (API) określić wartość ciągu znaków jako identyfikator aplikacji. Klienci, którzy uzyskują token dla interfejsu API, mogą używać tej wartości ciągu podczas żądania OAuth. Jeśli na przykład interfejs API skonfigurował identyfikator URI https://api.contoso.com, klienci tego interfejsu API mogliby określić tę wartość w żądaniach OAuth do Microsoft Entra. Ten identyfikator URI jest używany jako oświadczenie odbiorców w tokenach dostępu w wersji 1.0.

Identyfikatory URI są konfigurowane przy użyciu strony "Uwidacznianie interfejsu API" w rejestracjach aplikacji. W obszarze Rejestracje aplikacji identyfikator URI jest określany jako URI aplikacji; jest to synonim identyfikatora URI.

Jak działają te zasady?

Wymuszanie jest włączane przez skonfigurowanie zasad zarządzania aplikacjami organizacji. Administrator dzierżawy może ją włączyć lub wyłączyć. Firma Microsoft domyślnie włącza ją w niektórych organizacjach w miesiącach czerwca i lipca 2025 r.

Dowiedz się, jak sprawdzić, czy ochrona została włączona w organizacji

Mimo że firma Microsoft domyślnie włącza to ustawienie, administratorzy dzierżawy zachowują kontrolę nad tym ustawieniem. Mogą włączać, wyłączać lub udzielać wyjątków.