API Management でクライアント証明書認証を使用して API を保護する方法

  • [アーティクル]

適用対象: すべての API Management レベル

API Management には、クライアント証明書と相互 TLS 認証を使用して API へのアクセス (つまりクライアントから API Management へのアクセス) を保護する機能が備わっています。 接続しているクライアントによって提示される証明書を検証し、ポリシー式を使用して証明書のプロパティを目的の値に対して確認することができます。

クライアント証明書を使用して API のバックエンド サービスへの (つまり、API Management からバックエンドへの) アクセスをセキュリティで保護する方法については、クライアント証明書認証を使用してバックエンド サービスをセキュリティで保護する方法に関するページを参照してください。

API の認可の概念的概要については、API Management での API に対する認証と認可をご覧ください。

証明書のオプション

証明書の検証では、API Management を API Management インスタンスで管理されている証明書と照合することができます。 API Management を使用してクライアント証明書を管理する場合は、次のオプションがあります。

  • Azure Key Vault で管理される証明書を参照する
  • API Management で証明書ファイルを直接追加する

API Management のセキュリティ向上に役立つため、キー コンテナー証明書を使用することをお勧めします。

  • キー コンテナーに格納されている証明書は、サービス間で再利用できます
  • キー コンテナーに格納されている証明書には、きめ細かいアクセス ポリシーを適用できます
  • キー コンテナーで更新された証明書は、API Management で自動的にローテーションされます。 キー コンテナー内で更新が行われると、4 時間以内に API Management 内の証明書が更新されます。 また、Azure portal または管理 REST API を使用して、証明書を手動で更新することもできます。

前提条件

  • API Management サービス インスタンスをまだ作成していない場合は、API Management サービス インスタンスの作成に関するページを参照してください。

  • Azure キー コンテナーでの管理用の証明書とパスワードにアクセスするか、API Management サービスにアップロードする必要があります。 証明書は CER または PFX の形式である必要があります。 自己署名証明書も許可されます。

    自己署名証明書を使用する場合は、信頼されたルート証明書と中間 CA 証明書も API Management インスタンスにインストールします。

    Note

    証明書検証用の CA 証明書は従量課金レベルではサポートされていません。

キー コンテナー統合の前提条件

  1. まだキー コンテナーがない場合は作成します。 キー コンテナーを作成する手順については、「クイックスタート: Azure portal を使用してキー コンテナーを作成する」を参照してください。

    キー コンテナーに証明書を作成またはインポートする方法については、「クイック スタート: Azure portal を使用して Azure Key Vault から証明書の設定と取得を行う」を参照してください。

  2. API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。

キー コンテナーへのアクセスを構成する

  1. ポータルで、キー コンテナーに移動します。

  2. 左側のメニューで [アクセス構成] を選択し、構成されているアクセス許可モデルをメモします。

  3. アクセス許可モデルに応じて、API Management マネージド ID のキー コンテナー アクセス ポリシーまたは Azure RBAC アクセスを構成します。

    キー コンテナー アクセス ポリシーを追加する手順は、以下のとおりです。

    1. 左側のメニューで、[アクセス ポリシー] を選択します。
    2. [アクセス ポリシー] ページで、[+ 作成] を選択します。
    3. [アクセス許可] タブの [シークレットのアクセス許可] で、[取得] と [リスト] を選択し、[次へ] を選択します。
    4. [プリンシパル] タブの [Select principal] (プリンシパルの選択) で、マネージド ID のリソース名を検索し、[次へ] を選択します。 システムによって割り当てられた ID を使用している場合、プリンシパルは API Management インスタンスの名前です。
    5. もう一度 [次へ] を選択します [確認および作成] タブで、 [作成] を選択します。

    Azure RBAC アクセスを構成する手順は、以下のとおりです。

    1. 左側のメニューで [アクセス制御 (IAM)] を選択します。
    2. [アクセス制御 (IAM)] ページで、[ロールの割り当てを追加] を選択します。
    3. [ロール] タブで [キー コンテナー シークレット ユーザー] を選択します。
    4. [メンバー] タブで、[マネージド ID]>[+ Select members] (+ メンバーの選択) を選択します。
    5. [Select managed identity] (マネージド ID の選択) ページで、API Management インスタンスに関連付けられているシステム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択し、[選択] を選択します。
    6. [レビューと割り当て] を選択します。

