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

[アーティクル]
10/30/2024

適用対象: すべての 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 証明書は従量課金レベルではサポートされていません。

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

Note

現在、この機能はワークスペースでは使用できません。

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

キーコンテナーに証明書を作成またはインポートする方法については、「クイックスタート: Azure portal を使用して Azure Key Vault から証明書の設定と取得を行う」を参照してください。
API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。

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

ポータルで、キーコンテナーに移動します。
左側のメニューで [アクセス構成] を選択し、構成されているアクセス許可モデルをメモします。
アクセス許可モデルに応じて、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 にキーコンテナー証明書を追加するには、次の操作を行います。

Azure portal で、API Management インスタンスに移動します。
[セキュリティ] の [証明書] を選択します。
[証明書]>[+ 追加] を選択します。
[ID] に、希望の名前を入力します。
[証明書] で、 [キーコンテナー] を選択します。
キーコンテナー証明書の識別子を入力するか、 [選択] を選択してキーコンテナーから証明書を選択します。

重要

キーコンテナー証明書の識別子を自分で入力する場合は、バージョン情報が含まれていないことを確認してください。そうしないと、キーコンテナーで更新が行われた後に証明書が API Management で自動的にローテーションされません。
[クライアント ID] で、システムによって割り当てられた、または既存のユーザー割り当てのマネージド ID を選択します。 API Management サービスでのマネージド ID の追加または変更方法については、こちらを参照してください。

Note

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

証明書のアップロード

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

Azure portal で、API Management インスタンスに移動します。
[セキュリティ] の [証明書] を選択します。
[証明書]>[+ 追加] を選択します。
[ID] に、希望の名前を入力します。
[証明書] で、 [カスタム] を選択します。
証明書 .pfx ファイルを参照して選択し、そのパスワードを入力します。
[追加] を選択します。
[保存] を選択します。

Note

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

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

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

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

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

従量課金、Basic v2、Standard v2 または Premium v2 レベル

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

[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

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

ヒント

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

次の方法で共有

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

証明書のオプション

前提条件

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

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

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

仮想ネットワークの要件

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

証明書のアップロード

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

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

従量課金、Basic v2、Standard v2 または Premium v2 レベル

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

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

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

拇印の確認

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

次の手順

フィードバック

その他のリソース

次の方法で共有

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

証明書のオプション

前提条件

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

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

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

仮想ネットワークの要件

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

証明書のアップロード

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

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

従量課金、Basic v2、Standard v2 または Premium v2 レベル

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

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

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

拇印の確認

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

次の手順

フィードバック

その他のリソース

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

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

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