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

Benutzerdefiniert

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.

Schlüsseltresor

Es wird empfohlen, Azure Key Vault zum Verwalten Ihrer Zertifikate zu verwenden und für sie die Einstellung autorenew festzulegen.

Wenn Sie Azure Key Vault zum Verwalten eines benutzerdefinierten TLS-Domänenzertifikat verwenden, müssen Sie sicherstellen, dass das Zertifikat als Zertifikat und nicht als Geheimnis in Key Vault eingefügt wird.

Achtung

Wenn Sie in API Management ein Zertifikat aus einem Schlüsseltresor verwenden, dürfen Sie auf keinen Fall das Zertifikat, den Schlüsseltresor oder die verwaltete Identität löschen, die für den Zugriff auf den Schlüsseltresor verwendet wird.

Zum Abrufen des TLS/SSL-Zertifikats benötigt API Management die Berechtigung zum Auflisten und Abrufen von Geheimnissen für die Azure Key Vault-Instanz, die das Zertifikat enthält.

• Wenn Sie das Azure-Portal zum Importieren des Zertifikats verwenden, werden alle erforderlichen Konfigurationsschritte automatisch ausgeführt.

• Wenn Sie Befehlszeilentools oder eine Verwaltungs-API nutzen, müssen diese Berechtigungen manuell in zwei Schritten erteilt werden:

  1. Aktivieren Sie auf der Seite Verwaltete Identitäten für Ihre API Management-Instanz eine system- oder benutzerseitig zugewiesene verwaltete Identität. Notieren Sie sich die auf dieser Seite angezeigte Prinzipal-ID.
  2. Weisen Sie der verwalteten Identität Berechtigungen für den Zugriff auf den Schlüsseltresor zu. Führen Sie die Schritte im folgenden Abschnitt aus.

  Konfigurieren des Zugriffs auf den Schlüsseltresor

  1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.

  2. Wählen Sie im Menü auf der linken Seite Zugriffskonfiguration aus, und beachten Sie das konfigurierte Berechtigungsmodell.

  3. Konfigurieren Sie je nach Berechtigungsmodell entweder eine Schlüsseltresor-Zugriffsrichtlinie oder den Azure RBAC-Zugriff für eine verwaltete API Management-Identität.

     So fügen Sie eine Schlüsseltresor-Zugriffsrichtlinie hinzu
     

     1. Wählen Sie im Menü auf der linken Seite Zugriffsrichtlinien aus.
     2. Wählen Sie auf der Seite Zugriffsrichtlinien die Option + Erstellen aus.
     3. Wählen Sie auf der Registerkarte Berechtigungen unter Berechtigungen für Geheimnis die Optionen Abrufen und Auflisten und dann Weiter aus.
     4. Klicken Sie auf der Registerkarte Prinzipal auf Prinzipal auswählen, suchen Sie nach dem Ressourcennamen Ihrer verwalteten Identität, und wählen Sie dann Weiter aus. Wenn Sie eine systemseitig zugewiesene Identität verwenden, ist der Prinzipal der Name der API Management-Instanz.
     5. Wählen Sie erneut Weiter aus. Wählen Sie auf der Registerkarte Überprüfen + erstellen die Option Erstellen aus.

     So konfigurieren Sie Azure RBAC-Zugriff
     

     1. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus.
     2. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Option Rollenzuweisung hinzufügen aus.
     3. Wählen Sie auf der Registerkarte Rolle die Option Schlüsseltresor-Zertifikatbenutzer aus.
     4. Wählen Sie auf der Registerkarte Mitglieder die Option Verwaltete Identität>+ Mitglieder auswählen aus.
     5. Wählen Sie auf der Seite Verwaltete Identität auswählen die systemseitig zugewiesene verwaltete Identität oder eine benutzerseitig zugewiesene verwaltete Identität aus, die Ihrer API Management-Instanz zugeordnet ist, und wählen Sie dann Auswählen aus.
     6. Wählen Sie Überprüfen und zuweisen aus.

