Een aangepaste domeinnaam configureren voor uw Azure API Management-exemplaar

VAN TOEPASSING OP: Alle API Management-lagen

Wanneer u een Azure API Management-service-exemplaar maakt in de Azure-cloud, wijst Azure dit toe aan een azure-api.net subdomein (bijvoorbeeld apim-service-name.azure-api.net). U kunt uw API Management-eindpunten ook beschikbaar maken met behulp van uw eigen aangepaste domeinnaam, zoals contoso.com. In dit artikel leest u hoe u een bestaande aangepaste DNS-naam toe te wijzen aan eindpunten die worden weergegeven door een API Management-exemplaar.

Belangrijk

API Management accepteert alleen aanvragen met hostheaderwaarden die overeenkomen met:

• De standaarddomeinnaam van de gateway
• Een van de geconfigureerde aangepaste domeinnamen van de gateway

Notitie

Op dit moment worden aangepaste domeinnamen niet ondersteund in een werkruimtegateway.

Vereisten

• Een API Management-exemplaar. Zie Een Azure API Management-exemplaar maken voor meer informatie.

• Een aangepaste domeinnaam die eigendom is van u of uw organisatie. Dit artikel bevat geen instructies voor het aanschaffen van een aangepaste domeinnaam.

• Een geldig certificaat met een openbare en persoonlijke sleutel (optioneel). PFX). De alternatieve naam van het onderwerp of onderwerp (SAN) moet overeenkomen met de domeinnaam (hierdoor kan het API Management-exemplaar VEILIG URL's beschikbaar maken via TLS).

  Zie Opties voor domeincertificaat.

• DNS-records die worden gehost op een DNS-server om de aangepaste domeinnaam toe te wijzen aan de standaarddomeinnaam van uw API Management-exemplaar. Dit onderwerp bevat geen instructies voor het hosten van de DNS-records.

  Zie de DNS-configuratie verderop in dit artikel voor meer informatie over vereiste records.

Eindpunten voor aangepaste domeinen

Er zijn verschillende API Management-eindpunten waaraan u een aangepaste domeinnaam kunt toewijzen. Momenteel zijn de volgende eindpunten beschikbaar:

Eindpunt	Standaardinstelling
Gateway	Standaard is: <apim-service-name>.azure-api.net. Gateway is het enige eindpunt dat beschikbaar is voor configuratie in de verbruikslaag. De standaardconfiguratie van het gateway-eindpunt blijft beschikbaar nadat een aangepast gatewaydomein is toegevoegd.
ontwikkelaarsportal	De standaardwaarde is: <apim-service-name>.developer.azure-api.net
Beheer	De standaardwaarde is: <apim-service-name>.management.azure-api.net
Configuratie-API (v2)	De standaardwaarde is: <apim-service-name>.configuration.azure-api.net
SCM	De standaardwaarde is: <apim-service-name>.scm.azure-api.net

Overwegingen

• U kunt alle eindpunten bijwerken die in uw servicelaag worden ondersteund. Normaal gesproken werken klanten Gateway (deze URL wordt gebruikt om de API's aan te roepen die beschikbaar worden gesteld via API Management) en Ontwikkelaarsportal (de URL van de ontwikkelaarsportal) bij.
• Het standaardgateway-eindpunt blijft beschikbaar nadat u een aangepaste gatewaydomeinnaam hebt geconfigureerd en niet kan worden verwijderd. Voor andere API Management-eindpunten (zoals de ontwikkelaarsportal) die u configureert met een aangepaste domeinnaam, is het standaardeindpunt niet meer beschikbaar.
• Alleen eigenaren van API Management exemplaren kunnen intern Management en SCM-eindpunten gebruiken. Aan deze eindpunten wordt minder vaak een aangepaste domeinnaam toegewezen.
• De lagen Premium en Developer ondersteunen het instellen van meerdere hostnamen voor het Gateway-eindpunt.
• Domeinnamen met jokertekens, zoals , worden ondersteund in alle lagen, met *.contoso.comuitzondering van de verbruikslaag. Een specifiek subdomeincertificaat (bijvoorbeeld api.contoso.com) heeft voorrang op een jokertekencertificaat (*.contoso.com) voor aanvragen voor api.contoso.com.

Opties voor domeincertificaten

API Management ondersteunt aangepaste TLS-certificaten of certificaten die zijn geïmporteerd uit Azure Key Vault. U kunt ook een gratis, beheerd certificaat inschakelen.

Waarschuwing

Als u certificaatpinning nodig hebt, gebruikt u een aangepaste domeinnaam en een aangepast of Key Vault-certificaat, niet het standaardcertificaat of het gratis, beheerde certificaat. Het wordt afgeraden om een vaste afhankelijkheid te nemen van een certificaat dat u niet beheert.

Aangepast

Als u al een privécertificaat van een externe provider hebt, kunt u dit uploaden naar uw API Management-exemplaar. Deze moet voldoen aan de volgende vereisten. (Als u het gratis certificaat dat wordt beheerd door API Management inschakelt, voldoet het al aan deze vereisten.)

• Geëxporteerd als een PFX-bestand, versleuteld met behulp van triple DES en optioneel beveiligd met een wachtwoord.
• Bevat persoonlijke sleutel met een lengte van minimaal 2048 bits
• Bevat alle tussenliggende certificaten en het basiscertificaat in de certificaatketen.

Sleutelkluis

U wordt aangeraden Azure Key Vault te gebruiken om uw certificaten te beheren en in te stellen op autorenew.

Als u Azure Key Vault gebruikt om een TLS-certificaat voor een aangepast domein te beheren, moet u ervoor zorgen dat het certificaat als certificaat wordt ingevoegd in Key Vault, niet als geheim.

Let op

Wanneer u een sleutelkluiscertificaat in API Management gebruikt, moet u ervoor waken dat u het certificaat, de sleutelkluis of de beheerde identiteit die wordt gebruikt voor toegang tot de sleutelkluis, niet verwijdert.

Als u een TLS/SSL-certificaat wilt ophalen, moet API Management de lijst hebben en geheimenmachtigingen ophalen voor de Azure Key Vault die het certificaat bevat.

• Wanneer u Azure Portal gebruikt om het certificaat te importeren, worden alle benodigde configuratiestappen automatisch voltooid.

• Wanneer u opdrachtregelprogramma's of beheer-API gebruikt, moeten deze machtigingen handmatig worden verleend, in twee stappen:

  1. Schakel op de pagina Beheerde identiteiten van uw API Management-exemplaar een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in. Noteer de principal-id op die pagina.
  2. Wijs machtigingen toe aan de beheerde identiteit voor toegang tot de sleutelkluis. Gebruik de stappen in de volgende sectie.

  Toegang tot key vault configureren

  1. Navigeer in de portal naar uw sleutelkluis.

  2. Selecteer in het linkermenu De configuratie van Access en noteer het machtigingsmodel dat is geconfigureerd.

  3. Afhankelijk van het machtigingsmodel configureert u een toegangsbeleid voor key vault of Azure RBAC-toegang voor een beheerde API Management-identiteit.

     Ga als volgende te werk om toegangsbeleid voor key vault toe te voegen:
     

     1. Selecteer toegangsbeleid in het linkermenu.
     2. Selecteer + Maken op de pagina Toegangsbeleid.
     3. Selecteer Op het tabblad Machtigingen onder Geheime machtigingen de optie Ophalen en lijst en selecteer vervolgens Volgende.
     4. Selecteer principal op het tabblad Principal, zoek de resourcenaam van uw beheerde identiteit en selecteer vervolgens Volgende. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management-exemplaar.
     5. Selecteer Volgende opnieuw. Selecteer op het tabblad Beoordelen en maken de optie Maken.

     Azure RBAC-toegang configureren:
     

     1. Selecteer toegangsbeheer (IAM) in het linkermenu.
     2. Selecteer Op de pagina Toegangsbeheer (IAM) de optie Roltoewijzing toevoegen.
     3. Selecteer op het tabblad Rol de sleutelkluiscertificaatgebruiker.
     4. Selecteer Op het tabblad Leden beheerde identiteit>+ Leden selecteren.
     5. Selecteer op de pagina Beheerde identiteit selecteren de door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit die is gekoppeld aan uw API Management-exemplaar en selecteer vervolgens Selecteren.
     6. Selecteer Controleren + toewijzen.

Als het certificaat is ingesteld op autorenew en uw API Management-laag een SLA heeft (in alle lagen behalve de developer-laag), haalt API Management automatisch de nieuwste versie op, zonder uitvaltijd voor de service.

Zie Beheerde identiteiten gebruiken in Azure API Management voor meer informatie.

Beheerd

API Management biedt een gratis, beheerd TLS-certificaat voor uw domein als u uw eigen certificaat niet wilt kopen en beheren. Het certificaat wordt automatisch opnieuw toegepast.

Notitie

Het gratis, beheerde TLS-certificaat is in preview. Momenteel is deze niet beschikbaar in de v2-servicelagen.

Beperkingen

• Momenteel kan alleen worden gebruikt met het gateway-eindpunt van uw API Management-service
• Niet ondersteund met de zelf-hostende gateway
• Niet ondersteund in de volgende Azure-regio's: Frankrijk - zuid en Zuid-Afrika - west
• Momenteel alleen beschikbaar in de Azure-cloud
• Biedt geen ondersteuning voor hoofddomeinnamen (bijvoorbeeld contoso.com). Vereist een volledig gekwalificeerde naam, zoals api.contoso.com.
• Ondersteunt alleen openbare domeinnamen
• Kan alleen worden geconfigureerd bij het bijwerken van een bestaand API Management-exemplaar, niet bij het maken van een exemplaar

Een aangepaste domeinnaam instellen - portal

Kies de stappen op basis van het domeincertificaat dat u wilt gebruiken.

Aangepast

1. Navigeer naar uw API Management-exemplaar in Azure Portal.
2. Selecteer aangepaste domeinen in het linkernavigatievenster.
3. Selecteer +Toevoegen of selecteer een bestaand eindpunt dat u wilt bijwerken.
4. Selecteer in het venster aan de rechterkant het type eindpunt voor het aangepaste domein.
5. Geef in het veld Hostnaam de naam op die u wilt gebruiken. Bijvoorbeeld: api.contoso.com.
6. Selecteer Onder Certificaat de optie Aangepast
7. Selecteer Certificaatbestand om een certificaat te selecteren en te uploaden.
8. Upload een geldige . PFX-bestand en geef het bijbehorende wachtwoord op als het certificaat is beveiligd met een wachtwoord.
9. Wanneer u een gateway-eindpunt configureert, selecteert of deselecteert u indien nodig andere opties, waaronder negotiate-clientcertificaat of standaard-SSL-binding.
10. Selecteer Toevoegen of selecteer Bijwerken voor een bestaand eindpunt.
11. Selecteer Opslaan.

Sleutelkluis

1. Navigeer naar uw API Management-exemplaar in Azure Portal.
2. Selecteer aangepaste domeinen in het linkernavigatievenster.
3. Selecteer +Toevoegen of selecteer een bestaand eindpunt dat u wilt bijwerken.
4. Selecteer in het venster aan de rechterkant het type eindpunt voor het aangepaste domein.
5. Geef in het veld Hostnaam de naam op die u wilt gebruiken. Bijvoorbeeld: api.contoso.com.
6. Selecteer Key Vault onder Certificaat en selecteer vervolgens.
   1. Selecteer het abonnement in de vervolgkeuzelijst.
   2. Selecteer de sleutelkluis in de vervolgkeuzelijst.
   3. Nadat de certificaten zijn geladen, selecteert u het certificaat in de vervolgkeuzelijst. Klik op Selecteren.
   4. Selecteer in clientidentiteit een door het systeem toegewezen identiteit of een door de gebruiker toegewezen beheerde identiteit die is ingeschakeld in het exemplaar voor toegang tot de sleutelkluis.
7. Wanneer u een gateway-eindpunt configureert, selecteert of deselecteert u indien nodig andere opties, waaronder negotiate-clientcertificaat of standaard-SSL-binding.
8. Selecteer Toevoegen of selecteer Bijwerken voor een bestaand eindpunt.
9. Selecteer Opslaan.

Beheerd

1. Navigeer naar uw API Management-exemplaar in Azure Portal.
2. Selecteer aangepaste domeinen in het linkernavigatievenster.
3. Selecteer +Toevoegen of selecteer een bestaand eindpunt dat u wilt bijwerken.
4. Selecteer in het venster aan de rechterkant het type eindpunt voor het aangepaste domein.
5. Geef in het veld Hostnaam de naam op die u wilt gebruiken. Bijvoorbeeld: api.contoso.com.
6. Selecteer onder Certificaat beheerd om een gratis certificaat in te schakelen dat wordt beheerd door API Management. Het beheerde certificaat is alleen beschikbaar in preview voor het gateway-eindpunt.
7. Kopieer de volgende waarden en gebruik deze om DNS te configureren:
   • TXT-record
   • CNAME-record
8. Wanneer u een gateway-eindpunt configureert, selecteert of deselecteert u indien nodig andere opties, waaronder negotiate-clientcertificaat of standaard-SSL-binding.
9. Selecteer Toevoegen of selecteer Bijwerken voor een bestaand eindpunt.
10. Selecteer Opslaan.

Notitie

Het toewijzen van het certificaat kan 15 minuten of langer duren, afhankelijk van de grootte van de implementatie. De ontwikkelaarslaag heeft downtime, terwijl Basic- en hogere lagen dat niet doen.

DNS-configuratie

• Configureer een CNAME-record voor uw aangepaste domein.
• Wanneer u het gratis beheerde certificaat van API Management gebruikt, configureert u ook een TXT-record om uw eigendom van het domein vast te stellen.

Notitie

Het gratis certificaat wordt uitgegeven door DigiCert. Voor sommige domeinen moet u DigiCert expliciet toestaan als certificaatverlener door een CAA-domeinrecord te maken met de waarde: 0 issue digicert.com

CNAME-record

Configureer een CNAME-record die verwijst van uw aangepaste domeinnaam (bijvoorbeeld api.contoso.com) naar de hostnaam van uw API Management-service (bijvoorbeeld <apim-service-name>.azure-api.net). Een CNAME-record is stabieler dan een A-record als het IP-adres verandert. Zie IP-adressen van Azure API Management en de veelgestelde vragen over API Management voor meer informatie.

Notitie

Bij sommige domeinregistrars kunt u alleen subdomeinen toewijzen wanneer u een CNAME-record gebruikt, zoals www.contoso.comen geen hoofdnamen, zoals contoso.com. Zie de documentatie van uw registrar of IETF-domeinnamen - Implementatie en specificatie voor meer informatie over CNAME-records.

Let op

Wanneer u het gratis, beheerde certificaat gebruikt en een CNAME-record configureert met uw DNS-provider, moet u ervoor zorgen dat deze wordt omgezet in de standaardhostnaam van de API Management-service (<apim-service-name>.azure-api.net). Op dit moment wordt het certificaat niet automatisch vernieuwd als de CNAME-record niet wordt omgezet in de standaard-API Management-hostnaam. Als u bijvoorbeeld het gratis, beheerde certificaat gebruikt en Cloudflare als uw DNS-provider gebruikt, moet u ervoor zorgen dat de DNS-proxy niet is ingeschakeld voor de CNAME-record.

TXT-record

Wanneer u het gratis, beheerde certificaat voor API Management inschakelt, configureert u ook een TXT-record in uw DNS-zone om uw eigendom van de domeinnaam vast te stellen.

• De naam van de record is uw aangepaste domeinnaam voorafgegaan door apimuid. Voorbeeld: apimuid.api.contoso.com.
• De waarde is een domeineigendoms-id die wordt geleverd door uw API Management-exemplaar.

Wanneer u de portal gebruikt om het gratis, beheerde certificaat voor uw aangepaste domein te configureren, worden de naam en waarde van de benodigde TXT-record automatisch weergegeven.

U kunt ook een domeineigendom-id ophalen door de REST API voor domeineigendom-id ophalen aan te roepen.

Hoe de API Management-proxyserver reageert met SSL-certificaten in de TLS-handshake

Wanneer u een aangepast domein configureert voor het gateway-eindpunt, kunt u aanvullende eigenschappen instellen die bepalen hoe API Management reageert met een servercertificaat, afhankelijk van de clientaanvraag.

Clients die bellen met SNI-header (Server Name Indication)

Als u een of meerdere aangepaste domeinen hebt geconfigureerd voor het gateway-eindpunt, kan API Management reageren op HTTPS-aanvragen vanuit:

• Aangepast domein (bijvoorbeeld contoso.com)
• Standaarddomein (bijvoorbeeld apim-service-name.azure-api.net).

Op basis van de informatie in de SNI-header reageert API Management met het juiste servercertificaat.

Clientoproepen zonder SNI-header

Als u een client gebruikt die de SNI-header niet verzendt, maakt API Management antwoorden op basis van de volgende logica:

• Als de service slechts één aangepast domein heeft geconfigureerd voor Gateway, is het standaardcertificaat het certificaat dat is uitgegeven aan het aangepaste domein van de gateway.

• Als de service meerdere aangepaste domeinen heeft geconfigureerd voor Gateway (ondersteund in de laag Developer en Premium ), kunt u het standaardcertificaat aanwijzen door de eigenschap defaultSslBinding in te stellen op true ("defaultSslBinding":"true"). Schakel in de portal het selectievakje Standaard-SSL-binding in.

  Als u de eigenschap niet instelt, is het standaardcertificaat het certificaat dat is uitgegeven aan het standaardgatewaydomein dat wordt gehost op *.azure-api.net.

Ondersteuning voor PUT/POST-aanvragen met grote nettolading

API Management-proxyserver ondersteunt aanvragen met grote nettoladingen (>40 kB) bij het gebruik van certificaten aan de clientzijde in HTTPS. Als u wilt voorkomen dat de aanvraag van de server wordt bevroren, kunt u de eigenschap negotiateClientCertificate instellen op true ("negotiateClientCertificate": "true") op de hostnaam van de gateway. Schakel in de portal het selectievakje Negotiate-clientcertificaat in.

Als de eigenschap is ingesteld op Waar, wordt het clientcertificaat aangevraagd op de tijd van de SSL/TLS-verbinding, vóór HTTP-aanvragen worden uitgewisseld. Omdat de instelling van toepassing is op hostnaamniveau van de gateway, vragen alle verbindingsaanvragen om het clientcertificaat. U kunt deze beperking omzeilen en maximaal 20 aangepaste domeinen configureren voor Gateway (alleen ondersteund in de Premium-laag ).

Volgende stappen

Uw service upgraden en schalen