分享方式:


設定 Azure API 管理執行個體的自訂網域名稱

適用於:所有 APIM 層

當您在 Azure 雲端中建立 Azure API 管理服務執行個體時,Azure 會為其指派 azure-api.net 子網域 (例如 apim-service-name.azure-api.net)。 您也可以使用自己的自訂網域名稱來公開 API 管理端點,例如 contoso.com。 本文說明如何將現有的自訂 DNS 名稱對應至 Azure API 管理執行個體所公開的端點。

重要

API 管理只接受主機標頭值符合下列條件的要求:

  • 閘道的預設網域名稱
  • 閘道已設定的任何自訂網域名稱

注意

目前工作區閘道不支援自定義功能變數名稱。

必要條件

  • API 管理執行個體。 如需詳細資訊,請參閱建立 Azure API 管理執行個體

  • 您或您的組織所擁有的自訂網域名稱。 本文未提供如何取得自訂網域名稱的指示。

  • (選用) 含有公開和私密金鑰的有效憑證 (.PFX)。 主體或主體別名 (SAN) 必須符合網域名稱 (這可讓 API 管理執行個體安全地透過 TLS 公開 URL)。

    請參閱網域憑證選項

  • 在 DNS 伺服器上代管的 DNS 記錄,以將自訂網域名稱對應至 API 管理執行個體的預設網域名稱。 本主題未提供如何代管 DNS 記錄的指示。

    如需必要記錄的詳細資訊,請參閱本文稍後的 DNS 設定

自訂網域的端點

您可以對數個 API 管理端點指派自訂網域名稱。 目前有下列端點可用:

端點 預設
閘道 預設值是:<apim-service-name>.azure-api.net。 閘道是使用層中唯一可用於設定的端點。

新增自訂閘道網域之後,預設閘道端點設定仍可供使用。
開發人員入口網站 預設值是:<apim-service-name>.developer.azure-api.net
管理 預設值是:<apim-service-name>.management.azure-api.net
設定 API (v2) 預設值是:<apim-service-name>.configuration.azure-api.net
SCM 預設值是:<apim-service-name>.scm.azure-api.net

考量

  • 您可以更新服務層級中支援的任何端點。 一般來說,客戶會更新閘道 (此閘道用來呼叫透過 API 管理公開的 API) 和開發人員入口網站 (開發人員入口網站 URL)。
  • 當您設定自訂閘道網域名稱之後,預設閘道端點仍可供使用且無法刪除。 對於您使用自訂網域名稱設定的其他 APIM 端點 (例如開發人員入口網站),已無法再使用預設端點。
  • 只有 API 管理執行個體擁有者可以在內部使用管理SCM 端點。 這些端點較不常指派自訂網域名稱。
  • 進階層和開發人員層可支援設定閘道端點的多個主機名稱。
  • 除了使用層以外,所有層都支援萬用字元網域名稱,例如 *.contoso.com。 對 api.contoso.com 的要求,特定子網域憑證 (例如,api.contoso.com) 的優先順序高於萬用字元憑證 (*.contoso.com)。

網域憑證選項

API 管理支援自訂 TLS 憑證或從 Azure Key Vault 匯入的憑證。 您也可以啟用免費的受控憑證。

警告

如果您需要憑證關聯,請使用自訂網域名稱和自訂或 Key Vault 憑證,而不是預設憑證或免費的受控憑證。 建議您不要對未管理的憑證採取硬式相依性。

如果您已經有協力廠商提供者的私人憑證,您可以將該憑證上傳至 API 管理執行個體。 憑證必須符合下列需求 (如果您啟用由 API 管理所管理的免費憑證,則該憑證已符合這些需求):

  • 匯出為 PFX 檔案 (以三重 DES 加密並選擇性地使用密碼保護)。
  • 包含長度至少 2048 位元的私密金鑰
  • 包含憑證鏈結中的所有中繼憑證和根憑證。

設定自訂網域名稱 - 入口網站

根據您要使用的網域憑證選擇步驟。

  1. 在 Azure 入口網站中瀏覽至您的 API 管理執行個體
  2. 從左側導覽中,選取 [自訂網域]
  3. 選取 [+新增],或選取您要更新的現有端點
  4. 在右側視窗中,選取自訂網域端點的 [類型]
  5. 在 [主機名稱] 欄位中,指定您想要使用的名稱。 例如: api.contoso.com
  6. 在 [憑證] 下方,選取 [自訂]
  7. 選取 [憑證檔案] 以選取並上傳憑證。
  8. 上傳有效的 .PFX 檔案,如果憑證受到密碼保護,則一併提供其密碼
  9. 設定閘道端點時,請視需要選取或取消選取其他選項,包括 [交涉用戶端憑證] 或 [預設 SSL 繫結]使用自定義憑證設定閘道網域
  10. 選取 [新增],或選取現有端點的 [更新]
  11. 選取 [儲存]。

