Azure API Management インスタンスのカスタム ドメイン名を構成するConfigure a custom domain name for your Azure API Management instance

Azure API Management サービス インスタンスを作成すると、Azure によって azure-api.net サブドメイン (例: apim-service-name.azure-api.net) に割り当てられます。When you create an Azure API Management service instance, Azure assigns it a subdomain of azure-api.net (for example, apim-service-name.azure-api.net). ただし、独自のカスタム ドメイン名 (contoso.com など) を使用する API Management エンドポイントを公開できます。However, you can expose your API Management endpoints using your own custom domain name, such as contoso.com. このチュートリアルでは、既存のカスタム DNS 名を、API Management インスタンスによって公開されるエンドポイントにマップする方法を説明します。This tutorial shows you how to map an existing custom DNS name to endpoints exposed by an API Management instance.

重要

API Management は、既定のドメイン名または構成されているいずれかのカスタム ドメイン名と一致するホスト ヘッダー値を持つ要求のみを受け入れます。API Management accepts only requests with host header values matching the default domain name or any of the configured custom domain names.

警告

アプリケーションのセキュリティを向上させるために証明書のピン留めを使用するお客様は、カスタム ドメイン名と、(既定の証明書ではない) お客様が管理する証明書を使用する必要があります。Customers who wish to use certificate pinning to improve the security of their applications must use a custom domain name and certificate which they manage, not the default certificate. 代わりに、既定の証明書をピン留めするお客様は、制御しない証明書のプロパティでハードの依存関係を取得することになります。この方法はお勧めしません。Customers that pin the default certificate instead will be taking a hard dependency on the properties of the certificate they don't control, which is not a recommended practice.

前提条件Prerequisites

この記事で説明されている手順を実行するには、以下が必要です。To perform the steps described in this article, you must have:

  • 有効な Azure サブスクリプションAn active Azure subscription.

    Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。If you don't have an Azure subscription, create a free account before you begin.

  • API Management インスタンス。An API Management instance. 詳細については、Azure API Management インスタンスの作成に関する記事を参照してください。For more information, see Create an Azure API Management instance.

  • 自分または自分の所属する組織が所有しているカスタム ドメイン名。A custom domain name that is owned by you or your organization. このトピックでは、カスタム ドメイン名を取得する手順は説明しません。This topic does not provide instructions on how to procure a custom domain name.

  • DNS サーバーでホストしている CNAME レコード。カスタム ドメイン名を API Management インスタンスの既定のドメイン名にマップするものです。A CNAME record hosted on a DNS server that maps the custom domain name to the default domain name of your API Management instance. このトピックでは、CNAME レコードをホストする手順は説明しません。This topic does not provide instructions on how to host a CNAME record.

  • パブリックおよびプライベート キー (.PFX) 付きの有効な証明書。You must have a valid certificate with a public and private key (.PFX). サブジェクトやサブジェクトの別名 (SAN) は、ドメイン名と一致している必要があります (これによって API Management インスタンスでは、TLS を通して URL を安全に公開することができます)。Subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over TLS).

