Konfigurace vlastního názvu domény pro instanci služby Azure API Management

PLATÍ PRO: Všechny úrovně služby správy rozhraní API

Když vytvoříte instanci služby Azure API Management v cloudu Azure, Azure ji přiřadí subdoménu azure-api.net (například apim-service-name.azure-api.net). Koncové body služby API Management můžete zveřejnit také pomocí vlastního názvu domény, například contoso.com. V tomto článku se dozvíte, jak namapovat existující vlastní název DNS na koncové body vystavené instancí služby API Management.

Important

Api Management přijímá pouze požadavky s odpovídajícími hodnotami hlaviček hostitele :

• Výchozí název domény brány
• Libovolný z nakonfigurovaných vlastních názvů domén brány

Note

V současné době se vlastní názvy domén v bráně pracovního prostoru nepodporují.

Important

Dokončení změn infrastruktury služby API Management (například konfigurace vlastních domén, přidání certifikátů certifikační autority, škálování, konfigurace virtuální sítě, změny zóny dostupnosti a přidání oblastí) může trvat 15 minut nebo déle v závislosti na úrovni služby a velikosti nasazení. U instance s větším počtem jednotek škálování nebo více oblastí můžete očekávat delší dobu. Postupné změny ve službě API Management se provádějí pečlivě, aby se zachovala kapacita a dostupnost.

Během aktualizace služby není možné provést jiné změny infrastruktury služeb. Můžete ale nakonfigurovat rozhraní API, produkty, zásady a uživatelská nastavení. Služba nebude mít výpadek brány a služba API Management bude dál obsluhovat požadavky rozhraní API bez přerušení (s výjimkou úrovně Developer).

Prerequisites

• Instance služby API Management. Další informace najdete v tématu Vytvoření instance služby Azure API Management.

• Vlastní název domény, který vlastníte vy nebo vaše organizace. Tento článek neobsahuje pokyny k získání vlastního názvu domény.

• Volitelně můžete použít platný certifikát s veřejným a privátním klíčem (. PFX). Alternativní název subjektu nebo subjektu se musí shodovat s názvem domény (to umožňuje instanci služby API Management bezpečně zveřejnit adresy URL přes protokol TLS).

  Viz Možnosti certifikátu domény.

• Záznamy DNS hostované na serveru DNS pro mapování vlastního názvu domény na výchozí název domény vaší instance služby API Management. Toto téma neobsahuje pokyny k hostování záznamů DNS.

  Další informace o požadovaných záznamech najdete v části Konfigurace DNS dále v tomto článku.

Koncové body pro vlastní domény

Existuje několik koncových bodů služby API Management, ke kterým můžete přiřadit vlastní název domény. V současné době jsou k dispozici následující koncové body:

Endpoint	Default
Gateway	Výchozí hodnota je: <apim-service-name>.azure-api.net. Brána je jediný koncový bod, který je k dispozici pro konfiguraci na úrovni Consumption. Výchozí konfigurace koncového bodu brány zůstane k dispozici po přidání vlastní domény brány.
Portál pro vývojáře (všechny úrovně kromě Consumption)	Výchozí hodnota je: <apim-service-name>.developer.azure-api.net
Správa (pouze úrovně Classic)	Výchozí hodnota je: <apim-service-name>.management.azure-api.net
Rozhraní API konfigurace brány v místním prostředí (v2)	Výchozí hodnota je: <apim-service-name>.configuration.azure-api.net
SCM (pouze úrovně Classic)	Výchozí hodnota je: <apim-service-name>.scm.azure-api.net

Considerations