DNS 組態

  • 設定自訂網域的 CNAME 記錄。
  • 使用 API 管理的免費受控憑證時,亦請設定 TXT 記錄來建立網域的擁有權。

注意

免費憑證由 DigiCert 所發行。 針對某些網域,您必須建立值為 0 issue digicert.comCAA 網域記錄,以明確允許 DigiCert 作為憑證簽發者。

CNAME 記錄

設定 CNAME 記錄,以從您的自訂網域名稱 (例如 api.contoso.com) 指向 API 管理服務主機名稱 (例如 <apim-service-name>.azure-api.net)。 為免 IP 位址變更,CNAME 記錄比 A 記錄更穩定。 如需詳細資訊,請參閱 Azure API 管理的 IP 位址API 管理常見問題集

注意

使用 CNAME 記錄時,某些網域註冊機構只允許您對應子網域 (如 www.contoso.com),而不是根名稱 (如 contoso.com)。 如需 CNAME 記錄的詳細資訊,請參閱註冊機構提供的文件或 IETF 網域名稱 - 實作與規格 (英文)。

警告

當您使用免費的受控憑證,並使用您的 DNS 提供者設定 CNAME 記錄時,請確定它會解析為預設的 APIM 服務主機名稱 (<apim-service-name>.azure-api.net)。 目前,如果 CNAME 記錄不會解析為預設的 APIM 主機名稱,APIM 就不會自動更新憑證。 例如,如果您使用免費受控憑證,並使用 Cloudflare 作為 DNS 提供者,請確定未在 CNAME 記錄上啟用 DNS Proxy。

TXT 記錄

啟用 API 管理的免費受控憑證時,亦請在 DNS 區域中設定 TXT 記錄,以建立網域名稱的擁有權。

  • 記錄名稱是您的自訂網域名稱,前面加上 apimuid。 範例:apimuid.api.contoso.com
  • 此值是您 API 管理執行個體所提供的網域擁有權識別碼。

當您使用入口網站來設定自訂網域的免費受控憑證時,系統會自動顯示必要 TXT 記錄的名稱和值。

您也可以呼叫取得網域擁有權識別碼 REST API,來取得網域擁有權識別碼。

API 管理 Proxy 伺服器如何在 TLS 交握中使用 SSL 憑證進行回應

設定閘道端點的自訂網域時,您可以設定其他屬性,以根據用戶端要求來判斷 API 管理如何使用伺服器憑證進行回應。

具有伺服器名稱指示 (SNI) 標頭的用戶端呼叫

如果您已針對閘道端點設定一或多個自訂網域,則 API 管理可以透過下列其中一個項目回應 HTTPS 要求:

  • 自訂網域 (例如:contoso.com)
  • 預設網域 (例如:apim-service-name.azure-api.net)。

根據 SNI 標頭中的資訊,API 管理會以適當的伺服器憑證進行回應。

不具有 SNI 標頭的用戶端呼叫

如果您使用的用戶端並不傳送 SNI 標頭,API 管理就會根據下列邏輯建立回應:

  • 如果服務只為閘道設定一個自訂網域,則預設憑證即為發給閘道自訂網域的憑證。

  • 如果服務已為閘道設定多個自訂網域 (支援開發人員層進階層),您可以將 defaultSslBinding 屬性設為 true ("defaultSslBinding":"true") 來指定預設憑證。 在入口網站中,選取 [預設 SSL 繫結] 核取方塊。

    如果您未設定此屬性,則預設憑證就是發給預設閘道網域 (裝載於 *.azure-api.net) 的憑證。

有大型承載之 PUT/POST 要求的支援

在 HTTPS 中使用用戶端憑證時,API 管理 Proxy 伺服器可支援具有大型承載 (>40 KB) 的要求。 若要防止系統凍結伺服器的要求,您可以在閘道主機名稱上將 negotiateClientCertificate 屬性設為 true ("negotiateClientCertificate": "true")。 在入口網站中,選取 [交涉用戶端憑證] 核取方塊。

如果將屬性設定為 true,系統就會在任何 HTTP 要求交換之前,於 SSL/TLS 連線時間要求用戶端憑證。 由於設定是套用在閘道主機名稱層級,因此所有連線要求都會要求用戶端憑證。 您可以為閘道設定最多 20 個自訂網域 (僅進階服務層支援此設定) 來解決這項限制。

下一步

升級和調整服務的規模