Egyéni tartománynév konfigurálása az Azure API Management-példányhoz

A KÖVETKEZŐRE VONATKOZIK: az összes API-kezelési szintre

Amikor létrehoz egy Azure API Management szolgáltatáspéldányt az Azure-felhőben, az Azure egy azure-api.net altartományt rendel hozzá (például apim-service-name.azure-api.net). Az API Management-végpontokat saját egyéni tartománynévvel is elérhetővé teheti, például contoso.com. Ez a cikk bemutatja, hogyan képezhet le egy meglévő testreszabott DNS-nevet az API-kezelési példányok által hozzáférhetővé tett végpontokra.

Fontos

Az API Management csak a gazdagép fejlécértékeivel egyező kéréseket fogad el:

• Az átjáró alapértelmezett tartományneve
• Az átjáró bármely konfigurált egyéni tartományneve

Megjegyzés

Az egyéni tartománynevek jelenleg nem támogatottak a munkaterület-átjárókban.

Fontos

Az API Management szolgáltatás infrastruktúrájának módosítása (például egyéni tartományok konfigurálása, CA-tanúsítványok hozzáadása, skálázás, virtuális hálózat konfigurációja, rendelkezésre állási zónák módosítása és régiók hozzáadása) a szolgáltatási szinttől és az üzembe helyezés méretétől függően akár 15 percet is igénybe vehet. Hosszabb idő várható a nagyobb méretű egységeket vagy többrégiós konfigurációt tartalmazó példányok esetében. Az API Management működés közbeni módosításait gondosan végrehajtjuk a kapacitás és a rendelkezésre állás megőrzése érdekében.

A szolgáltatás frissítése közben más szolgáltatásinfrastruktúra-módosítások nem végezhetők el. Azonban konfigurálhatja az API-kat, a termékeket, a szabályzatokat és a felhasználói beállításokat. A szolgáltatás nem fog átjáró-állásidőt tapasztalni, és az API Management továbbra is megszakítás nélkül fogja kiszolgálni az API-kéréseket (kivéve a fejlesztői szintet).

Előfeltételek

• Egy API-kezelési példány. További információ: Azure API Management-példány létrehozása.

• Egyéni tartománynév, amely Ön vagy a szervezete tulajdonában van. Ez a cikk nem tartalmaz útmutatást az egyéni tartománynév beszerzéséhez.

• Opcionálisan érvényes tanúsítvány nyilvános és titkos kulccsal (. PFX). A tárgy vagy tárgy alternatív nevének (SAN) meg kell egyeznie a tartománynévvel (így az API Management példány biztonságosan felfedheti az URL-címeket TLS segítségével).

  Lásd : Tartománytanúsítvány beállításai.

• A DNS-kiszolgálón tárolt DNS-rekordok az egyéni tartománynévnek az API Management-példány alapértelmezett tartománynevére való leképezéséhez. Ez a témakör nem nyújt útmutatást a DNS-rekordok üzemeltetéséhez.

  A szükséges rekordokról további információt a jelen cikk későbbi, DNS-konfigurációjában talál.

Végpontok egyéni tartományokhoz

Számos API Management-végponthoz rendelhet egyéni tartománynevet. Jelenleg a következő végpontok érhetők el:

Végpont	Alapértelmezett
Átjáró	Az alapértelmezett érték: <apim-service-name>.azure-api.net. A Gateway az egyetlen elérhető végpont a fogyasztási szint konfigurációjához. Az alapértelmezett átjáróvégpont-konfiguráció az egyéni átjárótartomány hozzáadása után is elérhető marad.
Fejlesztői portál (minden szint, kivéve a fogyasztási szint)	Az alapértelmezett érték a következő: <apim-service-name>.developer.azure-api.net
Felügyelet (csak klasszikus szintek esetén)	Az alapértelmezett érték a következő: <apim-service-name>.management.azure-api.net
Saját üzemeltetésű átjárókonfigurációs API (v2)	Az alapértelmezett érték a következő: <apim-service-name>.configuration.azure-api.net
SCM (csak klasszikus szintek esetén)	Az alapértelmezett érték a következő: <apim-service-name>.scm.azure-api.net

