Konfigurieren eines benutzerdefinierten Domänennamens für Ihre Azure API Management-Instanz

GILT FÜR: Alle API Management-Ebenen

Wenn Sie eine Azure API Management-Dienstinstanz in der Azure Cloud erstellen, weist Azure sie einer unterdomäne azure-api.net zu (z. B. apim-service-name.azure-api.net). Sie können Ihre API Management-Endpunkte auch unter Ihrem eigenen benutzerdefinierten Domänennamen verfügbar machen (z. B. contoso.com). In diesem Artikel erfahren Sie, wie Sie Endpunkten, die durch eine API Management-Instanz verfügbar gemacht werden, einen vorhandenen benutzerdefinierten DNS-Namen zuordnen.

Important

API Management akzeptiert nur Anforderungen, bei denen der Hostheaderwert mit einem der folgenden Werte übereinstimmt:

  • Standarddomänenname des Gateways
  • Beliebiger benutzerdefinierter Domänenname, der für das Gateway konfiguriert ist

Note

Derzeit werden benutzerdefinierte Domänennamen in einem Arbeitsbereichs-Gateway nicht unterstützt.

Important

Änderungen an der Infrastruktur Ihres API-Verwaltungsdiensts (z. B. Konfigurieren von benutzerdefinierten Domänen, Hinzufügen von Zertifizierungsstellenzertifikaten, Skalierung, Konfiguration virtueller Netzwerke, Änderungen der Verfügbarkeitszone und Regionszufügungen) können je nach Dienstebene und Größe der Bereitstellung 15 Minuten oder länger dauern. Instanzen mit einer größeren Anzahl von Skalierungseinheiten oder Konfigurationen mit mehreren Regionen (Gateways an mehreren Standorten) benötigen mehr Zeit. Laufende Änderungen an der API-Verwaltung werden sorgfältig ausgeführt, um Kapazität und Verfügbarkeit zu bewahren.

Während der Dienst aktualisiert wird, können andere Änderungen an der Dienstinfrastruktur nicht vorgenommen werden. Sie können jedoch APIs, Produkte, Richtlinien und Benutzereinstellungen konfigurieren. Der Dienst erlebt keine Ausfallzeiten des Gateways, und die API-Verwaltung wird weiterhin API-Anforderungen ohne Unterbrechung (mit Ausnahme der Entwicklerebene) dienstieren.

Prerequisites

  • Eine API Management-Instanz. Weitere Informationen finden Sie unter Create an Azure API Management instance.

  • Einen benutzerdefinierten Domänennamen, der sich in Ihrem Besitz oder im Besitz Ihrer Organisation befindet. Dieser Artikel enthält keine Anleitung zum Erwerben eines benutzerdefinierten Domänennamens.

  • Optional: Ein gültiges Zertifikat mit einem öffentlichen und privaten Schlüssel (.pfx). Der Antragstellername oder der alternative Antragstellername (Subject Alternative Name, SAN) muss dem Domänennamen entsprechen, damit die API Management-Instanz auf sichere Weise URLs über TLS verfügbar machen kann.

    Siehe Domänenzertifikatoptionen.

  • DNS-Einträge, die auf einem DNS-Server gehostet werden, der den benutzerdefinierten Domänennamen dem Standarddomänennamen Ihrer API Management-Instanz zuordnet. Dieser Artikel enthält keine Anleitung zum Hosten der DNS-Einträge.

    Weitere Informationen zu den erforderlichen Einträgen finden Sie weiter unten in diesem Artikel unter DNS-Konfiguration.

Endpunkte für benutzerdefinierte Domänen

Es gibt verschiedene API Management-Endpunkte, denen Sie einen benutzerdefinierten Domänennamen zuweisen können. Derzeit sind folgende Endpunkte verfügbar:

Endpoint Default
Gateway Der Standardwert ist <apim-service-name>.azure-api.net. Gateway ist der einzige Endpunkt, der zur Konfiguration im Tarif „Verbrauch“ verfügbar ist.

Die Standardkonfiguration des Gatewayendpunkts bleibt verfügbar, nachdem eine benutzerdefinierte Gatewaydomäne hinzugefügt wurde.
Entwicklerportal (alle Ebenen mit Ausnahme des Verbrauchs) Der Standardwert ist <apim-service-name>.developer.azure-api.net.
Verwaltung (nur klassische Ebenen) Der Standardwert ist <apim-service-name>.management.azure-api.net.
Selbst gehostete Gatewaykonfigurations-API (v2) Der Standardwert ist <apim-service-name>.configuration.azure-api.net.
SCM (nur klassische Ebenen) Der Standardwert ist <apim-service-name>.scm.azure-api.net.

