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
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.
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 Onder Certificaat de optie 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 negotiate-clientcertificaat 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 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 ).