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

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Wenn Sie eine Azure API Management-Dienstinstanz in der Azure-Cloud erstellen, weist Azure dieser einer Unterdomäne von 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.

Wichtig

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

Hinweis

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

Voraussetzungen

  • Eine API Management-Instanz. Weitere Informationen finden Sie unter Erstellen einer neuen Azure API Management-Dienstinstanz.

  • 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:

Endpunkt Standard
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 Der Standardwert ist <apim-service-name>.developer.azure-api.net.
Verwaltung Der Standardwert ist <apim-service-name>.management.azure-api.net.
Konfigurations-API (v2) Der Standardwert ist <apim-service-name>.configuration.azure-api.net.
SCM Der Standardwert ist <apim-service-name>.scm.azure-api.net.

Überlegungen

  • 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.

Domänenzertifikatoptionen

API Management unterstützt benutzerdefinierte TLS-Zertifikate oder aus Azure Key Vault importierte Zertifikate. Sie können auch ein kostenloses, verwaltetes Zertifikat aktivieren.

Warnung

Wenn Sie das Anheften von Zertifikaten brauchen, sollten Sie einen benutzerdefinierten Domänennamen und entweder ein benutzerdefiniertes oder ein Key Vault-Zertifikat nutzen, 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 Management-Instanz.
  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. Gateway Domäne mit benutzerdefiniertes 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 einen CNAME-Eintrag für Ihre benutzerdefinierten Domäne.
  • Wenn Sie das kostenlose, von API Management verwaltete Zertifikat verwenden, konfigurieren Sie auch einen TXT-Eintrag, um Ihren Domänenbesitz festzulegen.

Hinweis

Das kostenlose Zertifikat wird von DigiCert ausgestellt. Bei einigen Domänen müssen Sie DigiCert explizit als Zertifikataussteller zulassen, indem Sie einen CAA-Domäneneintrag mit dem folgenden Wert erstellen: 0 issue digicert.com.

CNAME-Eintrag

Konfigurieren Sie einen CNAME-Eintrag, der von Ihrem benutzerdefinierten Domänennamen (z. B. api.contoso.com) auf Ihren API Management-Diensthostnamen verweist (z. B. <apim-service-name>.azure-api.net). Ein CNAME-Eintrag ist beständiger als ein A-Eintrag, falls sich die IP-Adresse ändert. Weitere Informationen finden Sie unter IP-Adressen des API Management-Diensts und Häufig gestellte Fragen zu Azure API Management.

Hinweis

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.

Achtung

Wenn Sie das kostenlose verwaltete Zertifikat verwenden und einen CNAME-Eintrag mit Ihrem DNS-Anbieter konfigurieren, stellen Sie sicher, dass er in den Standardhostnamen des API Management-Diensts (<apim-service-name>.azure-api.net) aufgelöst wird. Derzeit erneuert API Management das Zertifikat nicht automatisch, wenn der CNAME-Eintrag nicht in den Standardhostnamen von API Management aufgelöst wird. Wenn Sie beispielsweise das kostenlose verwaltete Zertifikat verwenden und Cloudflare als DNS-Anbieter verwenden, stellen Sie sicher, dass der DNS-Proxy für den CNAME-Eintrag nicht aktiviert ist.

TXT-Eintrag

Wenn Sie das kostenlose, verwaltete Zertifikat für API Management aktivieren, konfigurieren Sie auch einen TXT-Eintrag in Ihrer DNS-Zone, um den Besitz des Domänennamens festzulegen.

  • Der Name des Eintrags ist ihr benutzerdefinierter Domänenname mit dem Präfix apimuid. Beispiel: apimuid.api.contoso.com.
  • Der Wert ist ein Domänenbesitzbezeichner, der von Ihrer API Management-Instanz bereitgestellt wird.

Wenn Sie das kostenlose, verwaltete Zertifikat für Ihre benutzerdefinierte Domäne mit dem Portal konfigurieren, werden der Name und der Wert des erforderlichen TXT-Eintrags automatisch angezeigt.

Sie können auch einen Domänenbesitzbezeichner abrufen, indem Sie die REST-API zum Abrufen eines Domänenbesitzbezeichners aufrufen.

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).

Nächste Schritte

Upgrade and scale an API Management instance (Upgraden und Skalieren einer API Management-Instanz)