Dela via

Konfigurera ett anpassat domännamn för Azure API Management-instansen

GÄLLER FÖR: Alla API Management-nivåer

När du skapar en Azure API Management-tjänstinstans i Azure-molnet tilldelar Azure den en azure-api.net underdomän (till exempel apim-service-name.azure-api.net). Du kan också exponera dina API Management-slutpunkter med ditt eget anpassade domännamn, till exempel contoso.com. Den här artikeln visar hur du mappar ett befintligt anpassat DNS-namn till slutpunkter som exponeras av en API Management-instans.

Important

API Management accepterar endast begäranden med värdhuvudvärden som matchar:

  • Gatewayens standarddomännamn
  • Något av gatewayens konfigurerade anpassade domännamn

Note

För närvarande stöds inte anpassade domännamn i en arbetsytegateway.

Important

Det kan ta 15 minuter eller längre att lägga till CA-certifikat, skalning, konfiguration av virtuellt nätverk, ändringar i tillgänglighetszonen och regiontillägg i API Management-tjänsten (till exempel att konfigurera anpassade domäner, lägga till CA-certifikat, skalning, konfiguration av virtuellt nätverk, ändringar i tillgänglighetszonen och regiontillägg) beroende på tjänstnivå och distributionens storlek. Förvänta dig längre tider för en instans med ett större antal skalningsenheter eller en konfiguration med flera regioner. Löpande ändringar i API Management utförs noggrant för att bevara kapacitet och tillgänglighet.

Medan tjänsten uppdateras kan andra ändringar av tjänstinfrastrukturen inte göras. Du kan dock konfigurera API:er, produkter, principer och användarinställningar. Tjänsten upplever inte gatewayavbrott och API Management fortsätter att hantera API-begäranden utan avbrott (förutom på nivån Utvecklare).

Prerequisites

  • En instans av API Management. Mer information finns i Skapa en Azure API Management-instans.

  • Ett anpassat domännamn som ägs av dig eller din organisation. Den här artikeln innehåller inga instruktioner om hur du skaffar ett anpassat domännamn.

  • Alternativt kan ett giltigt certifikat med en offentlig och privat nyckel (. PFX). Ämne eller alternativt ämnesnamn (SAN) måste matcha domännamnet (detta gör det möjligt för API Management-instansen att på ett säkert sätt exponera URL:er via TLS).

    Se Alternativ för domäncertifikat.

  • DNS-poster som finns på en DNS-server för att mappa det anpassade domännamnet till standarddomännamnet för din API Management-instans. Det här avsnittet innehåller inte instruktioner om hur du hostar DNS-posterna.

    Mer information om nödvändiga uppgifter finns senare i den här artikeln under DNS-konfiguration.

Slutpunkter för anpassade domäner

Det finns flera API Management-slutpunkter som du kan tilldela ett anpassat domännamn till. För närvarande är följande slutpunkter tillgängliga:

Endpoint Default
Gateway Standardvärdet är: <apim-service-name>.azure-api.net. Gateway är den enda slutpunkten som är tillgänglig för konfiguration på förbrukningsnivån.

Standardkonfigurationen för gatewayslutpunkt är fortfarande tillgänglig när en anpassad Gateway-domän har lagts till.
Utvecklarportalen (alla nivåer utom förbrukning) Standardvärdet är: <apim-service-name>.developer.azure-api.net
Hantering (endast klassiska nivåer) Standardvärdet är: <apim-service-name>.management.azure-api.net
Konfigurations-API för lokal gateway (v2) Standardvärdet är: <apim-service-name>.configuration.azure-api.net
SCM (endast klassiska nivåer) Standardvärdet är: <apim-service-name>.scm.azure-api.net

Considerations

  • Du kan uppdatera valfri slutpunkt som stöds på din tjänstnivå. Vanligtvis uppdaterar kunder gatewayen (den här URL:en används för att anropa API:erna som exponeras via API Management) och utvecklarportalen (url:en för utvecklarportalen).
  • Standardslutpunkten för gatewayen är fortfarande tillgänglig när du har konfigurerat ett anpassat gatewaydomännamn och kan inte tas bort. För andra API Management-slutpunkter (till exempel utvecklarportalen) som du konfigurerar med ett anpassat domännamn är standardslutpunkten inte längre tillgänglig.
  • Endast API Management-instansägare kan använda hanterings- och SCM-slutpunkter internt. Dessa slutpunkter tilldelas mindre ofta ett anpassat domännamn.
  • Nivåerna Premium och Developer stöder inställning av flera värdnamn för gatewayslutpunkten .
  • Wildcard-domäner, till exempel *.contoso.com, stöds på alla nivåer utom konsumtionsnivån. Ett specifikt underdomäncertifikat (till exempel api.contoso.com) skulle ha företräde framför ett jokerteckencertifikat (*.contoso.com) för begäranden till api.contoso.com.
  • När du konfigurerar en anpassad domän för utvecklarportalen kan du aktivera CORS för det nya domännamnet. Detta krävs för att besökare på utvecklarportalen ska kunna använda den interaktiva konsolen på API-referenssidorna.