Megfontolások

• A szolgáltatási szintjén támogatott végpontok bármelyikét frissítheti. Az ügyfelek általában frissítik az átjárót (ezt az URL-címet az API Management által közzétett API-k meghívására használják) és a fejlesztői portált (a fejlesztői portál URL-címét).
• Az alapértelmezett átjáróvégpont az egyéni átjáró tartománynevének konfigurálása után is elérhető marad, és nem törölhető. Az egyéni tartománynévvel konfigurált egyéb API Management-végpontok (például fejlesztői portál) esetében az alapértelmezett végpont már nem érhető el.
• Csak az API Management-példányok tulajdonosai használhatják belsőleg a Felügyelet és a SCM-végpontokat. A rendszer ezekhez a végpontokhoz ritkábban rendel hozzá egyéni tartománynevet.
• A prémium és fejlesztői szintek támogatják az átjáróvégpont több állomásnevének beállítását.
• Helyettesítő karakteres tartománynevek, mint a *.contoso.com, a Használat szint kivételével minden más szinten vannak támogatva. Egy adott altartomány-tanúsítvány (például api.contoso.com) a kérések esetében elsőbbséget élvez a helyettesítő (wildcard) tartomány-tanúsítvánnyal (*.contoso.com) szemben, ha a kérés az api.contoso.com címre irányul.
• Ha egyéni tartományt konfigurál a fejlesztői portálhoz, engedélyezheti a CORS-t az új tartománynévhez. Erre azért van szükség, hogy a fejlesztői portál látogatói az INTERAKTÍV konzolt használják az API referenciaoldalain.

Tartományi tanúsítvány beállításai

Az API Management támogatja az egyéni TLS-tanúsítványokat és az Azure Key Vaultból importált tanúsítványokat. Ingyenes, felügyelt tanúsítvány is engedélyezhető.

Figyelmeztetés

Ha tanúsítvány-rögzítést igényel, használjon egyéni tartománynevet és egyéni vagy Key Vault-tanúsítványt, ne az alapértelmezett tanúsítványt vagy az ingyenes, felügyelt tanúsítványt. Nem javasoljuk, hogy szigorú függőségben legyen egy olyan tanúsítványtól, amelyet nem Ön kezel.

Szokás

Ha már rendelkezik egy külső szolgáltatótól származó magántanúsítvánnyal, feltöltheti azt az API Management-példányba. Meg kell felelnie az alábbi követelményeknek. (Ha engedélyezi az API Management által felügyelt ingyenes tanúsítványt, az már megfelel ezeknek a követelményeknek.)

• Legyen PFX-fájlként exportált, háromszoros DES-sel titkosított, opcionálisan jelszavas védelemmel ellátott.
• Legalább 2048 bit hosszúságú titkos kulcsot kell tartalmaznia.
• Tartalmazza a tanúsítványláncban lévő összes köztes tanúsítványt és a főtanúsítványt.

Key Vault (kulcstároló)

Javasoljuk, hogy az Azure Key Vault használatával kezelje a tanúsítványokat , és állítsa őket a következőre autorenew: .

Ha az Azure Key Vaultot használja egy egyéni tartomány TLS-tanúsítványának kezeléséhez, győződjön meg arról, hogy a tanúsítvány tanúsítványként van beszúrva a Key Vaultba, nem titkos kulcsként.

Figyelemfelhívás

Ha key vault-tanúsítványt használ az API Managementben, ügyeljen arra, hogy ne törölje a kulcstartó eléréséhez használt tanúsítványt, kulcstartót vagy felügyelt identitást.

TLS/SSL-tanúsítvány lekéréséhez az API Managementnek rendelkeznie kell a listával, és titkos kódokra vonatkozó engedélyeket kell beszereznie a tanúsítványt tartalmazó Azure Key Vaultban.

• Amikor az Azure Portal használatával importálja a tanúsítványt, a rendszer automatikusan végrehajtja az összes szükséges konfigurációs lépést.