• Můžete aktualizovat jakýkoli koncový bod podporovaný na vaší úrovni služby. Zákazníci obvykle aktualizují bránu (tato adresa URL se používá k volání rozhraní API vystavených prostřednictvím služby API Management) a portálu pro vývojáře (adresa URL portálu pro vývojáře).
• Výchozí koncový bod brány zůstane dostupný po konfiguraci vlastního názvu domény brány a nedá se odstranit. Pro ostatní koncové body služby API Management (například portál pro vývojáře), které konfigurujete s vlastním názvem domény, už není výchozí koncový bod dostupný.
• Jen vlastníci instancí služby API Management mohou interně používat koncové body Management a SCM. K těmto koncovým bodům se méně často přiřazuje vlastní název domény.
• Úrovně Premium a Developer podporují nastavení více názvů hostitelů pro koncový bod Gateway.
• Názvy *.contoso.comdomén se zástupnými výjimkou úrovně Consumption podporují ve všech úrovních. Konkrétní certifikát subdomény (například api.contoso.com) má přednost před certifikátem se zástupným znakem (*.contoso.com) pro požadavky na api.contoso.com.
• Při konfiguraci vlastní domény pro portál pro vývojáře můžete CORS povolit pro nový název domény. To je potřeba, aby návštěvníci portálu pro vývojáře používali interaktivní konzolu na referenčních stránkách rozhraní API.

Možnosti certifikátu domény

API Management podporuje vlastní certifikáty TLS nebo certifikáty importované ze služby Azure Key Vault. Můžete také povolit bezplatný spravovaný certifikát.

Warning

Pokud požadujete připnutí certifikátu, použijte vlastní název domény a vlastní certifikát nebo certifikát služby Key Vault, ne výchozí nebo bezplatný spravovaný certifikát. Doporučujeme nevyužívat pevnou závislost na certifikátu, který nespravujete.

Custom

Pokud už máte privátní certifikát od jiného poskytovatele, můžete ho nahrát do instance služby API Management. Musí splňovat následující požadavky. (Pokud povolíte bezplatný certifikát spravovaný službou API Management, už splňuje tyto požadavky.)

• Musí být exportovaný do souboru PFX, šifrovaný pomocí algoritmu Triple DES a volitelně chráněný heslem.
• Obsahuje soukromý klíč dlouhý nejméně 2048 bitů
• Musí v řetězu certifikátů obsahovat všechny zprostředkující certifikáty a kořenový certifikát.

Úložiště klíčů

Ke správě certifikátů a jejich nastavení autorenewdoporučujeme použít Azure Key Vault.

Pokud ke správě vlastního certifikátu TLS domény používáte Azure Key Vault, ujistěte se, že se certifikát vloží do služby Key Vault jako certifikát, ne tajný klíč.

Caution

Při použití certifikátu trezoru klíčů ve službě API Management dávejte pozor, abyste certifikát, trezor klíčů nebo spravovanou identitu používanou pro přístup k trezoru klíčů neodstraňovat.

Pokud chcete načíst certifikát TLS/SSL, musí mít služba API Management seznam a získat oprávnění k tajným kódům ve službě Azure Key Vault obsahující certifikát.

• Když k importu certifikátu použijete Azure Portal, dokončí se všechny nezbytné kroky konfigurace automaticky.

• Pokud používáte nástroje příkazového řádku nebo rozhraní API pro správu, musí být tato oprávnění udělena ručně ve dvou krocích:

  1. Na stránce Spravované identity vaší instance služby API Management povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem. Poznamenejte si ID objektu zabezpečení na této stránce.
  2. Přiřaďte oprávnění spravované identitě pro přístup k trezoru klíčů. Postupujte podle kroků v následující části.

  Konfigurace přístupu k trezoru klíčů

  1. Na portálu přejděte do trezoru klíčů.
  2. V nabídce vlevo vyberte Nastavení>konfigurace přístupu. Všimněte si nakonfigurovaného modelu oprávnění .
  3. V závislosti na modelu oprávnění nakonfigurujte zásady přístupu trezoru klíčů nebo přístup Azure RBAC pro spravovanou identitu služby API Management.

  Chcete-li přidat zásadu přístupu k trezoru klíčů:

  1. V nabídce vlevo vyberte Zásady přístupu.
  2. Na stránce Zásady přístupu vyberte + Vytvořit.
  3. Na kartě Oprávnění v sekci Oprávnění pro tajné vyberte Získat a Vypsat a pak vyberte Další.
  4. Na kartě Hlavní vyhledejte název prostředku vaší spravované identity a poté vyberte Další. Pokud používáte identitu přiřazenou systémem, objekt zabezpečení je název vaší instance služby API Management.
  5. Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.

  Konfigurace přístupu Azure RBAC:

  1. V nabídce vlevo vyberte Řízení přístupu (IAM).
  2. Na stránce Řízení přístupu (IAM) vyberte Přidat přiřazení role.
  3. Na kartě Role vyberte uživatele certifikátu služby Key Vault.
  4. Na kartě Členové vyberte Spravovaná identita>+ Vybrat členy.
  5. V okně Vybrat spravované identity vyberte spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem přidruženou k vaší instanci služby API Management a klikněte na vybrat.
  6. Vyberte Zkontrolovat a přiřadit.