Alternativ för domäncertifikat

API Management stöder anpassade TLS-certifikat eller certifikat som importerats från Azure Key Vault. Du kan också aktivera ett kostnadsfritt, hanterat certifikat.

Warning

Om du behöver fästa certifikatet använder du ett anpassat domännamn och antingen ett anpassat certifikat eller Key Vault-certifikat, inte standardcertifikatet eller det kostnadsfria hanterade certifikatet. Vi rekommenderar inte att du har ett hårt beroende av ett certifikat som du inte hanterar.

Om du redan har ett privat certifikat från en tredjepartsleverantör kan du ladda upp det till din API Management-instans. Den måste uppfylla följande krav. (Om du aktiverar det kostnadsfria certifikatet som hanteras av API Management uppfyller det redan dessa krav.)

  • Exporterat som en PFX-fil, krypterat med trippel-DES och eventuellt lösenordsskyddat.
  • Innehåller privat nyckel minst 2048 bitar lång
  • Innehåller alla mellanliggande certifikat och rotcertifikatet i certifikatkedjan.

Ange ett anpassat domännamn – portalen

Välj stegen enligt det domäncertifikat som du vill använda.

  1. Gå till DIN API Management-instans i Azure Portal.
  2. I det vänstra navigeringsfältet väljer du Anpassade domäner.
  3. Välj +Lägg till eller välj en befintlig slutpunkt som du vill uppdatera.
  4. I fönstret till höger väljer du Typ av slutpunkt för den anpassade domänen.
  5. I fältet Värdnamn anger du det namn som du vill använda. Exempel: api.contoso.com
  6. Under Certifikat väljer du Anpassad
  7. Välj Certifikatfil för att välja och ladda upp ett certifikat.
  8. Ladda upp en giltig . PFX-fil och ange dess lösenord, om certifikatet är skyddat med ett lösenord.
  9. När du konfigurerar en gatewayslutpunkt väljer eller avmarkerar du andra alternativ efter behov, inklusive Negotiate-klientcertifikat eller Standard-SSL-bindning. Konfigurera gatewaydomän med anpassat certifikat
  10. Välj Lägg till eller välj Uppdatera för en befintlig slutpunkt.
  11. Välj Spara.

DNS-konfiguration

  • Konfigurera en CNAME-post för din anpassade domän.
  • När du använder API Managements kostnadsfria, hanterade certifikat konfigurerar du även en TXT-post för att upprätta ditt ägarskap för domänen.

Note

Det kostnadsfria certifikatet utfärdas av DigiCert. För vissa domäner måste du uttryckligen tillåta DigiCert som certifikatutfärdare genom att skapa en CAA-domänpost med värdet : 0 issue digicert.com.

CNAME record

Konfigurera en CNAME-post som pekar från ditt anpassade domännamn (till exempel api.contoso.com) till api Management-tjänstens värdnamn (till exempel <apim-service-name>.azure-api.net). En CNAME-post är stabilare än en A-post om IP-adressen ändras. Mer information finns i IP-adresser för Azure API Management och vanliga frågor och svar om API Management.

Note

Vissa domänregistratorer tillåter bara att du mappar underdomäner när du använder en CNAME-post, till exempel www.contoso.com, och inte rotnamn, till exempel contoso.com. Mer information om CNAME-poster finns i dokumentationen från din registrator eller IETF-domännamn – implementering och specifikation.

Caution

När du använder det kostnadsfria, hanterade certifikatet och konfigurerar en CNAME-post med din DNS-provider, kontrollerar du att den pekar på standardvärdnamnet för API Management-tjänsten (<apim-service-name>.azure-api.net). API Management förnyar för närvarande inte certifikatet automatiskt om CNAME-posten inte matchar standardvärden för API Management. Om du till exempel använder det kostnadsfria, hanterade certifikatet och använder Cloudflare som DNS-provider kontrollerar du att DNS-proxyn inte är aktiverad i CNAME-posten.

TXT record

När du aktiverar det kostnadsfria hanterade certifikatet för API Management konfigurerar du även en TXT-post i DNS-zonen för att upprätta ditt ägarskap för domännamnet.

  • Namnet på posten är ditt anpassade domännamn med prefixet apimuid. Exempel: apimuid.api.contoso.com.
  • Värdet är en domänägaridentifierare som tillhandahålls av din API Management-instans.

