API Management のアクセス制限ポリシー

この記事では、API Management のアクセス制限ポリシーについて説明します。

ポリシーの詳細:

アクセス制限ポリシー

ヒント

さまざまな目的に応じて異なるスコープでアクセス制限ポリシーを使用できます。 たとえば、API 全体を AAD 認証を使用して保護するには、validate-azure-ad-token ポリシーを API レベルに適用します。または、これを API 操作レベルに適用して、claims を使用してきめ細かい制御を行うこともできます。

HTTP ヘッダーを確認する

check-header ポリシーを使用して、HTTP ヘッダーの指定がもれなく要求に含まれるようにします。 必要に応じて、ヘッダーに特定の値が指定されているかどうか、または許可されている範囲内の値かどうかを確認できます。 チェックに失敗した場合、このポリシーに従って要求の処理は終了し、ポリシーで指定した HTTP 状態コードとエラー メッセージが返されます。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<check-header name="header name" failed-check-httpcode="code" failed-check-error-message="message" ignore-case="true">
    <value>Value1</value>
    <value>Value2</value>
</check-header>

<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
    <value>f6dc69a089844cf6b2019bae6d36fac8</value>
</check-header>

要素

名前 説明 必須
check-header ルート要素。 はい
value 許可される HTTP ヘッダーの値。 複数の要素を指定した場合、いずれかの値に一致すればチェックは成功とみなされます。 いいえ

属性

名前 説明 必須 Default
failed-check-error-message ヘッダーが存在しないかヘッダーが無効な値である場合に HTTP 応答本文で返されるエラー メッセージ。 このメッセージ内では、特殊文字を適切にエスケープする必要があります。 はい 該当なし
failed-check-httpcode ヘッダーが存在しないかヘッダーが無効な値である場合に返される HTTP 状態コード。 はい 該当なし
header-name チェックする HTTP ヘッダーの名前。 はい 該当なし
ignore-case True または False に設定できます。 True に設定した場合、ヘッダー値と許容される値セットとの比較時に大文字と小文字は区別されません。 はい 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound、outbound

  • ポリシー スコープ: すべてのスコープ

認可コンテキストを取得する

get-authorization-contextポリシーを使用して、API Management インスタンスで構成された指定された認可 (プレビュー) の認可コンテキストを取得します。

ポリシーは、構成された認可プロバイダーから認可トークンと更新トークンをフェッチして格納します。

identity-type=jwtを構成した場合は、JWT トークンを検証する必要があります。 このトークンの対象ユーザーはhttps://azure-api.net/authorization-managerでなければなりません。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<get-authorization-context
    provider-id="authorization provider id" 
    authorization-id="authorization id" 
    context-variable-name="variable name" 
    identity-type="managed | jwt"
    identity="JWT bearer token"
    ignore-error="true | false" />

例 1: トークンを取得する

<!-- Add to inbound policy. -->
<get-authorization-context 
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="managed" 
    identity="@(context.Request.Headers["Authorization"][0].Replace("Bearer ", ""))"
    ignore-error="false" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

例 2: 動的に設定された属性を使用してトークンを取得する

<!-- Add to inbound policy. -->
<get-authorization-context 
  provider-id="@(context.Request.Url.Query.GetValueOrDefault("authorizationProviderId"))" 
  authorization-id="@(context.Request.Url.Query.GetValueOrDefault("authorizationId"))" context-variable-name="auth-context" 
  ignore-error="false" 
  identity-type="managed" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

例 3: バックエンド呼び出しにトークンをアタッチする

<!-- Add to inbound policy. -->
<get-authorization-context
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="managed" 
    ignore-error="false" />
<!-- Attach the token to the backend call -->
<set-header name="Authorization" exists-action="override">
    <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
</set-header>

例 4: 受信要求からトークンを取得し、トークンを返す

<!-- Add to inbound policy. -->
<get-authorization-context 
    provider-id="github-01" 
    authorization-id="auth-01" 
    context-variable-name="auth-context" 
    identity-type="jwt" 
    identity="@(context.Request.Headers["Authorization"][0].Replace("Bearer ", ""))"
    ignore-error="false" />
