Freigeben über

Einschränkungen für Bezeichner-URIs von Microsoft Entra-Anwendungen

Die identifierUri-Eigenschaft einer Microsoft Entra-Anwendung wird auch als Application ID URI bezeichnet und ist in der Regel für Ressourcenanwendungen (API) konfiguriert. Die sichere Konfiguration dieser Eigenschaft ist für die Sicherheit der Ressource von entscheidender Bedeutung.

Sichere Muster

Für Anwendungs-IDs auf Basis von API- oder HTTP-Schemas werden die folgenden URI-Formate unterstützt. Ersetzen Sie die Platzhalterwerte gemäß der Liste, die der Tabelle folgend aufgeführt ist.

Unterstützte Anwendungs-ID
URI-Formate		 URIs für Beispiel-App-IDs
api://<appId> api://aaaabbbb-0000-cccc-1111-dddd2222eeee
<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>: Die AppId-Eigenschaft (Anwendungsbezeichner) des Anwendungsobjekts.
  • <string>: Der Zeichenfolgenwert für den Host oder das API-Pfadsegment.
  • <tenantId>: Eine von Azure generierte GUID, die den Mandanten in Azure repräsentiert.
  • <tenantInitialDomain> - <tenantInitialDomain>.onmicrosoft.com, wobei <tenantInitialDomain> der anfängliche Domänenname ist, den der Mandantenersteller bei der Mandantenerstellung angegeben hat.
  • <verifiedCustomDomain> – eine überprüfte benutzerdefinierte Domäne, die für Ihren Microsoft Entra-Mandanten konfiguriert ist.

Hinweis

Wenn Sie das api:// Schema verwenden, fügen Sie direkt nach dem "api://" einen Zeichenfolgenwert hinzu. Beispiel: api://<Zeichenfolge>. Dieser Zeichenfolgenwert kann eine GUID oder eine beliebige Zeichenfolge sein. Wenn Sie einen GUID-Wert hinzufügen, muss er entweder mit der App-ID oder der Mandanten-ID übereinstimmen. Wenn Sie einen Zeichenfolgenwert verwenden, muss er entweder eine überprüfte benutzerdefinierte Domäne oder die ursprüngliche Domäne Ihres Mandanten verwenden. Es wird empfohlen, api://< appId> zu verwenden.

Von Bedeutung

Der Wert für den Anwendungs-ID-URI darf nicht mit einem Schrägstrich (/) enden.

Von Bedeutung

Der URI-Wert der Anwendungs-ID muss innerhalb Ihres Mandanten eindeutig sein.

Durchsetzen sicherer Muster durch Richtlinien

Microsoft hat eine Sicherheitseinstellung eingeführt, die vor unsicherer Konfiguration von Bezeichner-URIs (auch als "App-ID-URIs" bezeichnet) in Microsoft Entra-Anwendungen schützt. Diese Sicherheitseinstellung stellt sicher, dass neu hinzugefügte URIs in v1-Anwendungen den oben beschriebenen sicheren Mustern entsprechen.

Richtlinienverhalten

Wenn diese Einstellung aktiviert ist, werden die sicheren Muster streng erzwungen. Wenn diese Einstellung aktiviert ist, wird, falls eine Person in Ihrer Organisation versucht, einen Bezeichner-URI hinzuzufügen, der nicht den sicheren Mustern entspricht, folgende Fehlermeldung angezeigt:

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.

Anwendungen, die für die Verwendung von v2.0 Entra-ID-Token konfiguriert sind, durch Festlegen der api.requestedAccessTokenVersion Eigenschaft der Anwendung auf 2, werden standardmäßig ausgenommen. Anwendungen, die für die Verwendung des SAML-Protokolls für SSO konfiguriert sind, indem die Eigenschaft preferredSingleSignOnMode des Dienstprinzipals auf SAML gesetzt wird, werden standardmäßig ebenfalls ausgenommen.

Vorhandene Bezeichner-URIs, die bereits in der App konfiguriert sind, sind nicht betroffen, und alle Apps funktionieren weiterhin normal. Dies wirkt sich nur auf neue Updates für Microsoft Entra-App-Konfigurationen aus.