Azure ポータルを使用してカスタム ドメイン名を設定するUse the Azure portal to set a custom domain name

  1. Azure portal で API Management インスタンスに移動します。Navigate to your API Management instance in the Azure portal.

  2. [カスタム ドメイン] をクリックします。Select Custom domains.

    カスタム ドメイン名を割り当てることができるエンドポイントは多数あります。There are a number of endpoints to which you can assign a custom domain name. 現時点では、次のエンドポイントを利用できます。Currently, the following endpoints are available:

    • ゲートウェイ (既定値: <apim-service-name>.azure-api.net)Gateway (default is: <apim-service-name>.azure-api.net),
    • ポータル (既定値: <apim-service-name>.portal.azure-api.net)Portal (default is: <apim-service-name>.portal.azure-api.net),
    • Management (既定値: <apim-service-name>.management.azure-api.net)Management (default is: <apim-service-name>.management.azure-api.net),
    • SCM (既定値: <apim-service-name>.scm.azure-api.net)SCM (default is: <apim-service-name>.scm.azure-api.net),
    • NewPortal (既定値: <apim-service-name>.developer.azure-api.net)NewPortal (default is: <apim-service-name>.developer.azure-api.net).

    注意

    従量課金レベルの構成で利用できるのは、 [ゲートウェイ] エンドポイントだけです。Only the Gateway endpoint is available for configuration in the Consumption tier. すべてのエンドポイントまたは一部を更新できます。You can update all of the endpoints or some of them. 通常、お客様は、ゲートウェイ (この URL を使用して API Management を通じて公開される API が呼び出されます) とポータル (開発者ポータルの URL) を更新します。Commonly, customers update Gateway (this URL is used to call the API exposed through API Management) and Portal (the developer portal URL). Management エンドポイントと SCM エンドポイントは、API Management インスタンス所有者だけが内部的に使用するため、カスタム ドメイン名が割り当てられることはほとんどありません。Management and SCM endpoints are used internally by the API Management instance owners only and thus are less frequently assigned a custom domain name. Premium レベルでは、ゲートウェイ エンドポイントに対する複数のホスト名の設定がサポートされます。The Premium tier supports setting multiple host names for the Gateway endpoint.

  3. 更新するエンドポイントを選択します。Select the endpoint that you want to update.

  4. 右側のウィンドウで [カスタム] をクリックします。In the window on the right, click Custom.

    • [カスタム ドメイン名] に、使用する名前を指定します。In the Custom domain name, specify the name you want to use. たとえば、「 api.contoso.com 」のように入力します。For example, api.contoso.com.
    • [証明書] で、Key Vault から証明書を選択します。In the Certificate, select a certificate from Key Vault. 証明書がパスワードで保護されている場合は、有効な .PFX ファイルをアップロードし、そのパスワードを指定することもできます。You can also upload a valid .PFX file and provide its Password, if the certificate is protected with a password.

    注意

    ワイルドカードを使用したドメイン名 (*.contoso.com など) は、従量課金レベル以外のあらゆるレベルでサポートされています。Wildcard domain names, e.g. *.contoso.com are supported in all tiers except the Consumption tier.

    ヒント

    Azure Key Vault を使用して証明書を管理し、それらを自動更新するように設定することをおすすめします。We recommend using Azure Key Vault for managing certificates and setting them to autorenew. Azure Key Vault を使用してカスタム ドメインの TLS/SSL 証明書を管理する場合は、証明書が、_シークレット_ではなく_証明書_として Key Vault に挿入されていることを確認してください。If you use Azure Key Vault to manage the custom domain TLS/SSL certificate, make sure the certificate is inserted into Key Vault as a certificate, not a secret.

    TLS/SSL 証明書を取得するには、証明書が格納されている Azure Key Vault に対するシークレットの一覧表示および取得のアクセス許可が、API Management に付与されている必要があります。To fetch a TLS/SSL certificate, API Management must have the list and get secrets permissions on the Azure Key Vault containing the certificate. Azure portal を使用している場合、必要なすべての構成手順が自動的に完了します。When using Azure portal all the necessary configuration steps will be completed automatically. コマンド ライン ツールまたは管理 API を使用している場合は、これらのアクセス許可を手動で付与する必要があります。When using command line tools or management API, these permissions must be granted manually. この処理は 2 段階の手順で実行されます。This is done in two steps. まず、API Management インスタンスのマネージド ID ページを使用して、マネージド ID が有効になっていることを確認し、そのページに表示されているプリンシパル ID を書き留めます。First, use Managed identities page on your API Management instance to make sure that Managed Identity is enabled and make a note of the principal id shown on that page. 次に、このプリンシパル ID にアクセス許可リストを提供し、証明書が格納されている Azure Key Vault に対するシークレットの取得アクセス許可を付与します。Second, give permission list and get secrets permissions to this principal id on the Azure Key Vault containing the certificate.

    証明書が自動更新されるように設定されている場合、API Management はサービスのダウンタイムなしに最新バージョンを自動的に取得します (お使いの API Management のレベルに SLA が含まれている場合 (つまり、Developer レベルを除くすべてのレベル))。If the certificate is set to autorenew, API Management will pick up the latest version automatically without any downtime to the service (if your API Management tier has SLA - i. e. in all tiers except the Developer tier).

  5. [適用] をクリックします。Click Apply.

    注意

    証明書を割り当てる処理は、デプロイのサイズによっては、15 分以上かかる場合があります。The process of assigning the certificate may take 15 minutes or more depending on size of deployment. Developer SKU にはダウンタイムがありますが、Basic 以上の SKU にはダウンタイムがありません。Developer SKU has downtime, Basic and higher SKUs do not have downtime.

APIM プロキシ サーバーが SSL 証明書を使用して TLS ハンドシェイクで応答する方法How APIM Proxy Server responds with SSL certificates in the TLS handshake