Considerations

  • Sie können jeden der Endpunkte aktualisieren, die in Ihrer Dienstebene unterstützt werden. In der Regel aktualisieren Kunden Gateway (diese URL wird zum Aufrufen der über API Management verfügbar gemachten API verwendet) und Entwicklerportal (die URL des Entwicklerportals).
  • Der Standardendpunkt Gateway ist noch verfügbar, nachdem Sie einen benutzerdefinierten Gatewaydomänennamen konfiguriert haben, und kann nicht gelöscht werden. Für andere API Management-Endpunkte (z. B. Entwicklerportal), die Sie mit einem benutzerdefinierten Domänennamen konfigurieren, ist der Standardendpunkt nicht mehr verfügbar.
  • Nur API Management-Instanzbesitzer können Verwaltungs- und SCM-Endpunkte intern verwenden. Diesen Endpunkten wird seltener ein benutzerdefinierter Domänenname zugewiesen.
  • In den Tarifen Premium und Developer können mehrere Hostnamen für den Endpunkt Gateway festgelegt werden.
  • Platzhalterdomänennamen wie *.contoso.com werden in allen Tarifen mit Ausnahme des Tarifs „Verbrauch“ unterstützt. Ein spezifisches Unterdomänen-Zertifikat (z. B. api.contoso.com) hätte Vorrang vor einem Platzhalterzertifikat (*.contoso.com) für Anforderungen an api.contoso.com.
  • Beim Konfigurieren einer benutzerdefinierten Domäne für das Entwicklerportal können Sie CORS für den neuen Domänennamen aktivieren. Dies ist für Entwicklerportalbesucher erforderlich, um die interaktive Konsole auf den API-Referenzseiten zu verwenden.

Domänenzertifikatoptionen

DIE API-Verwaltung unterstützt benutzerdefinierte TLS-Zertifikate oder Zertifikate, die aus Azure Key Vault importiert wurden. Sie können auch ein kostenloses, verwaltetes Zertifikat aktivieren.

Warning

Wenn Sie eine Zertifikatanheftung benötigen, verwenden Sie bitte einen benutzerdefinierten Domänennamen und entweder ein benutzerdefiniertes oder Key Vault Zertifikat, nicht das Standardzertifikat oder das kostenlose, verwaltete Zertifikat. Es wird davon abgeraten, eine feste Abhängigkeit von einem Zertifikat zu definieren, das Sie nicht verwalten.

Wenn Sie bereits über ein privates Zertifikat von einem Drittanbieter verfügen, können Sie es in Ihre API Management-Instanz hochladen. Es muss die folgenden Anforderungen erfüllen. (Wenn Sie das kostenlose Zertifikat aktivieren, das von API Management verwaltet wird, erfüllt es diese Anforderungen bereits.)

  • Exportiert als PFX-Datei, mit Triple DES verschlüsselt und optional kennwortgeschützt
  • Enthält einen privaten Schlüssel mit mindestens 2048 Bit
  • Enthält alle Zwischenzertifikate und das Stammzertifikat in der Zertifikatkette.

Festlegen eines benutzerdefinierten Domänennamens – Portal

Wählen Sie die Schritte gemäß Domänenzertifikat aus, das Sie verwenden möchten.

  1. Navigieren Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie im linken Navigationsbereich die Option Benutzerdefinierte Domänen aus.
  3. Klicken Sie auf +Hinzufügen, oder wählen Sie einen vorhandenen Endpunkt aus, den Sie aktualisieren möchten.
  4. Wählen Sie im Fenster auf der rechten Seite den Typ des Endpunkts für die benutzerdefinierte Domäne aus.
  5. Geben Sie im Feld Hostname den gewünschten Namen an. Beispiel: api.contoso.com.
  6. Wählen Sie unter Zertifikat die Option Benutzerdefinierte aus.
  7. Wählen Sie Zertifikatdatei aus, um ein Zertifikat auszuwählen und hochzuladen.
  8. Wenn das Zertifikat mit einem Kennwort geschützt ist, laden Sie eine gültige PFX-Datei hoch, und geben Sie deren Kennwort an.
  9. Wählen Sie beim Konfigurieren eines Gatewayendpunkts nach Bedarf weitere Optionen aus, bzw. deaktivieren Sie sie, z. B. Clientzertifikat aushandeln oder Standard-SSL-Bindung. Gatewaydomäne mit benutzerdefiniertem Zertifikat konfigurieren
  10. Klicken Sie auf +Hinzufügen, oder wählen Sie für einen vorhandenen Endpunkt Aktualisieren aus.
  11. Wählen Sie Speichern aus.