Pokud je certifikát nastavený autorenew a vaše úroveň SLUŽBY API Management má smlouvu SLA (to znamená ve všech úrovních kromě úrovně Developer), služba API Management automaticky vyzvedne nejnovější verzi bez výpadků služby.

Další informace najdete v tématu Použití spravovaných identit ve službě Azure API Management.

Managed

Služba API Management nabízí pro vaši doménu bezplatný spravovaný certifikát TLS, pokud si nechcete koupit a spravovat vlastní certifikát. Certifikát se automaticky automaticky neaktualizují.

Important

Vytvoření spravovaných certifikátů pro vlastní domény ve službě API Management bude dočasně nedostupné od 15. srpna 2025 do 15. března 2026. Naše certifikační autorita (CA), DigiCert, migruje na novou ověřovací platformu, aby splňovala požadavky MPIC (Multi-Perspective Issuance Corroboration) pro vystavování certifikátů. Tato migrace vyžaduje, abychom dočasně pozastavili vytváření spravovaných certifikátů pro vlastní domény. Další informace

Stávající spravované certifikáty se automaticky provedou a zůstanou nedotčené.

Vytváření spravovaných certifikátů je pozastavené, ale pro konfiguraci vlastních domén použijte další možnosti certifikátu.

Note

Bezplatný spravovaný certifikát TLS je ve verzi Preview.

Limitations

• Aktuálně je možné použít pouze s koncovým bodem brány vaší služby API Management.
• Není podporováno v úrovních v2.
• Nepodporuje se u brány v místním prostředí
• Nepodporuje se v následujících oblastech Azure: Francie – jih a Jižní Afrika – západ
• Aktuálně k dispozici pouze v cloudu Azure
• Nepodporuje názvy kořenových domén (například contoso.com). Vyžaduje plně kvalifikovaný název, například api.contoso.com.
• Podporuje pouze názvy veřejných domén.
• Dá se nakonfigurovat jenom při aktualizaci existující instance služby API Management, ne při vytváření instance.

Nastavení vlastního názvu domény – portál

Zvolte kroky podle certifikátu domény , který chcete použít.

Custom

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V levém navigačním panelu vyberte Vlastní domény.
3. Vyberte +Přidat nebo vyberte existující koncový bod , který chcete aktualizovat.
4. V okně napravo vyberte typ koncového bodu pro vlastní doménu.
5. Do pole Název hostitele zadejte název, který chcete použít. Například api.contoso.com.
6. V části Certifikát vyberte Vlastní.
7. Vyberte soubor certifikátu pro nahrání certifikátu.
8. Nahrajte platný soubor .PFX a zadejte jeho heslo, pokud je certifikát chráněný heslem.
9. Při konfiguraci koncového bodu brány vyberte nebo podle potřeby zrušte výběr dalších možností, včetně klientského certifikátu Negotiate nebo výchozí vazby SSL.
10. Vyberte Přidat nebo vyberte Aktualizovat pro existující koncový bod.
11. Vyberte Uložit.

Úložiště klíčů

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V levém navigačním panelu vyberte Vlastní domény.
3. Vyberte +Přidat nebo vyberte existující koncový bod , který chcete aktualizovat.
4. V okně napravo vyberte typ koncového bodu pro vlastní doménu.
5. Do pole Název hostitele zadejte název, který chcete použít. Například api.contoso.com.
6. V části Certifikát vyberte Key Vault a pak vyberte.
   1. V rozevíracím seznamu vyberte předplatné .
   2. V rozevíracím seznamu vyberte trezor klíčů .
   3. Po načtení certifikátů vyberte certifikát z rozevíracího seznamu. Klepněte na tlačítko Vybrat.
   4. V části Identita klienta vyberte identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem povolenou v instanci pro přístup k trezoru klíčů.