SNI ヘッダーを使用して呼び出すクライアントClients calling with SNI header

プロキシ用に 1 つ以上のカスタム ドメインが設定されている場合、APIM は、既定のドメイン (apim-service-name.azure-api.net など) だけでなく、そのカスタム ドメイン (contoso.com など) からの HTTPS 要求にも応答できます。If the customer has one or multiple custom domains configured for Proxy, APIM can respond to HTTPS requests from the custom domain(s) (for example, contoso.com) as well as default domain (for example, apim-service-name.azure-api.net). APIM は、Server Name Indication (SNI) ヘッダーの情報に基づいて、適切なサーバー証明書を使用して応答します。Based on the information in the Server Name Indication (SNI) header, APIM responds with appropriate server certificate.

SNI ヘッダーを使用せずに呼び出すクライアントClients calling without SNI header

SNI ヘッダーを送信しないクライアントを使用している場合、APIM は次のロジックに基づいて応答を作成します。If the customer is using a client, which does not send the SNI header, APIM creates responses based on the following logic:

  • このサービスにプロキシ用のカスタム ドメインが 1 つだけ設定されている場合、そのプロキシ カスタム ドメインに発行された証明書が既定の証明書になります。If the service has just one custom domain configured for Proxy, the Default Certificate is the certificate that was issued to the Proxy custom domain.
  • このサービスにプロキシ用のカスタム ドメインが複数設定されている場合 (Developer および Premium レベルでサポート)、お客様は既定の証明書を指定できます。If the service has configured multiple custom domains for Proxy (supported in the Developer and Premium tier), the customer can designate which certificate should be the default certificate. 既定の証明書を設定するには、defaultSslBinding プロパティを true に設定する ("defaultSslBinding":"true") 必要があります。To set the default certificate, the defaultSslBinding property should be set to true ("defaultSslBinding":"true"). お客様がこのプロパティを設定していない場合、既定の証明書は、*.azure-api.net でホストされる既定のプロキシ ドメインに発行された証明書になります。If the customer does not set the property, the default certificate is the certificate issued to default Proxy domain hosted at *.azure-api.net.

ペイロードの大きい PUT/POST 要求のサポートSupport for PUT/POST request with large payload

HTTPS でクライアント側の証明書を使用する場合、APIM プロキシ サーバーでペイロードの大きな要求 (40 KB を超えるペイロードなど) がサポートされます。APIM Proxy server supports request with large payload when using client-side certificates in HTTPS (for example, payload > 40 KB). サーバーの要求がフリーズしないように、プロキシ ホスト名に "negotiateClientCertificate": "true" プロパティを設定できます。To prevent the server's request from freezing, customers can set the property "negotiateClientCertificate": "true" on the Proxy hostname. このプロパティが true に設定されている場合、HTTP 要求の交換前の SSL/TLS 接続時に、クライアント証明書が要求されます。If the property is set to true, the client certificate is requested at SSL/TLS connection time, before any HTTP request exchange. この設定はプロキシ ホスト名レベルで適用されるため、すべての接続要求でクライアント証明書が求められます。Since the setting applies at the Proxy Hostname level, all connection requests ask for the client certificate. プロキシ用のカスタム ドメインを最大 20 個設定して (Premium レベルでのみサポート)、この制限を回避できます。Customers can configure up to 20 custom domains for Proxy (only supported in the Premium tier) and work around this limitation.

DNS の構成DNS configuration

カスタム ドメイン名の DNS を構成するときは、次の 2 つのオプションがあります。When configuring DNS for your custom domain name, you have two options:

  • 構成したカスタム ドメイン名のエンドポイントを指す CNAME レコードを構成する。Configure a CNAME-record that points to the endpoint of your configured custom domain name.
  • API Management ゲートウェイの IP アドレスを指す A レコードを構成する。Configure an A-record that points to your API Management gateway IP address.

注意

API Management インスタンスの IP アドレスは静的ですが、いくつかのシナリオで変更される可能性があります。Although the API Managment instance IP address is static, it may change in a few scenarios. このため、カスタム ドメインを構成するときは CNAME を使用することをお勧めします。Because of this it's recommended to use CNAME when configuring custom domain. DNS 構成方法を選択するときは、このことを考慮してください。Take that into consideration when choosing DNS configuration method. 詳細については、IP に関するドキュメント記事API Management の FAQ を参照してください。Read more in the the IP documentation article and the API Management FAQ.

次のステップNext steps

サービスのアップグレードとスケーリングを行うUpgrade and scale your service