• Parancssori eszközök vagy felügyeleti API használata esetén ezeket az engedélyeket manuálisan kell megadni, két lépésben:

  1. Az API Management-példány Felügyelt identitások lapján engedélyezze a rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitást. Jegyezze fel az oldalon található főazonosítót.
  2. A felügyelt identitáshoz rendelje hozzá a kulcstár eléréséhez szükséges engedélyeket. Kövesse az alábbi szakasz lépéseit.

  A Key Vaulthoz való hozzáférés konfigurálása

  1. A portálon nyissa meg a kulcstárat.
  2. A bal oldali menüben válassza az Access-konfigurációt. Jegyezze fel a konfigurált engedélymodellt .
  3. Az engedélymodelltől függően konfiguráljon kulcstartó-hozzáférési szabályzatot vagy Azure RBAC-hozzáférést egy API Management által felügyelt identitáshoz.

  Kulcstár hozzáférési szabályzat hozzáadása:

  1. A bal oldali menüben válassza az Access-szabályzatok lehetőséget.
  2. Az Hozzáférési szabályzatok lapon válassza a + Létrehozás gombot.
  3. Az Engedélyek lap Titkos engedélyek csoportjában válassza a Beolvasás és a Lista lehetőséget, majd a Tovább lehetőséget.
  4. Az Egyszerű lapon válassza az Egyszerű lehetőséget, keresse meg a felügyelt identitás erőforrásnevét, majd kattintson a Tovább gombra. Ha rendszer által hozzárendelt identitást használ, az egyszerű az API Management-példány neve.
  5. Kattintson ismét a Tovább gombra. A Véleményezés + létrehozás lapon válassza a Létrehozás lehetőséget.

  Az Azure RBAC-hozzáférés konfigurálása:

  1. A bal oldali menüben válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
  2. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelés hozzáadása lehetőséget.
  3. A Szerepkör lapon válassza a Key Vault tanúsítványfelhasználója lehetőséget.
  4. A Tagok lapon válassza a Felügyelt identitás>+ Tagok kijelölése lehetőséget.
  5. A Felügyelt identitások kiválasztása ablakban válassza ki a rendszer által hozzárendelt felügyelt identitást vagy az API Management-példányhoz társított felhasználó által hozzárendelt felügyelt identitást, majd kattintson a Kiválasztás gombra.
  6. Válassza a Véleményezés + hozzárendelés lehetőséget.

Ha a tanúsítvány autorenew értékre van állítva, és az API Management szintje SLA-val rendelkezik (azaz a fejlesztői szint kivételével minden szinten), az API Management automatikusan felveszi a legújabb verziót, anélkül, hogy leállás történne a szolgáltatásban.

További információ: Felügyelt identitások használata az Azure API Managementben.

Kezelt

Az API Management ingyenes, felügyelt TLS-tanúsítványt kínál tartományához, ha nem szeretné megvásárolni és kezelni saját tanúsítványát. A tanúsítvány automatikusan újul meg.

Megjegyzés

Az ingyenes, felügyelt TLS-tanúsítvány előzetes verzióban érhető el. Jelenleg nem érhető el a v2 szolgáltatási szinteken.

Korlátozások

• Jelenleg csak az API Management szolgáltatás átjáróvégpontjával használható
• A saját üzemeltetésű átjáróval nem támogatott
• A következő Azure-régiókban nem támogatott: Dél-Franciaország és Dél-Afrika nyugati régiója
• Jelenleg csak az Azure-felhőben érhető el
• Nem támogatja a gyökértartományneveket (például contoso.com). Teljes névre van szükség, például api.contoso.com.
• Csak a nyilvános tartományneveket támogatja
• Csak meglévő API Management-példány frissítésekor konfigurálható, példány létrehozásakor nem

Egyéni tartománynév beállítása – portál

Válassza ki a használni kívánt tartománytanúsítványnak megfelelő lépéseket.

Szokás