Key Vault ファイアウォールの要件

キー コンテナーで Key Vault ファイアウォールが有効になっている場合、追加要件は次のとおりです。

  • キー コンテナーにアクセスするには、API Management インスタンスのシステムによって割り当てられたマネージド ID を使用する必要があります。

  • Key Vault ファイアウォールで、 [Allow Trusted Microsoft Services to bypass this firewall](信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可する) オプションを有効にします。

  • Azure API Management に追加する証明書またはシークレットを選択するときに、ローカル クライアントの IP アドレスがキー コンテナーへの一時的なアクセスを許可されるようにする必要があります。 詳細については、「Azure Key Vault のネットワーク設定を構成する」を参照してください。

    構成が完了したら、キー コンテナーのファイアウォールでクライアント アドレスをブロックできます。

仮想ネットワークの要件

API Management インスタンスが仮想ネットワークにデプロイされている場合は、次のネットワーク設定も構成してください。

  • API Management サブネットで Azure Key Vault へのサービス エンドポイントを有効にします。
  • AzureKeyVault と AzureActiveDirectory のサービス タグへの送信トラフィックを許可するネットワーク セキュリティ グループ (NSG) 規則を構成します。

詳細については、VNet で Azure API Management を設定するときのネットワーク構成に関する記事を参照してください。

キー コンテナー証明書を追加する

「キー コンテナー統合の前提条件」を参照してください。

重要

API Management インスタンスにキー コンテナー証明書を追加する場合は、キー コンテナーのシークレットを一覧表示するアクセス許可が必要です。

注意事項

API Management でキー コンテナー証明書を使用する場合は、証明書、キー コンテナー、またはキー コンテナーにアクセスするために使用するマネージド ID を削除しないように注意してください。

API Management にキー コンテナー証明書を追加するには、次の操作を行います。

  1. Azure portal で、API Management インスタンスに移動します。

  2. [セキュリティ] の [証明書] を選択します。

  3. [証明書]>[+ 追加] を選択します。

  4. [ID] に、希望の名前を入力します。

  5. [証明書] で、 [キー コンテナー] を選択します。

  6. キー コンテナー証明書の識別子を入力するか、 [選択] を選択してキー コンテナーから証明書を選択します。

    重要

    キー コンテナー証明書の識別子を自分で入力する場合は、バージョン情報が含まれていないことを確認してください。 そうしないと、キー コンテナーで更新が行われた後に証明書が API Management で自動的にローテーションされません。

  7. [クライアント ID] で、システムによって割り当てられた、または既存のユーザー割り当てのマネージド ID を選択します。 API Management サービスでのマネージド ID の追加または変更方法については、こちらを参照してください。

    Note

    ID には、キー コンテナーから証明書を取得および一覧表示するためのアクセス許可が必要です。 キー コンテナーへのアクセスをまだ構成していない場合は、必要なアクセス許可を使用して ID を自動的に構成できるように、API Management によってプロンプトが表示されます。

  8. [追加] を選択します。

    ポータルでキー コンテナー証明書を API Management に追加するスクリーンショット。

  9. [保存] を選択します。

証明書のアップロード

API Management にクライアント証明書をアップロードするには、次の操作を行います。

  1. Azure portal で、API Management インスタンスに移動します。

  2. [セキュリティ] の [証明書] を選択します。

  3. [証明書]>[+ 追加] を選択します。

  4. [ID] に、希望の名前を入力します。

  5. [証明書] で、 [カスタム] を選択します。

  6. 証明書 .pfx ファイルを参照して選択し、そのパスワードを入力します。

  7. [追加] を選択します。

    ポータルでクライアント証明書を API Management にアップロードするスクリーンショット。

  8. [保存] を選択します。

Note

証明書を使用して API Management にクライアントを認証するだけの場合は、CER ファイルをアップロードできます。

API Management インスタンスでクライアント証明書の受信と検証を有効にする

Developer、Basic、Standard、または Premium レベル

Developer、Basic、Basic v2、Standard、Standard v2、または Premium レベルで HTTP/2 経由でクライアント証明書を受信して確認するには、下に示すように、[カスタム ドメイン] ブレードで [クライアント証明書のネゴシエート] 設定を有効にする必要があります。

[Negotiate client certificate] (クライアント証明書をネゴシエートする)