Wenn für das Zertifikat autorenew eingerichtet ist und Ihr API Management-Tarif eine SLA aufweist (dies trifft auf alle Tarife mit Ausnahme des Developer-Tarifs zu), wählt API Management automatisch die neuste Version aus, ohne Downtime für den Dienst.

Weitere Informationen finden Sie unter Verwenden von verwalteten Identitäten in Azure API Management.

Verwaltet

API Management stellt ein kostenloses, verwaltetes TLS-Zertifikat für Ihre Domäne bereit, wenn Sie kein eigenes Zertifikat erwerben und verwalten möchten. Das Zertifikat wird automatisch erneuert.

Hinweis

Das kostenlose, verwaltete TLS-Zertifikat befindet sich in der Vorschau. Derzeit ist es in den v2-Dienstebenen nicht verfügbar.

Begrenzungen

• Derzeit nur mit dem Gatewayendpunkt Ihres API Management-Diensts verwendbar
• Keine Unterstützung mit dem selbst gehosteten Gateway
• Keine Unterstützung in den folgenden Azure-Regionen: „Frankreich, Süden“ und „Südafrika, Westen“
• Derzeit nur in der Azure-Cloud verfügbar
• Keine Unterstützung von Stammdomänennamen (z. B. contoso.com) Erfordert einen vollqualifizierten Namen wie beispielsweise api.contoso.com
• Unterstützt nur öffentliche Domänennamen
• Kann nur beim Aktualisieren einer vorhandenen API Management-Instanz und nicht beim Erstellen einer Instanz konfiguriert werden

Festlegen eines benutzerdefinierten Domänennamens – Portal

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

Benutzerdefiniert

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.
10. Klicken Sie auf +Hinzufügen, oder wählen Sie für einen vorhandenen Endpunkt Aktualisieren aus.
11. Wählen Sie Speichern aus.

Schlüsseltresor

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 Schlüsseltresor und dann Auswählen aus.
   1. Wählen Sie in der Dropdownliste Abonnement aus.
   2. Wählen Sie in der Dropdownliste den Schlüsseltresor aus.
   3. Nachdem die Zertifikate geladen wurden, wählen Sie das Zertifikat aus der Dropdownliste aus. Klicken Sie auf Auswählen.
   4. Wählen Sie in Clientidentität eine systemseitig zugewiesene Identität oder eine benutzerseitig zugewiesene verwaltete Identität aus, die in der Instanz für den Zugriff auf den Schlüsseltresor aktiviert ist.
7. Wählen Sie beim Konfigurieren eines Gatewayendpunkts nach Bedarf weitere Optionen aus, bzw. deaktivieren Sie sie, z. B. Clientzertifikat aushandeln oder Standard-SSL-Bindung.
8. Klicken Sie auf +Hinzufügen, oder wählen Sie für einen vorhandenen Endpunkt Aktualisieren aus.
9. Wählen Sie Speichern aus.

Verwaltet

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 Verwaltet aus, um ein kostenloses Zertifikat zu aktivieren, das von API Management verwaltet wird. Das verwaltete Zertifikat ist nur in der Vorschau für den Gatewayendpunkt verfügbar.
7. Kopieren Sie die folgenden Werte, und verwenden Sie sie zum Konfigurieren von DNS:
   • TXT-Eintrag
   • CNAME-Eintrag
8. Wählen Sie beim Konfigurieren eines Gatewayendpunkts nach Bedarf weitere Optionen aus, bzw. deaktivieren Sie sie, z. B. Clientzertifikat aushandeln oder Standard-SSL-Bindung.
9. Klicken Sie auf +Hinzufügen, oder wählen Sie für einen vorhandenen Endpunkt Aktualisieren aus.
10. Wählen Sie Speichern aus.

Hinweis

Die Zuweisung des Zertifikats kann je nach Größe der Bereitstellung 15 Minuten und länger dauern. Für den Developer-Tarif kommt es zu einer Downtime, für den Tarif „Basic“ und höhere Tarife hingegen nicht.

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)