DNS-Konfiguration

Konfigurieren Sie Ihren DNS-Anbieter, um Ihren benutzerdefinierten Domänennamen dem Standarddomänennamen Ihrer API-Verwaltungsinstanz zuzuordnen.

CNAME record

Konfigurieren Sie einen CNAME-Eintrag, der von Ihrem benutzerdefinierten Domänennamen (z. B. api.contoso.com) auf Ihren API Management-Diensthostnamen verweist (z. B. yourapim-service-name.azure-api.net). Ein CNAME-Eintrag ist stabiler als ein A-Eintrag, falls sich die IP-Adresse ändert. Weitere Informationen finden Sie unter IP-Adressen von Azure API Management und den häufig gestellten Fragen zur API-Verwaltung.

Note

Bei einigen Domänenregistrierungsstellen dürfen Sie Unterdomänen nur mit einem CNAME-Eintrag wie www.contoso.com zuweisen und nicht mit einem Stammnamen wie contoso.com. Weitere Informationen zu CNAME-Einträgen finden Sie in der von Ihrer Registrierungsstelle zur Verfügung gestellten Dokumentation oder unter IETF Domain Names – Implementation and Specification.

Zertifikatsynchronisierung und Problembehandlung für Azure Key Vault gesicherte Zertifikate

Wenn Sie ein Azure Key Vault gesichertes Zertifikat für eine benutzerdefinierte Domäne verwenden, stellt die API-Verwaltung Steuerelemente und Diagnose bereit, um Zertifikate synchron zu halten und Zugriffsprobleme schnell zu beheben.

Aufgrund eines Konfigurationsänderungs- oder Konnektivitätsproblems kann Ihre API-Verwaltungsinstanz beispielsweise kein Hostnamenzertifikat von Azure Key Vault abrufen, nachdem ein Zertifikat aktualisiert oder dort gedreht wurde. In diesem Fall verwendet Ihre API-Verwaltungsinstanz weiterhin ein zwischengespeichertes Zertifikat, bis es ein aktualisiertes Zertifikat empfängt. Wenn das zwischengespeicherte Zertifikat abläuft, wird der Laufzeitdatenverkehr an das Gateway blockiert. Jeder upstream-Dienst, z. B. Anwendungsgateway, das die Konfiguration des Hostnamenzertifikats verwendet, kann auch den Laufzeitdatenverkehr an das Gateway blockieren, wenn ein abgelaufenes zwischengespeichertes Zertifikat verwendet wird.

Verwenden Sie die folgenden Steuerelemente und Diagnosen, um Ihre Zertifikate synchron zu halten und Ausfallzeiten zu verhindern oder zu minimieren.

Synchronisieren von Zertifikaten

Wählen Sie " Zertifikate synchronisieren" auf der Befehlsleiste aus, um die Zertifikatsynchronisierung manuell zu starten, wenn sich Zertifikatfingerabdrücke geändert haben. Mit dieser Option können Sie vermeiden, auf den automatisierten Synchronisierungsauftrag zu warten, der in der Regel alle 3 bis 4 Stunden ausgeführt wird.

Screenshot des Befehls zum Synchronisieren von Hostnamenzertifikaten aus Azure Key Vault im portal.

Anzeigen von Synchronisierungsprotokollen

Wählen Sie " Synchronisierungsprotokolle anzeigen " auf der Befehlsleiste aus, um ein Panel mit detaillierten Ursacheninformationen zu öffnen, wenn die Zertifikatsynchronisierung fehlschlägt. Diese Protokolle helfen Ihnen, Synchronisierungsprobleme schneller zu diagnostizieren und zu beheben.

Wiederherstellen des Zugriffs auf den Schlüsseltresor

Die API-Verwaltung zeigt proaktive Warnungen an, wenn Sie Zugriffsprobleme zwischen Ihrer API-Verwaltungsinstanz und dem von der benutzerdefinierten Domäne verwendeten Schlüsseltresor erkennen. Diese Zugriffsprobleme verursachen häufig Fehler bei der Zertifikatsynchronisierung.

Wenn eine Warnung angezeigt wird, wählen Sie "Wiederherstellen" aus, um den Zugriff basierend auf Ihrem Schlüsseltresor-Autorisierungsmodell automatisch zu beheben. Je nach Modell führt die API-Verwaltung eine der folgenden Aktionen aus, um den Zugriff wiederherzustellen:

  • Weist die Rolle Key Vault Secrets User einem Azure RBAC-basierten Schlüsseltresor zu.
  • Gewährt die GET-Berechtigung für einen zugriffsrichtlinienbasierten Schlüsseltresor.