1. Lépjen az API Management-példányra az Azure Portalon.
2. A bal oldali navigációs sávon válassza az Egyéni tartományok lehetőséget.
3. Válassza a +Hozzáadás lehetőséget, vagy válasszon ki egy frissíteni kívánt meglévő végpontot .
4. A jobb oldali ablakban válassza ki az egyéni tartomány végpontjának típusát .
5. A Gazdagépnév mezőben adja meg a használni kívánt nevet. Például: api.contoso.com.
6. A Tanúsítvány területen válassza az Egyéni
7. Tanúsítvány kiválasztásához és feltöltéséhez válassza ki a tanúsítványfájlt .
8. Töltsön fel érvényes . PFX-fájl, és adja meg a jelszavát, ha a tanúsítvány jelszóval van védve.
9. Átjáróvégpont konfigurálásakor szükség szerint válassza ki vagy törölje az egyéb lehetőségek kijelölését, beleértve az ügyféltanúsítvány egyeztetését vagy az alapértelmezett SSL-kötést.
10. Válassza a Hozzáadás lehetőséget, vagy válassza a Meglévő végpont frissítését .
11. Válassza a Mentés lehetőséget.

Key Vault (kulcstároló)

1. Lépjen az API Management-példányra az Azure Portalon.
2. A bal oldali navigációs sávon válassza az Egyéni tartományok lehetőséget.
3. Válassza a +Hozzáadás lehetőséget, vagy válasszon ki egy frissíteni kívánt meglévő végpontot .
4. A jobb oldali ablakban válassza ki az egyéni tartomány végpontjának típusát .
5. A Gazdagépnév mezőben adja meg a használni kívánt nevet. Például: api.contoso.com.
6. A Tanúsítvány területen válassza a Key Vault , majd a Kiválasztás lehetőséget.
   1. Válassza ki az előfizetést a legördülő listából.
   2. Válassza ki a Key Vaultot a legördülő listából.
   3. A tanúsítványok betöltése után válassza ki a tanúsítványt a legördülő listából. Kattintson a Kijelölés gombra.
   4. Az ügyfélidentitásban válasszon ki egy rendszer által hozzárendelt identitást vagy egy felhasználó által hozzárendelt felügyelt identitást , amely engedélyezve van a példányban a kulcstartó eléréséhez.
7. Átjáróvégpont konfigurálásakor szükség szerint válassza ki vagy törölje az egyéb lehetőségek kijelölését, beleértve az ügyféltanúsítvány egyeztetését vagy az alapértelmezett SSL-kötést.
8. Válassza a Hozzáadás lehetőséget, vagy válassza a Meglévő végpont frissítését .
9. Válassza a Mentés lehetőséget.

Kezelt

1. Lépjen az API Management-példányra az Azure Portalon.
2. A bal oldali navigációs sávon válassza az Egyéni tartományok lehetőséget.
3. Válassza a +Hozzáadás lehetőséget, vagy válasszon ki egy frissíteni kívánt meglévő végpontot .
4. A jobb oldali ablakban válassza ki az egyéni tartomány végpontjának típusát .
5. A Gazdagépnév mezőben adja meg a használni kívánt nevet. Például: api.contoso.com.
6. A Tanúsítvány területen válassza a Felügyelt lehetőséget az API Management által felügyelt ingyenes tanúsítvány engedélyezéséhez. A felügyelt tanúsítvány csak az átjáróvégpont előzetes verziójában érhető el.
7. Másolja ki a következő értékeket, és használja őket a DNS konfigurálásához:
   • TXT rekord
   • CNAME rekord
8. Átjáróvégpont konfigurálásakor szükség szerint válassza ki vagy törölje az egyéb lehetőségek kijelölését, beleértve az ügyféltanúsítvány egyeztetését vagy az alapértelmezett SSL-kötést.
9. Válassza a Hozzáadás lehetőséget, vagy válassza a Meglévő végpont frissítését .
10. Válassza a Mentés lehetőséget.

DNS-konfiguráció

• Konfiguráljon egy CNAME rekordot az egyéni tartományhoz.
• Ha az API Management ingyenes, felügyelt tanúsítványát használja, konfiguráljon egy TXT rekordot is a tartomány tulajdonjogának megállapításához.