När du använder portalen för att konfigurera det kostnadsfria hanterade certifikatet för din anpassade domän visas automatiskt namnet och värdet för den nödvändiga TXT-posten.

Du kan också få en domänägaridentifierare genom att anropa Get Domain Ownership Identifier REST API.

Så här svarar API Management-proxyservern med SSL-certifikat i TLS-handskakningen

När du konfigurerar en anpassad domän för gatewayslutpunkten kan du ange ytterligare egenskaper som avgör hur API Management svarar med ett servercertifikat, beroende på klientbegäran.

Klienter som anropar med SNI-huvud (Server Name Indication)

Om du har en eller flera anpassade domäner konfigurerade för gatewayslutpunkten kan API Management svara på HTTPS-begäranden från antingen:

  • Anpassad domän (till exempel contoso.com)
  • Standarddomän (till exempel apim-service-name.azure-api.net).

Baserat på informationen i SNI-huvudet svarar API Management med rätt servercertifikat.

Klienter som anropar utan SNI-huvud

Om du använder en klient som inte skickar SNI-huvudet skapar API Management svar baserat på följande logik:

  • Om tjänsten bara har en anpassad domän konfigurerad för Gateway är standardcertifikatet certifikatet som utfärdats till gatewayens anpassade domän.

  • Om tjänsten har konfigurerat flera anpassade domäner för Gateway (stöds på nivån Utvecklare och Premium ) kan du ange standardcertifikatet genom att ange egenskapen defaultSslBinding till true ("defaultSslBinding":"true"). I portalen markerar du kryssrutan Standard-SSL-bindning .

    Om du inte anger egenskapen är standardcertifikatet certifikatet som utfärdats till standarddomänen för gatewayen som finns på *.azure-api.net.

Stöd för PUT/POST-begäran med stort innehåll

API Management-proxyservern stöder begäranden med stora nyttolaster (>40 KB) när du använder certifikat på klientsidan i HTTPS. För att förhindra att serverns begäran fryser kan du ange egenskapen negotiateClientCertificate till true ("negotiateClientCertificate": "true") på gatewayens värdnamn. I portalen väljer du kryssrutan Förhandla om klientcertifikat .

Om egenskapen är inställd på true begärs klientcertifikatet vid SSL/TLS-anslutningstid, före ett HTTP-begärandeutbyte. Eftersom inställningen gäller på gatewayens värdnamnsnivå ber alla anslutningsbegäranden om klientcertifikatet. Du kan kringgå den här begränsningen och konfigurera upp till 20 anpassade domäner för gateway (stöds endast på Premium-nivån ).

Begränsning för anpassat domännamn på Standard v2-nivå

I standardnivån v2 kräver API Management för närvarande ett offentligt matchningsbart DNS-namn för att tillåta trafik till gatewayslutpunkten. Om du konfigurerar ett anpassat domännamn för gatewayslutpunkten måste det namnet vara offentligt matchbart, inte begränsat till en privat DNS-zon.

Som en lösning i scenarier där du begränsar offentlig åtkomst till gatewayen och konfigurerar ett privat domännamn, kan du konfigurera Application Gateway för att ta emot trafik med det privata domännamnet och dirigera den till API Management-instansens gatewayslutpunkt. Ett exempel på arkitektur finns i den här GitHub-lagringsplatsen.

Felsökning: Det gick inte att rotera värdnamnets certifikat från Azure Key Vault

På grund av ett konfigurationsändrings- eller anslutningsproblem kanske din API Management-instans inte kan hämta ett värdnamnscertifikat från Azure Key Vault när ett certifikat har uppdaterats eller roterats där. När detta händer fortsätter API Management-instansen att använda ett cachelagrat certifikat tills det tar emot ett uppdaterat certifikat. Om det cachelagrade certifikatet upphör att gälla blockeras körningstrafiken till gatewayen. Alla överordnade tjänster som Application Gateway som använder certifikatkonfigurationen för värdnamn kan också blockera körningstrafik till gatewayen när ett cachelagrat certifikat som har upphört att gälla används.

För att undvika det här problemet kontrollerar du att nyckelvalvet finns och att certifikatet lagras i nyckelvalvet. Om din API Management-instans distribueras i ett virtuellt nätverk bekräftar du utgående anslutning till AzureKeyVault-tjänsttaggen. Kontrollera om den hanterade identitet som används för att komma åt nyckelvalvet finns. Bekräfta den hanterade identitetens behörigheter för åtkomst till nyckelvalvet. Läs Konfigurera ett anpassat domännamn – Key Vault tidigare i den här artikeln för detaljerade konfigurationssteg. När konfigurationen har återställts uppdateras värdnamnscertifikatet i API Management inom 4 timmar.

Relaterat innehåll

Uppgradera och skala din tjänst