次の方法で共有

Azure API Management ポリシーで名前付きの値を使用する

  • [アーティクル]

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

API Management ポリシーはシステムの強力な機能の 1 つで、これを使用することにより、発行者は構成を通じて API の動作を変更できます。 API の要求または応答に対して順に実行される一連のステートメントが集まってポリシーが形成されます。 ポリシー ステートメントは、リテラル テキストの値、ポリシーの式、名前付きの値を使用して構築できます。

"名前付きの値" は、各 API Management インスタンス内にある名前と値ペアのグローバル　コレクションです。 コレクション内の項目の数に制限はありません。 名前付きの値を使用すると、すべての API の構成とポリシーで定数文字列の値とシークレットを管理できます。

Azure portal 内の名前付きの値

値型

Type Description
普通紙 リテラル文字列またはポリシー式
Secret API Management によって暗号化されるリテラル文字列またはポリシー式
Key vault Azure Key Vault に格納されているシークレットの識別子。

プレーンテキストの値またはシークレットにはポリシー式を含めることができます。 たとえば、式 @(DateTime.Now.ToString()) では、現在の日付と時刻を含む文字列が返されます。

名前付きの値の属性の詳細については、API Management の REST API リファレンスのページを参照してください。

キー コンテナーのシークレット

シークレットの値は、API Management 内に暗号化された文字列 (カスタム シークレット) として、または Azure Key Vault 内のシークレットを参照することによって格納できます。

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

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

Note

Azure Key Vault に格納されるシークレットは、1 から 4,096 文字にする必要があります。API Management では、この制限を超える値を取得できないためです。

前提条件

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

Note

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

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

  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 インスタンスにキー コンテナー シークレットを追加する場合は、キー コンテナーのシークレットを一覧表示するアクセス許可が必要です。

注意事項

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

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

  2. [API] で、 [名前付きの値]>[+追加] を選択します。

  3. [名前] 識別子を入力し、ポリシー内でプロパティを参照するために使用される [表示名] を入力します。

  4. [値の種類] で、 [キー コンテナー] を選択します。

  5. キー コンテナーのシークレットの識別子 (バージョンなし) を入力するか、 [選択] を選択し、キー コンテナーからシークレットを選択します。

    重要

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

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

    Note

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

  7. 名前付きの値を整理するのに役立つ 1 つ以上の省略可能なタグを追加して、保存します。

  8. ［作成］ を選択します

    キー コンテナーのシークレットの値を追加する

プレーンまたはシークレットの値を API Management に追加する

  1. Azure portal で、API Management インスタンスに移動します。
  2. [API] で、 [名前付きの値]>[+追加] を選択します。
  3. [名前] 識別子を入力し、ポリシー内でプロパティを参照するために使用される [表示名] を入力します。
  4. [値の種類] で、 [プレーン] または [シークレット] を選択します。
  5. [値] に、文字列またはポリシー式を入力します。
  6. 名前付きの値を整理するのに役立つ 1 つ以上の省略可能なタグを追加して、保存します。
  7. ［作成］ を選択します

名前付きの値が作成されたら、名前を選択して編集できます。 表示名を変更すると、その名前付きの値を参照するすべてのポリシーが、その新しい表示名を使用するように自動的に更新されます。

名前付きの値を使用する

このセクションの例では、次の表に示す名前付きの値が使用されます。

名前 値 Secret
ContosoHeader TrackingId 誤
ContosoHeaderValue •••••••••••••••••••••• True
ExpressionProperty @(DateTime.Now.ToString()) 誤
ContosoHeaderValue2 This is a header value. 誤

ポリシーで名前付きの値を使用するには、{{ContosoHeader}} のように、二重の中括弧でその表示名を囲みます。次に例を示します。

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

この例では、ContosoHeader は set-header ポリシーのヘッダー名として使用されており、ContosoHeaderValue はそのヘッダーの値として使用されています。 このポリシーが API Management ゲートウェイの要求または応答で評価されるとき、{{ContosoHeader}} と {{ContosoHeaderValue}} はそれぞれの値で置換されます。

名前付きの値は前の例のように完全な属性または要素値として使用できますが、次の例に示すように、リテラル テキスト表現に挿入するか、その一部と組み合わせることもできます:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

名前付きの値にはポリシー式を含めることもできます。 次の例では、ExpressionProperty 式が使用されています。

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

このポリシーが評価されるとき、{{ExpressionProperty}} はその値 @(DateTime.Now.ToString()) に置き換えられます。 値がポリシー式であるため、式が評価され、ポリシーがその実行に進みます。

これは、名前付きの値が範囲内にあるポリシーを持つ操作を呼び出すことによって、Azure portal または開発者ポータルでテストできます。 次の例では、前の 2 つのサンプル set-header ポリシーと名前付きの値で操作が呼び出されています。 応答に、ポリシーと名前付きの値を使用して構成された 2 つのカスタム ヘッダーが含まれていることに注意してください。

API 応答をテストする

送信 API トレースを見て、前の 2 つのサンプル ポリシーと名前付きの値が含まれる呼び出しを探すと、名前付きの値が挿入された 2 つの set-header ポリシーと、ポリシー式が含まれる名前付きの値のポリシー式評価を確認できます。

API Inspector トレース

文字列補間は、名前付き値でも使用できます。

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

CustomHeader の値は The URL encoded value is This+is+a+header+value. になります。

注意事項

ポリシーで Azure Key Vault 内のシークレットが参照されている場合、キー・コンテナーの値は、そのAPI 要求トレースが有効になっているサブスクリプションにアクセスできるユーザーに表示されます。

名前付きの値にはポリシー式を含めることができますが、他の名前付きの値を含めることはできません。 名前付きの値参照を含むテキストが Text: {{MyProperty}} などの値に使用されている場合、その参照は解決されず、置き換えられません。

名前付きの値を削除する

名前付きの値を削除するには、名前を選択して、コンテキスト メニュー ( ... ) から [削除] を選択します。

重要

名前付きの値がいずれかの API Management ポリシーで参照されている場合は、それが使用されているすべてのポリシーから削除してからでないと削除できません。

次のステップ