Megjegyzés

Az ingyenes tanúsítványt a DigiCert állítja ki. Egyes tartományok esetében explicit módon engedélyeznie kell a DigiCert tanúsítványkibocsátóként egy CAA-tartományrekord létrehozását a következő értékkel: 0 issue digicert.com.

CNAME-rekord

Konfiguráljon egy CNAME rekordot, amely az egyéni tartománynévről (például api.contoso.com) az API Management szolgáltatás gazdagépnevére mutat (például <apim-service-name>.azure-api.net). A CNAME rekord stabilabb, mint az A-rekord, ha megváltozik az IP-cím. További információkért tekintse meg az Azure API Management IP-címeit és az API Managementtel kapcsolatos gyakori kérdéseket.

Megjegyzés

Egyes tartományregisztrálók csak akkor engedélyezik az altartományok leképezését, ha CNAME rekordot használ, például www.contoso.comnem gyökérneveket, például contoso.com. A CNAME rekordokról további információt a regisztráló vagy az IETF-tartománynevek – implementáció és specifikáció dokumentációjában talál.

Figyelemfelhívás

Ha az ingyenes, felügyelt tanúsítványt használja, és konfigurál egy CNAME rekordot a DNS-szolgáltatónál, győződjön meg arról, hogy az az alapértelmezett API Management szolgáltatás állomásneve (<apim-service-name>.azure-api.net). Az API Management jelenleg nem újítja meg automatikusan a tanúsítványt, ha a CNAME rekord nem oldja fel az alapértelmezett API Management-gazdagépnevet. Ha például az ingyenes, felügyelt tanúsítványt használja, és a Cloudflare-t használja DNS-szolgáltatóként, győződjön meg arról, hogy a DNS-proxy nincs engedélyezve a CNAME rekordon.

TXT rekord

Az API Management ingyenes, felügyelt tanúsítványának engedélyezésekor konfiguráljon egy TXT rekordot a DNS-zónában a tartománynév tulajdonjogának megállapításához.

• A rekord neve az egyéni tartománynév, amelyhez az apimuid előtag tartozik. Példa: apimuid.api.contoso.com
• Az érték az API Management-példány által megadott tartománytulajdon-azonosító.

Amikor a portál használatával konfigurálja az egyéni tartomány ingyenes, felügyelt tanúsítványát, a rendszer automatikusan megjeleníti a szükséges TXT rekord nevét és értékét.

A tartomány tulajdonjogi azonosítóját a Tartomány tulajdonjogának lekérése REST API meghívásával is lekérheti.

Hogyan válaszol az API Management proxykiszolgáló SSL-tanúsítványokkal a TLS-kézfogásban?

Ha egyéni domaint konfigurál a Gateway végponthoz, beállíthat olyan további tulajdonságokat, amelyek meghatározzák, hogy az API Management hogyan válaszol egy kiszolgálótanúsítvánnyal, az ügyfélkéréstől függően.

A kiszolgálónév-jelzés (SNI) fejlécével hívogató ügyfelek

Ha egy vagy több egyéni tartomány van konfigurálva az átjáróvégponthoz, az API Management az alábbi esetekben válaszolhat a HTTPS-kérelmekre:

• Egyéni tartomány (például contoso.com)
• Alapértelmezett tartomány (például apim-service-name.azure-api.net).

Az SNI-fejlécben található információk alapján az API Management a megfelelő kiszolgálótanúsítvánnyal válaszol.

SNI-fejléc nélkül hívó ügyfelek

Ha olyan ügyfelet használ, amely nem küldI el az SNI-fejlécet , az API Management a következő logika alapján hoz létre válaszokat:

• Ha a szolgáltatásnak csak egy egyéni tartománya van konfigurálva az Átjáróhoz, az alapértelmezett tanúsítvány az átjáró egyéni tartománya számára kiadott tanúsítvány.

