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.

Viktigt!

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

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

Kommentar

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

Förutsättningar

• En API Management-instans. 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). Alternativt namn på ämne eller ämne (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 är värd för DNS-posterna.

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

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:

Slutpunkt	Standardvärde
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	Standardvärdet är: <apim-service-name>.developer.azure-api.net
Hantering	Standardvärdet är: <apim-service-name>.management.azure-api.net
Konfigurations-API (v2)	Standardvärdet är: <apim-service-name>.configuration.azure-api.net
SCM	Standardvärdet är: <apim-service-name>.scm.azure-api.net

Att tänka på

• Du kan uppdatera slutpunkter som stöds på din tjänstnivå. Vanligtvis uppdaterar kunderna gatewayen (denna URL används för att anropa API:er som exponeras via API Management) och utvecklarportalen (URL 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.
• Jokerteckendomännamn, till exempel *.contoso.com, stöds på alla nivåer utom förbrukningsnivå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 att api.contoso.com.

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.

Varning

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.

Egen

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.

Key Vault

Vi rekommenderar att du använder Azure Key Vault för att hantera dina certifikat och ställa in dem på autorenew.

Om du använder Azure Key Vault för att hantera ett anpassat TLS-certifikat för domän kontrollerar du att certifikatet infogas i Key Vault som ett certifikat, inte en hemlighet.

Varning

När du använder ett nyckelvalvscertifikat i API Management bör du vara försiktig så att du inte tar bort certifikatet, nyckelvalvet eller den hanterade identitet som används för att komma åt nyckelvalvet.

För att kunna hämta ett TLS/SSL-certifikat måste API Management ha listan och få behörigheter för hemligheter i Azure Key Vault som innehåller certifikatet.

• När du använder Azure-portalen för att importera certifikatet slutförs alla nödvändiga konfigurationssteg automatiskt.

• När du använder kommandoradsverktyg eller hanterings-API måste dessa behörigheter beviljas manuellt i två steg:

  1. På sidan Hanterade identiteter i DIN API Management-instans aktiverar du en systemtilldelad eller användartilldelad hanterad identitet. Observera huvud-ID:t på den sidan.
  2. Tilldela behörigheter till den hanterade identiteten för åtkomst till nyckelvalvet. Använd stegen i följande avsnitt.

  Konfigurera åtkomst till nyckelvalv

  1. I portalen navigerar du till ditt nyckelvalv.

  2. I den vänstra menyn väljer du Åtkomstkonfiguration och noterar den behörighetsmodell som har konfigurerats.

  3. Beroende på behörighetsmodellen konfigurerar du antingen en åtkomstprincip för nyckelvalvet eller Azure RBAC-åtkomst för en hanterad API Management-identitet.

     Så här lägger du till en åtkomstprincip för key vault:
     

     1. I den vänstra menyn väljer du Åtkomstprinciper.
     2. På sidan Åtkomstprinciper väljer du + Skapa.
     3. På fliken Behörigheter går du till Hemliga behörigheter, väljer Hämta och Lista och väljer sedan Nästa.
     4. På fliken Huvudnamn väljer du huvudnamn, söker efter resursnamnet för din hanterade identitet och väljer sedan Nästa. Om du använder en systemtilldelad identitet är huvudnamnet för din API Management-instans.
     5. Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.

     Så här konfigurerar du Azure RBAC-åtkomst:
     

     1. Välj Åtkomstkontroll (IAM) i den vänstra menyn.
     2. På sidan Åtkomstkontroll (IAM) väljer du Lägg till rolltilldelning.
     3. På fliken Roll väljer du Nyckelvalvscertifikatanvändare.
     4. På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
     5. På sidan Välj hanterad identitet väljer du den systemtilldelade hanterade identiteten eller en användartilldelad hanterad identitet som är associerad med din API Management-instans och väljer sedan Välj.
     6. Välj Granska + tilldela.

Om certifikatet är inställt på autorenew och API Management-nivån har ett serviceavtal (dvs. på alla nivåer utom på utvecklarnivån) hämtar API Management den senaste versionen automatiskt, utan avbrott för tjänsten.

Mer information finns i Använda hanterade identiteter i Azure API Management.

Hanterad

API Management erbjuder ett kostnadsfritt, hanterat TLS-certifikat för din domän om du inte vill köpa och hantera ditt eget certifikat. Certifikatet återställs automatiskt.

Kommentar

Det kostnadsfria, hanterade TLS-certifikatet är i förhandsversion. För närvarande är den inte tillgänglig på v2-tjänstnivåerna.

Begränsningar

• För närvarande kan endast användas med gatewayslutpunkten för DIN API Management-tjänst
• Stöds inte med den lokalt installerade gatewayen
• Stöds inte i följande Azure-regioner: Frankrike, södra och Sydafrika, västra
• För närvarande endast tillgängligt i Azure-molnet
• Stöder inte rotdomännamn (till exempel contoso.com). Kräver ett fullständigt kvalificerat namn, till exempel api.contoso.com.
• Stöder endast offentliga domännamn
• Kan bara konfigureras när du uppdaterar en befintlig API Management-instans, inte när du skapar en instans

Ange ett anpassat domännamn – portalen

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

Egen

1. Gå till DIN API Management-instans i Azure-portalen.
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.
10. Välj Lägg till eller välj Uppdatera för en befintlig slutpunkt.
11. Välj Spara.

Key Vault

1. Gå till DIN API Management-instans i Azure-portalen.
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 Key Vault och sedan Välj.
   1. Välj Prenumeration i listrutan.
   2. Välj Nyckelvalvet i listrutan.
   3. När certifikaten har lästs in väljer du Certifikat i listrutan. Klicka på Välj.
   4. I Klientidentitet väljer du en systemtilldelad identitet eller en användartilldelad hanterad identitet som är aktiverad i instansen för att få åtkomst till nyckelvalvet.
7. När du konfigurerar en gatewayslutpunkt väljer eller avmarkerar du andra alternativ efter behov, inklusive Negotiate-klientcertifikat eller Standard-SSL-bindning.
8. Välj Lägg till eller välj Uppdatera för en befintlig slutpunkt.
9. Välj Spara.

Hanterad

1. Gå till DIN API Management-instans i Azure-portalen.
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 Hanterat för att aktivera ett kostnadsfritt certifikat som hanteras av API Management. Det hanterade certifikatet är endast tillgängligt som förhandsversion för gatewayslutpunkten.
7. Kopiera följande värden och använd dem för att konfigurera DNS:
   • TXT-post
   • CNAME-post
8. När du konfigurerar en gatewayslutpunkt väljer eller avmarkerar du andra alternativ efter behov, inklusive Negotiate-klientcertifikat eller Standard-SSL-bindning.
9. Välj Lägg till eller välj Uppdatera för en befintlig slutpunkt.
10. Välj Spara.

Kommentar

Det kan ta 15 minuter eller mer att tilldela certifikatet beroende på distributionens storlek. Utvecklarnivån har stilleståndstid, medan basic- och högre nivåer inte gör det.

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.

Kommentar

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

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.

Kommentar

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.

Varning

När du använder det kostnadsfria, hanterade certifikatet och konfigurerar en CNAME-post med DNS-providern kontrollerar du att den matchar standardvärden 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-post

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 som prefixet av 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å hämta en domänägaridentifierare genom att anropa REST-API:et hämta domänägaridentifierare .

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 stor nyttolast

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

Nästa steg

Uppgradera och skala din tjänst