Wenn sie nicht aktiviert ist, können einige unsichere Muster weiterhin verwendet werden. URIs des Formats api://{string} können z. B. weiterhin hinzugefügt werden. Selbst wenn die Einstellung deaktiviert ist, ist in einigen Szenarien möglicherweise noch eine überprüfte oder anfängliche Domäne erforderlich, zum Beispiel bei der Verwendung des https:// Schemas.

Aktivieren und Verwalten der Richtlinie

Microsoft hat diese Richtlinie möglicherweise bereits in Ihrer Organisation aktiviert, um die Sicherheit zu verbessern. Sie können überprüfen, indem Sie dieses Skript ausführen.

Auch wenn Microsoft die Richtlinie in Ihrer Organisation aktiviert hat, hat ein Mandantenadministrator weiterhin die volle Kontrolle darüber. Sie können Ausnahmen gewähren für eine bestimmte Microsoft Entra-Anwendung, für sich selbst, für einen anderen Benutzer in der Organisation oder für jeden Dienst oder Prozess, den die Organisation verwendet. Oder ein Administrator kann die Richtlinie deaktivieren (nicht empfohlen).

Microsoft aktiviert die Richtlinie in Ihrer Organisation nicht, wenn sie erkennt, dass Ihre Organisation Prozesse aufweist, die möglicherweise durch die Änderung gestört werden. Stattdessen kann ein Administrator in Ihrer Organisation es selbst aktivieren (empfohlen).

Leitfaden für Entwickler

Lesen Sie diesen Abschnitt, wenn Sie Entwickler sind, und Sie versuchen, einen Bezeichner-URI (auch als App-ID-URI bezeichnet) zu einer Microsoft Entra-API hinzuzufügen, die Sie besitzen, aber Sie haben diesen Fehler erhalten.

Es gibt drei mögliche Möglichkeiten, wie Sie Ihrer App einen Bezeichner-URI hinzufügen können. Wir empfehlen Ihnen in der folgenden Reihenfolge:

  1. Verwenden eines der sicheren URI-Muster

  2. Wenn dieser Fehler aufgetreten ist, bedeutet dies, dass Ihre API derzeit v1.0-Token verwendet. Sie können die Blockierung selbst aufheben, indem Sie Ihren Dienst so aktualisieren, dass v2.0-Token akzeptiert werden. V2.0-Token ähneln v1.0, aber es gibt einige Unterschiede. Sobald Ihr Dienst in der Lage ist, v2.0-Token zu verarbeiten, können Sie Ihre App-Konfiguration aktualisieren, damit Microsoft Entra Ihnen v2.0-Token sendet. Der Manifest-Editor im Microsoft Entra Admin Center App-Registrierungsbereich bietet eine einfache Möglichkeit hierfür:

    Screenshot der Token-Update-Versionserfahrung.

    Sie sollten jedoch vorsichtig vorgehen, wenn Sie diese Änderung vornehmen. Dies liegt daran, dass die App, nachdem sie auf das v2.0-Tokenformat aktualisiert wurde, nicht zurück zu v1.0-Token wechseln kann, wenn sie nicht kompatible Bezeichner-URIs konfiguriert hat, es sei denn, sie wurde eine Ausnahme gewährt (siehe Option 3).

  3. Wenn Sie Ihrer App einen nicht kompatiblen Bezeichner-URI hinzufügen müssen, bevor Sie das v2.0-Tokenformat aktualisieren können, können Sie den Administrator bitten, Ihrer App eine Ausnahme zu gewähren.

Zusätzliche Sicherheitseinstellungen

Microsoft bietet auch eine restriktivere Sicherheitsrichtlinie für die identifierUris Eigenschaft an. Diese restriktivere Richtlinie wird genannt nonDefaultUriAddition.