• Ha a szolgáltatás több egyéni tartományt konfigurált az Átjáróhoz (a fejlesztői és prémium szintű szinten támogatott), az alapértelmezettSslBinding tulajdonság true ("defaultSslBinding":"true") értékre állításával kijelölheti az alapértelmezett tanúsítványt. A portálon jelölje be az Alapértelmezett SSL-kötés jelölőnégyzetet.

  Ha nem állítja be a tulajdonságot, az alapértelmezett tanúsítvány a *.azure-api.net helyen üzemeltetett alapértelmezett átjáró tartományához kiadott tanúsítvány.

A PUT/POST kérelmek támogatása nagy méretű terheléssel

Az API Management proxykiszolgáló támogatja a nagy méretű adatokkal (>40 KB) rendelkező kéréseket, amikor ügyféloldali tanúsítványokat használ a HTTPS használata esetén. Ha meg szeretné akadályozni, hogy a kiszolgáló kérése lefagyjon, állítsa a negotiateClientCertificate tulajdonságot true ("negotiateClientCertificate": "true") értékre az Átjáró gazdagépnéven. A portálon jelölje be az Ügyféltanúsítvány egyeztetése jelölőnégyzetet.

Ha a tulajdonság értéke igaz, az ügyféltanúsítványt SSL-/TLS-kapcsolati időpontban kéri a rendszer a HTTP-kérések cseréje előtt. Mivel a beállítás az átjáró állomásnév szintjén érvényes, minden kapcsolatkérés az ügyféltanúsítványt kéri. Megkerülheti ezt a korlátozást, és legfeljebb 20 egyéni tartományt konfigurálhat az átjáróhoz (csak a Prémium szinten támogatott).

Az egyéni tartománynév korlátozása a Standard v2 szinten

A Standard v2 szinten az API Management jelenleg nyilvánosan feloldható DNS-nevet igényel az átjáróvégpont felé történő forgalom engedélyezéséhez. Ha egyéni tartománynevet konfigurál az átjáróvégponthoz, ennek a névnek nyilvánosan feloldhatónak kell lennie, nem korlátozódhat privát DNS-zónára.

Kerülő megoldásként olyan helyzetekben, amikor korlátozza az átjáróhoz való nyilvános hozzáférést, és konfigurál egy privát tartománynevet, beállíthatja az Application Gatewayt, hogy fogadja a forgalmat a privát tartománynéven, és átirányítsa azt az API Management-példány átjáróvégpontjára. Példaarchitektúraként tekintse meg ezt a GitHub-adattárat.

Hibaelhárítás: A gazdagépnév tanúsítványának rotálása nem sikerült az Azure Key Vaultból

Konfigurációváltozás vagy csatlakozási probléma miatt előfordulhat, hogy az API Management-példány nem tudja lekérni a gazdagépnév-tanúsítványt az Azure Key Vaultból, miután egy tanúsítványt frissítenek vagy cserélnek. Ha ez történik, az API Management-példány továbbra is gyorsítótárazott tanúsítványt használ, amíg meg nem kapja a frissített tanúsítványt. Ha a gyorsítótárazott tanúsítvány lejár, a rendszer letiltja az átjáró futásidejű forgalmát. Bármely upstream szolgáltatás, mint például az Application Gateway, amely a hostnév tanúsítványkonfigurációját használja, blokkolhatja az átjáró futó forgalmát lejárt gyorsítótárazott tanúsítvány használatakor.

A probléma megoldásához győződjön meg arról, hogy a kulcstartó létezik, és a tanúsítvány a kulcstartóban van tárolva. Ha az API Management-példány virtuális hálózaton van üzembe helyezve, erősítse meg az AzureKeyVault szolgáltatás címkéjéhez való kimenő kapcsolatot. Ellenőrizze, hogy létezik-e a kulcstár eléréséhez használt felügyelt identitás. Ellenőrizze, hogy a felügyelt identitás engedélyei lehetővé teszik-e a kulcstár elérését. A részletes konfigurációs lépésekért tekintse át az egyéni tartománynév – Key Vault beállítását a cikk korábbi részében. A konfiguráció visszaállítása után a gazdagépnév tanúsítványa 4 órán belül frissül az API Managementben.

Kapcsolódó tartalom

A szolgáltatás frissítése és skálázása