Weitere Tipps zur Problembehandlung für fehlerhafte Zertifikatrotation von Azure Key Vault

  • Vergewissern Sie sich, dass die verwaltete Identität, die für den Zugriff auf den Schlüsseltresor verwendet wird, vorhanden ist.

  • Wenn Ihre API-Verwaltungsinstanz in einem virtuellen Netzwerk bereitgestellt wird, bestätigen Sie die ausgehende Verbindung mit dem AzureKeyVault-Diensttag.

Antworten des API Management-Proxyservers mit SSL-Zertifikaten beim TLS-Handshake

Beim Konfigurieren einer benutzerdefinierten Domäne für den Gatewayendpunkt können Sie über zusätzliche Eigenschaften bestimmen, wie API Management abhängig von der Clientanforderung mit einem Serverzertifikat antwortet.

Aufrufen von Clients mit dem SNI-Header (Server Name Indication, Servernamensanzeige)

Wenn Sie eine oder mehrere benutzerdefinierte Domänen für den Gatewayendpunkt konfiguriert haben, kann API Management auf HTTPS-Anforderungen aus folgenden beiden Domänen antworten:

  • Benutzerdefinierte Domäne (z. B. contoso.com)
  • Standarddomäne (z. B. apim-service-name.azure-api.net)

Basierend auf den Informationen im SNI-Header antwortet API Management mit dem entsprechenden Serverzertifikat.

Aufrufen von Clients ohne den SNI-Header

Wenn Sie einen Client verwenden, der den SNI-Header nicht sendet, erstellt API Management Antworten gemäß der folgenden Logik:

  • Wenn der Dienst nur eine für das Gateway konfigurierte benutzerdefinierte Domäne enthält, ist das Standardzertifikat das Zertifikat, das für die benutzerdefinierte Gatewaydomäne ausgestellt wurde.

  • Wenn im Dienst mehrere benutzerdefinierte Domänen für das Gateway konfiguriert sind (unterstützt in den Tarifen Developer und Premium), können Sie das Standardzertifikat definieren, indem Sie die Eigenschaft defaultSslBinding auf TRUE festlegen ("defaultSslBinding":"true"). Aktivieren Sie im Portal das Kontrollkästchen Standard-SSL-Bindung.

    Wenn Sie die Eigenschaft nicht festlegen, ist das Standardzertifikat das Zertifikat, das für die unter *.azure-api.net gehostete Gatewaystandarddomäne ausgestellt wird.

Unterstützung für PUT/POST-Anforderung mit großer Nutzlast

Der API Management-Proxyserver unterstützt Anforderungen mit großen Nutzdaten (> 40 KB) bei der Verwendung von clientseitigen Zertifikaten in HTTPS. Um zu verhindern, dass die Serveranforderung blockiert wird, können Sie die Eigenschaft negotiateClientCertificate für den Gatewayhostnamen auf TRUE ("negotiateClientCertificate": "true") festlegen. Aktivieren Sie im Portal das Kontrollkästchen Clientzertifikat aushandeln.

Wenn die Eigenschaft auf „true“ festgelegt ist, wird vor jedem Austausch von HTTP-Anforderungen zum Zeitpunkt der SSL/TLS-Verbindung das Clientzertifikat angefordert. Da die Einstellung auf der Ebene Gatewayhostname gilt, wird bei allen Verbindungsanforderungen das Clientzertifikat angefordert. Sie können diese Einschränkung umgehen und bis zu 20 benutzerdefinierte Domänen für das Gateway konfigurieren (nur im Premium-Tarif unterstützt).

Einschränkung für benutzerdefinierten Domänennamen in v2-Ebenen

Derzeit erfordert die API-Verwaltung in den Ebenen Standard v2 und Premium v2 einen öffentlich aufgelösten DNS-Namen, um den Datenverkehr an den Gatewayendpunkt zuzulassen. Wenn Sie einen benutzerdefinierten Domänennamen für den Gatewayendpunkt konfigurieren, muss dieser Name öffentlich aufgelöst werden können, nicht auf eine private DNS-Zone beschränkt.

Als Problemumgehung in Szenarien, in denen Sie den öffentlichen Zugriff auf das Gateway einschränken und einen privaten Domänennamen konfigurieren, können Sie das Anwendungsgateway so einrichten, dass Datenverkehr über den privaten Domänennamen empfangen und an den Gatewayendpunkt der API-Verwaltungsinstanz weitergeleitet wird. Eine Beispielarchitektur finden Sie in diesem GitHub-Repository.

Verwandte Inhalte

  • Last updated on