Wenn dieser Schutz aktiviert ist, können neue benutzerdefinierte Bezeichner-URIs keiner Anwendung in dieser Organisation hinzugefügt werden, mit Ausnahme bekannter sicherer Szenarien. Wenn eine der folgenden Bedingungen erfüllt ist, kann weiterhin ein Bezeichner-URI hinzugefügt werden:

  • Der Bezeichner-URI, der der App hinzugefügt wird, ist einer der 'default' URIs, was bedeutet, dass er im Format api://{appId} oder api://{tenantId}/{appId} vorliegt.
  • Die App akzeptiert v2.0 Entra-Token. Dies gilt, wenn die Eigenschaft der App api.requestedAccessTokenVersion auf 2 festgelegt ist.
  • Die App verwendet das SAML-Protokoll für einmaliges Anmelden (Single Sign-On, SSO). Dies gilt, wenn der Dienstprinzipal für die App seine preferredSingleSignOnMode Eigenschaft auf SAML setzt.
  • Eine Ausnahmegenehmigung wurde von einem Administrator für die App, zu der der URI hinzugefügt wird, oder für den Benutzer oder Dienst, der die Hinzufügung ausführt, erteilt.

Sobald dieser Schutz aktiviert ist, wird eine Fehlermeldung angezeigt, wenn jemand in Ihrer Organisation versucht, einer v1-Anwendung einen benutzerdefinierten Bezeichner-URI hinzuzufügen:

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.

Diese restriktivere Richtlinie kann Dazu beitragen, Ihre Organisation vor allgemeinen Tokenüberprüfungsfehlern im audience Anspruch zu schützen. Es wird empfohlen, dies nach Möglichkeit zu aktivieren, aber Microsoft aktiviert sie nicht in Ihrem Auftrag.

Um diese restriktivere Richtlinie in Ihrer Organisation zu aktivieren, können Sie dieses Skript ausführen.

Wie die andere Richtlinie können Administratoren auch Ausnahmen für diese Richtlinie erteilen oder deaktivieren , nachdem sie aktiviert wurde.

Häufig gestellte Fragen

Was sind Bezeichner-URIs?

Bezeichner-URIs (auch als "App-ID-URIs" bezeichnet) ermöglichen es einem Ressourcenentwickler (API), einen Zeichenfolgenwert für seine Anwendung als Bezeichner anzugeben. Clients, die ein Token für die API erwerben, können diesen Zeichenfolgenwert während einer OAuth-Anforderung verwenden. Beispielsweise könnten Clients einer API, die eine Bezeichner-URI von https://api.contoso.com konfiguriert hat, diesen Wert in OAuth-Anforderungen an Microsoft Entra angeben. Dieser Bezeichner-URI wird als Zielgruppenanspruch in v1.0-Zugriffstoken verwendet.

Bezeichner-URIs werden mithilfe der Seite "API verfügbar machen" in App-Registrierungen konfiguriert. Bei App-Registrierungen wird der URI des Bezeichners als Anwendungs-ID-URI bezeichnet; dies ist synonym mit Bezeichner-URI.

Screenshot der Bezeichner-URI-Konfigurationserfahrung.

Wie funktionieren diese Richtlinien?

Die Erzwingungen werden durch Konfigurieren der App-Verwaltungsrichtlinien einer Organisation aktiviert. Ein Mandantenadministrator kann ihn aktivieren oder deaktivieren. Microsoft aktiviert sie standardmäßig in einigen Organisationen während der Monate Juni und Juli 2025.

Erfahren Sie, wie Sie überprüfen, ob der Schutz in Ihrer Organisation aktiviert wurde.

Obwohl Microsoft diese Einstellung standardmäßig aktiviert, behalten Mandantenadministratoren die Kontrolle darüber. Sie können sie aktivieren, deaktivieren oder Ausnahmen erteilen.

Warum stoße ich auf diesen Fehler beim Konfigurieren meiner SAML-Anwendung?

SAML-Anwendungen sind standardmäßig von den Bezeichner-URI-Einschränkungen ausgenommen. Sie müssen jedoch ausdrücklich als SAML-Anträge angegeben werden, damit die Ausnahme zutrifft.

Wenn das SAML-Setup mithilfe der Seite "Einmaliges Anmelden" von "Unternehmensanwendungen" konfiguriert wurde, wird die App automatisch als SAML-App angegeben. Falls nicht, können Sie die App als SAML-App angeben, indem Sie die preferredSingleSignOn-Moduseigenschaft des Dienstprinzipals auf SAML festlegen.

Führen Sie dazu die folgende Anforderung aus. Sie können die Objekt-ID des Dienstprinzipals aus der Enterprise-Anwendungsumgebung abrufen.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{objectIdOfServicePrincipal}

{
    "preferredSingleSignOnMode": "SAML"
}
  • Last updated on