7. Při konfiguraci koncového bodu brány vyberte nebo podle potřeby zrušte výběr dalších možností, včetně klientského certifikátu Negotiate nebo výchozí vazby SSL.
8. Vyberte Přidat nebo vyberte Aktualizovat pro existující koncový bod.
9. Vyberte Uložit.

Managed

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V levém navigačním panelu vyberte Vlastní domény.
3. Vyberte +Přidat nebo vyberte existující koncový bod , který chcete aktualizovat.
4. V okně napravo vyberte typ koncového bodu pro vlastní doménu.
5. Do pole Název hostitele zadejte název, který chcete použít. Například api.contoso.com.
6. V části Certifikát vyberte Spravované a povolte bezplatný certifikát spravovaný službou API Management. Spravovaný certifikát je dostupný jenom ve verzi Preview pro koncový bod brány.
7. Zkopírujte následující hodnoty a použijte je ke konfiguraci DNS:
   • Záznam TXT
   • Záznam CNAME
8. Při konfiguraci koncového bodu brány vyberte nebo podle potřeby zrušte výběr dalších možností, včetně klientského certifikátu Negotiate nebo výchozí vazby SSL.
9. Vyberte Přidat nebo vyberte Aktualizovat pro existující koncový bod.
10. Vyberte Uložit.

Konfigurace DNS

• Nakonfigurujte záznam CNAME pro vlastní doménu.
• Při použití bezplatného spravovaného certifikátu služby API Management nakonfigurujte také záznam TXT pro vytvoření vlastnictví domény.

Note

Certifikát free vydává DigiCert. U některých domén musíte digiCert explicitně povolit jako vystavitele certifikátu vytvořením záznamu domény CAA s hodnotou: 0 issue digicert.com.

záznam CNAME

Nakonfigurujte záznam CNAME, který odkazuje z vašeho vlastního názvu domény (například api.contoso.com) na název hostitele služby API Management (například <apim-service-name>.azure-api.net). Záznam CNAME je stabilnější než záznam A pro případ, že se IP adresa změní. Další informace najdete v tématu IP adresy služby Azure API Management a nejčastější dotazy ke službě API Management.

Note

Někteří doménoví registrátoři umožňují mapovat subdomény pouze při použití záznamu CNAME, například www.contoso.com, a ne kořenových názvů, například contoso.com. Další informace o záznamech CNAME najdete v dokumentaci, kterou poskytuje registrátor nebo názvy domén IETF – Implementace a specifikace.

Caution

Pokud použijete bezplatný spravovaný certifikát a nakonfigurujete záznam CNAME u svého poskytovatele DNS, ujistěte se, že se přeloží na výchozí název hostitele služby API Management (<apim-service-name>.azure-api.net). V současné době služba API Management certifikát automaticky neobnoví, pokud se záznam CNAME nepřeloží na výchozí název hostitele služby API Management. Pokud například používáte bezplatný spravovaný certifikát a jako poskytovatele DNS používáte Cloudflare, ujistěte se, že na záznamu CNAME není povolený proxy server DNS.

záznam TXT

Při povolování bezplatného spravovaného certifikátu pro API Management nakonfigurujte také záznam TXT ve vaší zóně DNS, aby se vytvořilo vlastnictví názvu domény.

• Název záznamu je váš vlastní název domény s předponou apimuid. Příklad: apimuid.api.contoso.com.
• Hodnota je identifikátor vlastnictví domény poskytnutý vaší instancí služby API Management.

Když pomocí portálu nakonfigurujete bezplatný spravovaný certifikát pro vaši vlastní doménu, automaticky se zobrazí název a hodnota potřebného záznamu TXT.

Identifikátor vlastnictví domény můžete získat také voláním rozhraní REST API Get Domain Ownership Identifier .

Jak proxy server služby API Management reaguje certifikáty SSL v metodě handshake protokolu TLS

Při konfiguraci vlastní domény pro koncový bod brány můžete nastavit další vlastnosti, které určují, jak služba API Management reaguje certifikátem serveru v závislosti na požadavku klienta.

Klienti volají s hlavičkou SNI (Server Name Indication)

Pokud máte jednu nebo více vlastních domén nakonfigurovaných pro koncový bod brány, může služba API Management reagovat na požadavky HTTPS z těchto:

• Vlastní doména (například contoso.com)
• Výchozí doména (například apim-service-name.azure-api.net).

Na základě informací v hlavičce SNI služba API Management odpoví příslušným certifikátem serveru.

Klienti volají bez hlavičky SNI

Pokud používáte klienta, který neodesílá hlavičku SNI , služba API Management vytvoří odpovědi na základě následující logiky:

• Pokud má služba nakonfigurovanou jenom jednu vlastní doménu pro bránu, výchozím certifikátem je certifikát vydaný pro vlastní doménu brány.

• Pokud služba nakonfigurovala více vlastních domén pro bránu (podporovanou ve vrstvě Developer a Premium ), můžete výchozí certifikát určit nastavením výchozí vlastnostiSslBinding na true ("defaultSslBinding":"true"). Na portálu zaškrtněte políčko Výchozí vazba SSL .

  Pokud vlastnost nenastavíte, výchozí certifikát je certifikát vystavený výchozí doméně brány hostované na *.azure-api.netadrese .

Podpora požadavku PUT/POST s velkou datovou částí

Proxy server služby API Management podporuje požadavky s velkými datovými částmi (>40 kB) při použití certifikátů na straně klienta v protokolu HTTPS. Chcete-li zabránit zablokování požadavku serveru, můžete nastavit vlastnost negotiateClientCertificate na hodnotu true ("negotiateClientCertificate": "true") v názvu hostitele brány. Na portálu zaškrtněte políčko Vyjednat klientský certifikát .

Pokud je vlastnost nastavena na true, klientský certifikát se vyžádá v době připojení SSL/TLS před jakoukoli výměnou požadavků HTTP. Vzhledem k tomu, že nastavení platí na úrovni názvu hostitele brány , všechny požadavky na připojení se ptají na klientský certifikát. Toto omezení můžete obejít a nakonfigurovat až 20 vlastních domén pro bránu (podporuje se jenom na úrovni Premium ).

Omezení pro vlastní název domény na úrovních v2

V současné době služba API Management ve vrstvách Standard v2 a Premium v2 vyžaduje veřejně přeložitelný název DNS, který povoluje provoz do koncového bodu brány. Pokud pro koncový bod brány nakonfigurujete vlastní název domény, musí být tento název veřejně přeložitelný, nikoli omezený na privátní zónu DNS.

Jako alternativní řešení ve scénářích, kdy omezíte veřejný přístup k bráně a nakonfigurujete název privátní domény, můžete službu Application Gateway nastavit tak, aby přijímala provoz v názvu privátní domény a směruje ho do koncového bodu brány instance služby API Management. Ukázkovou architekturu najdete v tomto úložišti GitHubu.

Řešení potíží: Rotace certifikátů pro název hostitele z Azure Key Vault selhala

Kvůli změně konfigurace nebo problému s připojením nemusí instance služby API Management po aktualizaci nebo obnovení certifikátu ze služby Azure Key Vault načíst certifikát názvu hostitele. Když k tomu dojde, vaše instance služby API Management bude dál používat certifikát uložený v mezipaměti, dokud neobdrží aktualizovaný certifikát. Pokud vyprší platnost certifikátu uloženého v mezipaměti, zablokuje se provoz modulu runtime do brány. Jakákoli nadřazená služba, jako je Application Gateway, která používá konfiguraci certifikátu názvu hostitele, může také zablokovat provoz směrem k bráně, pokud je použit certifikát v mezipaměti s expirovanou platností.

Pokud chcete tento problém zmírnit, ověřte, že trezor klíčů existuje a že je certifikát uložený v trezoru klíčů. Pokud je vaše instance služby API Management nasazená ve virtuální síti, ověřte odchozí připojení ke značce služby AzureKeyVault. Zkontrolujte, jestli existuje spravovaná identita použitá pro přístup k trezoru klíčů. Ověřte oprávnění spravované identity pro přístup k trezoru klíčů. Podrobné kroky konfigurace najdete v části Nastavení vlastního názvu domény – Key Vault výše v tomto článku. Po obnovení konfigurace se certifikát názvu hostitele během 4 hodin aktualizuje ve službě API Management.

Související obsah

Upgradujte a škálujte vaši službu