<!-- Return the token -->
<return-response>
    <set-status code="200" />
    <set-body template="none">@(((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</set-body>
</return-response>

要素

名前 説明 必須
認可コンテキストの取得 ルート要素。 はい

属性

名前 説明 必須 Default
provider-id 認可プロバイダーのリソース識別子。 はい
authorization-id 認可リソース識別子。 はい
コンテキスト変数名 Authorizationオブジェクトを受け取るコンテキスト変数の名前。 はい
identity-type 認可アクセス ポリシーに対して検査される ID の型。
- managed: API Management サービスのマネージド ID。
- jwt: identity属性で 指定された JWT ベアラー トークン。
No キー管理
identity 認可アクセス許可に対して検査される Azure AD JWT ベアラー トークン。 jwt以外のidentity-typeの場合は無視されます。

予想される要求:
- 対象ユーザー: https://azure-api.net/authorization-manager
- oid: アクセス許可オブジェクト ID
- tid: アクセス許可テナント ID
No
ignore-error Boolean です。 認可コンテキストを取得するとエラーが発生する場合 (たとえば、認可リソースが見つからないか、エラー状態にある場合):
- true: コンテキスト変数に null の値が割り当てられます。
- false: 500 を返します
いいえ false

認可オブジェクト

Authorization コンテキスト変数は、型Authorizationのオブジェクトを受け取ります。

class Authorization
{
    public string AccessToken { get; }
    public IReadOnlyDictionary<string, object> Claims { get; }
}
プロパティ名 説明
AccessToken バックエンド HTTP 要求を承認するためのベアラー アクセス トークン。
Claims 承認サーバーのトークン応答 API から返された要求 ( RFC6749#section-5.1 を参照)。

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound

  • ポリシー スコープ: すべてのスコープ

呼び出しレートをサブスクリプション別に制限する

rate-limit ポリシーは、指定期間あたりの呼び出しレートを指定数に制限することで、サブスクリプションごとに API 使用量の急増を防ぎます。 この呼び出しレートを超えると、呼び出し元は 429 Too Many Requests 応答状態コードを受信します。

レート上限とクォータの違いについては、レート上限とクォータに関するページを参照してください。

重要

  • このポリシーは、ポリシー ドキュメントごとに 1 回のみ使用できます。
  • このポリシー内のポリシー属性では、ポリシー式は使用できません。

注意事項

スロットリングのアーキテクチャは分散型の性質のため、レートの制限は完全に正確ではありません。 許可される要求の構成された数と実際の数の差異は、要求のボリュームとレート、バックエンドの待ち時間、およびその他の要因によって異なります。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<rate-limit calls="number" renewal-period="seconds">
    <api name="API name" id="API id" calls="number" renewal-period="seconds">
        <operation name="operation name" id="operation id" calls="number" renewal-period="seconds" 
        retry-after-header-name="custom header name, replaces default 'Retry-After'" 
        retry-after-variable-name="policy expression variable name"
        remaining-calls-header-name="header name"  
        remaining-calls-variable-name="policy expression variable name"
        total-calls-header-name="header name"/>
    </api>
</rate-limit>

次の例では、サブスクリプションあたりのレート上限が 90 秒ごとに 20 回です。 ポリシーを実行するたびに、その期間内に許可されている残りの呼び出しが変数 remainingCallsPerSubscription に格納されます。

<policies>
    <inbound>
        <base />
        <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

要素

名前 説明 必須
rate-limit ルート要素。 はい
api 製品内の API に対して呼び出しレート制限をかけるには、これらの要素を 1 つまたは複数追加します。 製品と API の呼び出しレート制限は別々に適用されます。 API は name または id のいずれかによって参照できます。 両方の属性が提供された場合、id が使用されて name は無視されます。 いいえ
操作 API 内の操作に対して呼び出しレート制限をかけるには、これらの要素を 1 つまたは複数追加します。 製品、API、および操作の呼び出しレート制限は別々に適用されます。 操作は name または id のいずれかによって参照できます。 両方の属性が提供された場合、id が使用されて name は無視されます。 いいえ

属性

名前 説明 必須 Default
name レート制限の適用対象になる API の名前。 はい 該当なし
calls renewal-period で指定された期間中に許可される最大の呼び出し合計数。 はい 該当なし
renewal-period 許可された要求の数が、calls で指定された値を超えてはならないスライディング ウィンドウの長さ (秒単位)。 許可される最大値: 300 秒。 はい 該当なし
retry-after-header-name 値が指定された呼び出しレートを超えた後の推奨される再試行間隔 (秒単位) であるカスタム応答ヘッダーの名前。 いいえ Retry-After
retry-after-variable-name 指定した呼び出しレートを超えた後の推奨される再試行間隔 (秒単位) を格納するポリシー式変数の名前。 いいえ なし
remaining-calls-header-name 各ポリシーの実行後の値が、renewal-period で指定された時間間隔に対して許可されている残りの呼び出しの数である応答ヘッダーの名前。 いいえ 該当なし
remaining-calls-variable-name 各ポリシーの実行後に、renewal-period で指定された時間間隔に対して許可されている残りの呼び出しの数を格納する、ポリシー式変数の名前。 いいえ N/A
total-calls-header-name 値が calls で指定された値である応答ヘッダーの名前。 いいえ 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound

  • ポリシー スコープ: 製品、API、操作

呼び出しレートをキー別に制限する

重要

この機能は、API Management の従量課金レベルでは使用できません。

rate-limit-by-key ポリシーは、指定期間あたりの呼び出しレートを指定数に制限することで、キーごとに API 使用量の急増を防ぎます。 キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。 必要に応じて増分条件を追加し、制限に対してカウントする要求を指定することもできます。 この呼び出しレートを超えると、呼び出し元は 429 Too Many Requests 応答状態コードを受信します。

レート上限とクォータの違いについては、レート上限とクォータに関するページを参照してください。

このポリシーの詳細と例については、「Azure API Management を使用した高度な要求スロットル」を参照してください。

注意事項

スロットリングのアーキテクチャは分散型の性質のため、レートの制限は完全に正確ではありません。 許可される要求の構成された数と実際の数の差異は、要求のボリュームとレート、バックエンドの待ち時間、およびその他の要因によって異なります。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   increment-count="number"
                   counter-key="key value" 
                   retry-after-header-name="custom header name, replaces default 'Retry-After'" 
                   retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  
                   remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/> 

次の例では、60 秒ごとに 10 回のレート制限のキーに呼び出し元 IP を設定しています。 ポリシーを実行するたびに、その期間内に許可されている残りの呼び出しが変数 remainingCallsPerIP に格納されます。

<policies>
    <inbound>
        <base />
        <rate-limit-by-key  calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

要素

名前 説明 必須
rate-limit-by-key ルート要素。 はい

属性

名前 説明 必須 Default
calls renewal-period で指定した期間中に許容する最大呼び出し総数。 ポリシー式は許可されます。 はい 該当なし
counter-key レート制限ポリシーに使用するキー。 キー値ごとに、ポリシーが構成されているすべてのスコープに対して 1 つのカウンターが使用されます。 はい 該当なし
increment-condition レートに対して要求の件数をカウントするかどうかを指定するブール式 (true)。 いいえ 該当なし
increment-count 要求ごとにカウンターを増やす数。 いいえ 1
renewal-period 許可された要求の数が、calls で指定された値を超えてはならないスライディング ウィンドウの長さ (秒単位)。 ポリシー式は許可されます。 許可される最大値: 300 秒。 はい 該当なし
retry-after-header-name 値が指定された呼び出しレートを超えた後の推奨される再試行間隔 (秒単位) であるカスタム応答ヘッダーの名前。 いいえ Retry-After
retry-after-variable-name 指定した呼び出しレートを超えた後の推奨される再試行間隔 (秒単位) を格納するポリシー式変数の名前。 いいえ なし
remaining-calls-header-name 各ポリシーの実行後の値が、renewal-period で指定された時間間隔に対して許可されている残りの呼び出しの数である応答ヘッダーの名前。 いいえ 該当なし
remaining-calls-variable-name 各ポリシーの実行後に、renewal-period で指定された時間間隔に対して許可されている残りの呼び出しの数を格納する、ポリシー式変数の名前。 いいえ N/A
total-calls-header-name 値が calls で指定された値である応答ヘッダーの名前。 いいえ 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound

  • ポリシー スコープ: すべてのスコープ

呼び出し元 IP を制限する

ip-filter ポリシーは、特定の IP アドレスやアドレス範囲からの呼び出しをフィルター処理 (許可または拒否) します。

注意

ポリシーは、直前の呼び出し元の IP アドレスをフィルター処理します。 ただし、API Management のホスト場所が Application Gateway の背後である場合、その IP アドレス (API 要求の発信元ではない) がポリシーの処理対象になります。 現時点では、X-Forwarded-For 内の IP アドレスは対象になりません。

注意

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address" />
</ip-filter>

次の例のポリシーでは、指定された単一の IP アドレスまたは IP アドレス範囲のどちらかから受け取った要求しか許可されません。

<ip-filter action="allow">
    <address>13.66.201.169</address>
    <address-range from="13.66.140.128" to="13.66.140.143" />
</ip-filter>

要素

名前 説明 必須
ip-filter ルート要素。 はい
address フィルターを適用する単一の IP アドレスを指定します。 address 要素または address-range 要素は少なくとも 1 つ必要です。
address-range from="address" to="address" フィルターを適用する IP アドレスの範囲を指定します。 address 要素または address-range 要素は少なくとも 1 つ必要です。

属性

名前 説明 必須 Default
address-range from="address" to="address" アクセスを許可または拒否する IP アドレスの範囲。 address-range 要素を使用する場合は必須です。 該当なし
ip-filter action="allow | forbid" 指定した IP アドレスおよび IP アドレス範囲に対する呼び出しを許可するかどうかを指定します。 はい 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

注意

このポリシーを複数のスコープで構成した場合、IP フィルタリングはポリシー定義のポリシー評価の順序で適用されます。

使用量のクォータをサブスクリプション別に設定する

quota ポリシーは、更新可能な呼び出しまたは有効期間中の呼び出しのボリュームと帯域幅クォータの両方またはそのどちらかをサブスクリプションに基づいて適用します。 クォータを超えると、呼び出し元は応答状態コード 403 Forbidden を受け取ります。応答には、推奨される再試行間隔 (秒単位) の値を示す、Retry-After ヘッダーが含まれます。

レート上限とクォータの違いについては、レート上限とクォータに関するページを参照してください。

重要

  • このポリシーは、ポリシー ドキュメントごとに 1 回のみ使用できます。
  • ポリシー式は、このポリシーのポリシー属性に使用できません。

注意

基になるコンピューティング リソースがサービス プラットフォームで再起動されると、クォータに達した後も API Management がしばらくの間要求を処理し続ける可能性があります。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<quota calls="number" bandwidth="kilobytes" renewal-period="seconds">
    <api name="API name" id="API id" calls="number">
        <operation name="operation name" id="operation id" calls="number" />
    </api>
</quota>

<policies>
    <inbound>
        <base />
        <quota calls="10000" bandwidth="40000" renewal-period="3600" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

要素

名前 説明 必須
quota ルート要素。 はい
api 製品内の API に対して呼び出しクォータをかけるには、これらの要素を 1 つまたは複数追加します。 製品と API の呼び出しクォータは別々に適用されます。 API は name または id のいずれかによって参照できます。 両方の属性が提供された場合、id が使用されて name は無視されます。 いいえ
操作 API 内の操作に対して呼び出しクォータをかけるには、これらの要素を 1 つまたは複数追加します。 製品、API、および操作の呼び出しクォータは別々に適用されます。 操作は name または id のいずれかによって参照できます。 両方の属性が提供された場合、id が使用されて name は無視されます。 いいえ

属性

名前 説明 必須 Default
name クォータを適用する API または操作の名前。 はい 該当なし
bandwidth renewal-period で指定した期間中に許可する最大合計キロバイト数。 callsbandwidth のいずれかまたは両方と同時に指定する必要があります。 該当なし
calls renewal-period で指定した期間中に許容する最大呼び出し総数。 callsbandwidth のいずれかまたは両方と同時に指定する必要があります。 該当なし
renewal-period クォータがリセットされた後の固定ウィンドウの長さ (秒単位)。 各期間の開始は、サブスクリプションの開始時刻を基準にして計算されます。 renewal-period0 に設定すると、この期間は無限に設定されます。 はい 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: 製品

使用量のクォータをキー別に設定する

重要

この機能は、API Management の従量課金レベルでは使用できません。

quota-by-key ポリシーは、更新可能な呼び出しまたは有効期間中の呼び出しのボリュームと帯域幅クォータの両方またはそのどちらかをキーに基づいて適用します。 キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。 必要に応じて増分条件を追加し、クォータに対してカウントする要求を指定することもできます。 複数のポリシーによって同じキー値が増分される場合は、要求ごとに 1 回だけ増分されます。 クォータを超えると、呼び出し元は応答状態コード 403 Forbidden を受け取ります。応答には、推奨される再試行間隔 (秒単位) の値を示す、Retry-After ヘッダーが含まれます。

このポリシーの詳細と例については、「Azure API Management を使用した高度な要求スロットル」を参照してください。

レート上限とクォータの違いについては、レート上限とクォータに関するページを参照してください。

注意

基になるコンピューティング リソースがサービス プラットフォームで再起動されると、クォータに達した後も API Management がしばらくの間要求を処理し続ける可能性があります。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<quota-by-key calls="number"
              bandwidth="kilobytes"
              renewal-period="seconds"
              increment-condition="condition"
              counter-key="key value"
              first-period-start="date-time" />

次のサンプルでは、クォータのキーに呼び出し元 IP を設定しています。

<policies>
    <inbound>
        <base />
        <quota-by-key calls="10000" bandwidth="40000" renewal-period="3600"
                      increment-condition="@(context.Response.StatusCode >= 200 && context.Response.StatusCode < 400)"
                      counter-key="@(context.Request.IpAddress)" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

要素

名前 説明 必須
quota ルート要素。 はい

属性

名前 説明 必須 Default
bandwidth renewal-period で指定した期間中に許可する最大合計キロバイト数。 callsbandwidth のいずれかまたは両方と同時に指定する必要があります。 該当なし
calls renewal-period で指定した期間中に許容する最大呼び出し総数。 callsbandwidth のいずれかまたは両方と同時に指定する必要があります。 該当なし
counter-key クォータ ポリシーに使用するキー。 キー値ごとに、ポリシーが構成されているすべてのスコープに対して 1 つのカウンターが使用されます。 はい 該当なし
increment-condition クォータに対して要求の件数をカウントするかどうかを指定するブール式 (true) いいえ 該当なし
renewal-period クォータがリセットされた後の固定ウィンドウの長さ (秒単位)。 各期間の開始は、first-perdiod-start に対して相対的に計算されます。 renewal-period0 に設定すると、この期間は無限に設定されます。 はい なし
first-period-start クォータの更新期間の開始日付と時刻は、yyyy-MM-ddTHH:mm:ssZとISO 8601 標準で指定されています。 いいえ 0001-01-01T00:00:00Z

注意

counter-key 属性値は、他の API 間で合計値を共有したくない場合は、API Management のすべての API で一意でなければなりません。

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

Azure Active Directory のトークンの検証

このvalidate-azure-ad-token ポリシーでは、Azure Active Directory サービスによって提供された JSON Web トークン (JWT) の存在と有効性が強制されます。 JWT は、ポリシー式またはコンテキスト変数を使用して指定された HTTP ヘッダー、クエリ パラメーター、または値から抽出できます。

ポリシー ステートメント

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Azure Active Directory</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Azure Active Directory</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
</validate-azure-ad-token>

単純なトークン検証

次のポリシーは、 validate-azure-ad-token ポリシーの最小フォームです。 Bearerスキームを使用して、Authorizationヘッダーに JWT が提供されることを想定しています。 この例では、名前付き値を使用して Azure AD テナント ID とクライアント アプリケーション ID を指定します。

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

対象ユーザーと要求が正しいことを検証する

次のポリシーでは、対象ユーザーがAPI Management インスタンスのホスト名であり、 ctry 要求がUSであることを確認します。 ホスト名はポリシー式を使用して提供され、Azure AD テナント ID とクライアント アプリケーション ID は名前付き値を使用して提供されます。 デコードされた JWT は、検証後に jwt 変数に提供されます。

省略可能な要求の詳細については、「 アプリにオプションの要求を提供する」を参照してください。

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

要素

要素 説明 必須
validate-azure-ad-token ルート要素。 はい
audiences トークン上に存在する可能性がある、許容される対象ユーザー クレームの一覧を記載します。 対象ユーザー値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 少なくとも 1 つの対象ユーザーを指定する必要があります。 いいえ
backend-application-ids 受け入れ可能なバックエンド アプリケーション ID のリストが含まれます。 これは、オプションの構成に高度なケースでのみ必要であり、通常は削除できます。 いいえ
client-application-ids 受け入れ可能なクライアント アプリケーション ID のリストが含まれます。 アプリケーションIDの要素が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 アプリケーションIDを少なくとも 1 つ指定する必要があります。 はい
required-claims トークン上に存在すると予測される、有効とみなすクレームの一覧を記載します。 match 属性を all に設定した場合、検証が成功するにはポリシー内のクレーム値がすべてトークン内に存在する必要があります。 match 属性を any に設定した場合、検証が成功するには少なくとも 1 つのクレームがトークン内に存在する必要があります。 いいえ

属性

名前 説明 必須 Default
failed-validation-error-message JWT が検証で不合格となった場合に HTTP 応答本文で返すエラー メッセージ。 このメッセージ内では、特殊文字を適切にエスケープする必要があります。 いいえ 既定のエラー メッセージは検証の問題によって異なります ("JWT not present" (JWT が存在しません) など)。
failed-validation-httpcode JWT が検証で不合格となった場合に返す HTTP 状態コード。 いいえ 401
header-name トークンを保持する HTTP ヘッダーの名前。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし
match claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。 次のいずれかの値になります。

- all - 検証が成功するには、ポリシー内のクレーム値がすべてトークン内に存在する必要があります。

- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。
No all
output-token-variable-name 文字列 をオンにします。 成功したトークンの検証において、Jwt 型のオブジェクトとしてトークン値を受け取るコンテキスト変数の名前 いいえ 該当なし
query-parameter-name トークンを保持するクエリ パラメーターの名前。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし
separator 文字列。 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。 いいえ 該当なし
token-value トークンを含む文字列を返す式。 トークン値の一部として Bearer を返すことはできません。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

制限事項

このポリシーは、パブリック Azure クラウド内の Azure Active Directory テナントでのみ使用できます。 リージョン クラウドまたはアクセスが制限された Azure クラウドで構成されたテナントはサポートされていません。

JWT を検証する

validate-jwt ポリシーは、指定した HTTP ヘッダーまたは指定したクエリ パラメーターまたは指定した価値のマッチングから抽出した JSON Web トークン (JWT) が存在し、有効であることを必須にします。

重要

validate-jwt ポリシーは、require-expiration-time 属性を指定し false に設定した場合を除いて、exp 登録クレームが JWT トークンに含まれていることを必須にします。 validate-jwt ポリシーでは HS256 署名アルゴリズムと RS256 署名アルゴリズムがサポートされています。 HS256 の場合、キーをポリシー内に base64 エンコード形式でインライン指定する必要があります。 RS256 の場合、キーは、Open ID 構成エンドポイント経由で指定するか、公開キーまたは公開キーのモジュラスとエクスポーネントのペアが PFX 形式で含まれるアップロードされた証明書の ID を提供することで指定することができます。 validate-jwt ポリシーでは、暗号化アルゴリズムA128CBC-HS256、A192CBC-HS384、A256CBC-HS512 を使用して対称キーで暗号化されたトークンがサポートされます。

注意

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<validate-jwt
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="http status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    require-expiration-time="true|false"
    require-scheme="scheme"
    require-signed-tokens="true|false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, e.g. https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <required-claims>
    <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
      <value>claim value as it is expected to appear in the token</value>
      <!-- if there is more than one allowed values, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed values, then add additional value elements -->
  </required-claims>
</validate-jwt>

単純なトークン検証

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

RSA 証明書を使用したトークン検証

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Azure Active Directory のトークン検証

注意

validate-azure-ad-token ポリシーを 使用して、Azure Active Directory に対してトークンを検証します。

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Azure Active Directory B2C のトークン検証

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

トークン クレームに基づいて操作へのアクセスを承認する

次の例では、JWT を検証するポリシーを使用して、トークン クレーム値に基づいて操作へのアクセスを承認する方法を示します。

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

要素

要素 説明 必須
validate-jwt ルート要素。 はい
audiences トークン上に存在する可能性がある、許容される対象ユーザー クレームの一覧を記載します。 対象ユーザー値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 少なくとも 1 つの対象ユーザーを指定する必要があります。 いいえ
issuer-signing-keys 署名付きトークンの検証に使用する base64 でエンコードされたセキュリティ キーの一覧。 セキュリティ キーが複数存在する場合は、すべてのキーが処理される (この場合検証は失敗します) かいずれかのキーの検証が成功する (トークンのロールオーバーに使用されます) まで、各キーについて検証が行われます。 キー要素には、kid クレームとの照合に使用される id 属性を必要に応じて設定できます。

または、次のものを使用して発行者の署名キーを指定します。

- <key certificate-id="mycertificate" /> という形式の certificate-id を使用して、API Management にアップロードされた証明書エンティティの識別子を指定します
- <key n="<modulus>" e="<exponent>" /> という形式の RSA のモジュラス n とエクスポーネント e のペアを使用して、base64url エンコード形式で RSA パラメーターを指定します
いいえ
decryption-keys トークンの暗号化を解除するために使用される Base64 でエンコードされたキーの一覧。 セキュリティ キーが複数存在する場合は、すべてのキーが処理される (この場合検証は失敗します) かいずれかのキーの検証が成功するまで、各キーについて検証が行われます。 キー要素には、kid クレームとの照合に使用される id 属性を必要に応じて設定できます。

または、次のものを使用して復号化キーを指定します。

- <key certificate-id="mycertificate" /> という形式の certificate-id を使用して、API Management にアップロードされた証明書エンティティの識別子を指定します
いいえ
issuers トークンを発行した、許容されるプリンシパルの一覧。 発行者の値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 いいえ
openid-config これらの要素の 1 つ以上を追加して、署名キーと発行者を取得可能な準拠している OpenID 構成エンドポイントを指定します。

JSON Web Key Set (JWKS) を含む構成は、エンドポイントから 1 時間ごとにプルされ、キャッシュされます。 検証対象のトークンが、キャッシュされた構成に存在しない検証キー (kid 要求を使用) を参照している場合、または取得に失敗した場合、API Management はエンドポイントから最大 5 分に 1 回プルします。 これらの間隔は予告なしに変更されることがあります。
いいえ
required-claims トークン上に存在すると予測される、有効とみなすクレームの一覧を記載します。 match 属性を all に設定した場合、検証が成功するにはポリシー内のクレーム値がすべてトークン内に存在する必要があります。 match 属性を any に設定した場合、検証が成功するには少なくとも 1 つのクレームがトークン内に存在する必要があります。 いいえ

属性

名前 説明 必須 Default
clock-skew 期間。 トークンの発行者と API Management インスタンスのシステム クロックの間に予想される最大時間差を指定するために使用します。 いいえ 0 秒
failed-validation-error-message JWT が検証で不合格となった場合に HTTP 応答本文で返すエラー メッセージ。 このメッセージ内では、特殊文字を適切にエスケープする必要があります。 いいえ 既定のエラー メッセージは検証の問題によって異なります ("JWT not present" (JWT が存在しません) など)。
failed-validation-httpcode JWT が検証で不合格となった場合に返す HTTP 状態コード。 いいえ 401
header-name トークンを保持する HTTP ヘッダーの名前。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし
query-parameter-name トークンを保持するクエリ パラメーターの名前。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし
token-value トークンを含む文字列を返す式。 トークン値の一部として Bearer を返すことはできません。 header-namequery-parameter-nametoken-value のいずれかを指定する必要があります。 該当なし
id key 要素の id 属性を使用すると、署名検証用の適切なキーを確認するためにトークン内の kid クレーム (存在する場合) と照合する文字列を指定できます。 いいえ 該当なし
match claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。 次のいずれかの値になります。

- all - 検証が成功するには、ポリシー内のクレーム値がすべてトークン内に存在する必要があります。

- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。
No all
require-expiration-time ブール型。 トークン内に有効期限クレームが存在する必要があるかどうかを指定します。 いいえ true
require-scheme トークン スキームの名前、(例: 「Bearer」)。 この属性が設定されている場合、ポリシーは指定したスキームが承認ヘッダーの値に存在していることを確認します。 いいえ 該当なし
require-signed-tokens ブール型。 トークンに署名が必要かどうかを指定します。 いいえ true
separator 文字列。 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。 いいえ 該当なし
url Open ID 構成メタデータを取得可能な Open ID 構成エンドポイントの URL。 応答は、URL https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata で定義されている仕様に従っている必要があります。

Azure Active Directory の場合は、次のようなアプリ登録で構成された OpenID Connect のメタデータ エンドポイントを使用します。
- (v2) https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- (v2 マルチテナント) https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- (v1) https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration

ディレクトリ テナント名または ID を置き換えます (例: {tenant-name}contoso.onmicrosoft.com に置き換えます)。
はい 該当なし
output-token-variable-name 文字列 をオンにします。 成功したトークンの検証において、Jwt 型のオブジェクトとしてトークン値を受け取るコンテキスト変数の名前 いいえ 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

クライアント証明書を検証する

validate-client-certificate ポリシーを使用して、クライアントから API Management インスタンスに提示された証明書が、1つまたは複数の証明書 ID のサブジェクトや発行者などの指定した検証規則と要求に一致することを強制します。

クライアント証明書は、有効と見なされるために、最上位要素の属性で定義されているすべての検証規則と一致し、定義済みの ID の少なくとも 1 つに対して定義されているすべての要求と一致している必要があります。

このポリシーを使用して、受信証明書のプロパティと必要なプロパティを確認します。 また、このポリシーを使用して、次のような場合にクライアント証明書の既定の検証を上書きします。

  • マネージド ゲートウェイへのクライアント要求を検証するためにカスタム CA 証明書をアップロードした場合
  • セルフマネージド ゲートウェイへのクライアント要求を検証するようにカスタム証明機関を構成した場合

カスタム CA 証明書と証明機関の詳細については、「Azure API Management でカスタム CA 証明書を追加する方法」を参照してください。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<validate-client-certificate 
    validate-revocation="true|false"
    validate-trust="true|false" 
    validate-not-before="true|false" 
    validate-not-after="true|false" 
    ignore-error="true|false">
    <identities>
        <identity 
            thumbprint="certificate thumbprint"
            serial-number="certificate serial number"
            common-name="certificate common name"
            subject="certificate subject string"
            dns-name="certificate DNS name"
            issuer-subject="certificate issuer"
            issuer-thumbprint="certificate issuer thumbprint"
            issuer-certificate-id="certificate identifier" />
    </identities>
</validate-client-certificate> 

次の例では、ポリシーの既定の検証規則に一致するようにクライアント証明書を検証し、サブジェクトと発行者の名前が指定された値に一致するかどうかを確認します。

<validate-client-certificate 
    validate-revocation="true" 
    validate-trust="true" 
    validate-not-before="true" 
    validate-not-after="true" 
    ignore-error="false">
    <identities>
        <identity
            subject="C=US, ST=Illinois, L=Chicago, O=Contoso Corp., CN=*.contoso.com"
            issuer-subject="C=BE, O=FabrikamSign nv-sa, OU=Root CA, CN=FabrikamSign Root CA" />
    </identities>
</validate-client-certificate> 

要素

要素 説明 必須
validate-client-certificate ルート要素。 はい
ID クライアント証明書に対して定義されたクレームのある ID の一覧が含まれます。 いいえ

属性

名前 説明 必須 Default
validate-revocation ブール型。 オンライン失効リストに対して証明書を検証するかどうかを指定します。  True
validate-trust ブール型。 信頼されたCAにチェーンを正常に構築できない場合に検証が失敗するかどうかを指定します。 True
validate-not-before ブール型。 現在の時刻に対して値を検証します。 True
validate-not-after ブール型。 現在の時刻に対して値を検証します。 True
ignore-error Boolean です。 ポリシーを次のハンドラーに進めるか、検証に失敗した場合に ON-ERROR にジャンプするかを指定します。 no False
ID 文字列 をオンにします。 証明書を有効にする証明書要求値の組み合わせ。 はい N/A
thumbprint 証明書のサムプリント。 N/A
serial-number 証明書のシリアル番号。 N/A
common-name 証明書の共通名 (サブジェクト文字列の一部)。 N/A
subject サブジェクト文字列。 識別名の形式に従う必要があります。 N/A
dns-name サブジェクトの代替名要求内の dnsName エントリの値。 該当なし
issuer-subject 発行者のサブジェクト。 識別名の形式に従う必要があります。 N/A
issuer-thumbprint 発行者の拇印。 N/A
issuer-certificate-id 発行者の公開キーを表す既存の証明書エンティティの識別子。 他の発行者属性と同時に指定できません。 該当なし

使用法

このポリシーは、次のポリシー セクションスコープで使用できます。

  • ポリシー セクション: inbound
  • ポリシー スコープ: すべてのスコープ

次のステップ

ポリシーに対する処理の詳細については、次のトピックを参照してください。