Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
TOEPASSING OP: Alle lagen van API Management
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.
Belangrijk
Wijzigingen in de infrastructuur van uw API Management-service (zoals het configureren van aangepaste domeinen, het toevoegen van CA-certificaten, schalen, configuratie van virtuele netwerken, wijzigingen in de beschikbaarheidszone en regio-toevoegingen) kunnen 15 minuten of langer duren, afhankelijk van de servicelaag en de grootte van de implementatie. Verwacht langere tijden voor een exemplaar met een groter aantal schaaleenheden of configuratie met meerdere regio's. Rolling wijzigingen in API Management worden zorgvuldig uitgevoerd om de capaciteit en beschikbaarheid te behouden.
Terwijl de service wordt bijgewerkt, kunnen andere wijzigingen in de serviceinfrastructuur niet worden aangebracht. U kunt echter API's, producten, beleid en gebruikersinstellingen configureren. De service ondervindt geen downtime van de gateway en API Management blijft zonder onderbreking service-API-aanvragen uitvoeren (behalve in de developer-laag).
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 naam van het onderwerp of de alternatieve naam van het onderwerp (SAN) moet overeenkomen met de domeinnaam (waardoor het API Management-exemplaar veilig URL's voor TLS beschikbaar kan maken).
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 | Standaard |
|---|---|
| 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 (alle lagen behalve Verbruik) | De standaardwaarde is: <apim-service-name>.developer.azure-api.net |
| Beheer (alleen klassieke niveaus) | De standaardwaarde is: <apim-service-name>.management.azure-api.net |
| Zelfgehoste gateway-configuratie-API (v2) | De standaardwaarde is: <apim-service-name>.configuration.azure-api.net |
| SCM (alleen klassieke lagen) | 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
*.contoso.com, worden ondersteund in alle lagen, met uitzondering van de verbruikslaag. Een specifiek subdomeincertificaat (bijvoorbeeld api.contoso.com) heeft voorrang op een jokertekencertificaat (*.contoso.com) voor aanvragen voor api.contoso.com. - Wanneer u een aangepast domein configureert voor de ontwikkelaarsportal, kunt u CORS inschakelen voor de nieuwe domeinnaam. Dit is nodig voor bezoekers van de ontwikkelaarsportal voor het gebruik van de interactieve console op de API-referentiepagina's.
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.
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.
Een aangepaste domeinnaam instellen - portal
Kies de stappen op basis van het domeincertificaat dat u wilt gebruiken.
- Navigeer naar uw API Management-exemplaar in Azure Portal.
- Selecteer aangepaste domeinen in het linkernavigatievenster.
- Selecteer +Toevoegen of selecteer een bestaand eindpunt dat u wilt bijwerken.
- Selecteer in het venster aan de rechterkant het type eindpunt voor het aangepaste domein.
- Geef in het veld Hostnaam de naam op die u wilt gebruiken. Bijvoorbeeld:
api.contoso.com. - Selecteer Certificaat en kies Aangepast
- Selecteer Certificaatbestand om een certificaat te selecteren en te uploaden.
- Upload een geldige . PFX-bestand en geef het bijbehorende wachtwoord op als het certificaat is beveiligd met een wachtwoord.
- Wanneer u een gateway-eindpunt configureert, selecteert of deselecteert u indien nodig andere opties, waaronder Cliënteelcertificaat onderhandelen of Standaard-SSL-binding.
- Selecteer Toevoegen of selecteer Bijwerken voor een bestaand eindpunt.
- Selecteer Opslaan.
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 domeineigendomidentificator verkrijgen door de Get Domain Ownership Identifier REST API 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-request met grote payload
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. Selecteer in de portal het selectievakje Negotiate-clientcertificaat.
Als de eigenschap is ingesteld op waar, wordt het clientcertificaat aangevraagd tijdens de SSL/TLS-verbinding, voordat er 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 ).
Beperking voor aangepaste domeinnaam in standard v2-laag
Op dit moment vereist API Management in de Standard v2-laag een openbaar omzetbare DNS-naam om verkeer naar het gateway-eindpunt toe te staan. Als u een aangepaste domeinnaam voor het gateway-eindpunt configureert, moet die naam openbaar kunnen worden omgezet, niet beperkt tot een privé-DNS-zone.
Als tijdelijke oplossing in scenario's waarin u openbare toegang tot de gateway beperkt en u een privédomeinnaam configureert, kunt u Application Gateway instellen voor het ontvangen van verkeer op de privédomeinnaam en deze routeren naar het gateway-eindpunt van het API Management-exemplaar. Zie deze GitHub-opslagplaats voor een voorbeeldarchitectuur.
Problemen oplossen: roulatie van hostnaamcertificaten vanuit Azure Key Vault is mislukt
Vanwege een configuratiewijziging of connectiviteitsprobleem kan uw API Management-exemplaar mogelijk geen hostnaamcertificaat ophalen uit Azure Key Vault nadat een certificaat daar is bijgewerkt of geroteerd. Wanneer dit gebeurt, blijft uw API Management-exemplaar een certificaat in de cache gebruiken totdat het een bijgewerkt certificaat ontvangt. Als het certificaat in de cache verloopt, wordt runtime-verkeer naar de gateway geblokkeerd. Elke upstream-service, zoals Application Gateway die gebruikmaakt van de configuratie van het hostnaamcertificaat, kan ook runtimeverkeer naar de gateway blokkeren wanneer een verlopen certificaat in de cache wordt gebruikt.
U kunt dit probleem oplossen door te controleren of de sleutelkluis bestaat en of het certificaat is opgeslagen in de sleutelkluis. Als uw API Management-exemplaar is geïmplementeerd in een virtueel netwerk, controleert u de uitgaande connectiviteit met de AzureKeyVault-servicetag. Controleer of de beheerde identiteit die wordt gebruikt voor toegang tot de sleutelkluis bestaat. Bevestig de machtigingen van de beheerde identiteit voor toegang tot de sleutelkluis. Bekijk Het instellen van een aangepaste domeinnaam - Key Vault, eerder in dit artikel, voor gedetailleerde configuratiestappen. Nadat de configuratie is hersteld, wordt het hostnaamcertificaat binnen 4 uur vernieuwd in API Management.