Consumption レベル

従量課金レベルでクライアント証明書を受信して確認するには、下に示すように、[カスタム ドメイン] ブレードで [クライアント証明書を要求する] の設定を有効にする必要があります。

[Request client certificate] (クライアント証明書を要求する)

クライアント証明書を検証するためのポリシー

validate-client-certificate ポリシーを使用して、API Management インスタンスでホストされている API へのアクセスに使用されるクライアント証明書の 1 つまたは複数の属性を検証します。

証明書の発行者、サブジェクト、拇印、証明書がオンライン失効リストに対して検証されるかどうかなど、1 つまたは複数の属性を検証するようにポリシーを構成します。

コンテキスト変数を使用した証明書の検証

context 変数を使用してポリシー式を作成し、クライアント証明書を確認することもできます。 次のセクションの例では、context.Request.Certificate プロパティと他の context プロパティを使用した式を示します。

Note

API Management ゲートウェイ エンドポイントが Application Gateway を介して公開されている場合、相互証明書認証が正しく機能しない可能性があります。 これは、Application Gateway がレイヤー 7 ロード バランサーとして機能し、バックエンド API Management サービスとの個別の SSL 接続を確立するためです。 そのため、最初の HTTP 要求でクライアントによってアタッチされた証明書は APIM に転送されません。 ただし、回避策として、サーバー変数オプションを使用して証明書を送信できます。 詳細な手順については、「相互認証サーバー変数」を参照してください。

重要

  • 2021 年 5 月以降、context.Request.Certificate プロパティで証明書が要求されるのは、API Management インスタンスの hostnameConfiguration で negotiateClientCertificate プロパティが True に設定されている場合のみとなりました。 既定では、negotiateClientCertificate は False に設定されます。
  • クライアントで TLS 再ネゴシエーションが無効になっている場合は、context.Request.Certificate プロパティを使用して証明書を要求するときに TLS エラーが表示されることがあります。 これが発生した場合は、クライアントで TLS 再ネゴシエーション設定を有効にします。
  • API Management v2 レベルでは、証明書の再ネゴシエーションはサポートされていません。

発行者とサブジェクトの確認

以下のポリシーを構成して、クライアント証明書の発行者とサブジェクトを確認できます。

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

証明書失効リストの確認を無効にするには、context.Request.Certificate.Verify() の代わりに context.Request.Certificate.VerifyNoRevocation() を使用します。 クライアント証明書が自己署名済みである場合、context.Request.Certificate.Verify() と context.Request.Certificate.VerifyNoRevocation() が機能するには、ルート (または中間) の CA 証明書を API Management にアップロードする必要があります。

拇印の確認

以下のポリシーを構成して、クライアント証明書の拇印を確認できます。

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

証明書失効リストの確認を無効にするには、context.Request.Certificate.Verify() の代わりに context.Request.Certificate.VerifyNoRevocation() を使用します。 クライアント証明書が自己署名済みである場合、context.Request.Certificate.Verify() と context.Request.Certificate.VerifyNoRevocation() が機能するには、ルート (または中間) の CA 証明書を API Management にアップロードする必要があります。

API Management にアップロードされた証明書に対する拇印の確認

以下の例では、API Management にアップロードされた証明書に対して、クライアント証明書の拇印を確認する方法を示しています。

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

証明書失効リストの確認を無効にするには、context.Request.Certificate.Verify() の代わりに context.Request.Certificate.VerifyNoRevocation() を使用します。 クライアント証明書が自己署名済みである場合、context.Request.Certificate.Verify() と context.Request.Certificate.VerifyNoRevocation() が機能するには、ルート (または中間) の CA 証明書を API Management にアップロードする必要があります。

ヒント

この記事で説明されているクライアント証明書のデッドロックに関する問題が、要求が凍結する、要求がタイムアウト後に 403 Forbidden 状態コードになる、context.Request.Certificate が null である、などのいくつかの形で現れる場合があります。 この問題は通常、コンテンツの長さが約 60KB 以上ある POST および PUT 要求に影響を与えます。 この問題が発生しないようにするには、このドキュメントの最初の画像で示すように、[カスタム ドメイン] ブレードにある目的のホスト名の [クライアント証明書のネゴシエート] の設定を有効にします。 この機能は、Consumption レベルでは使用できません。

次の手順