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

このトピックでは、次の API Management ポリシーについて説明します。This topic provides a reference for the following API Management policies. ポリシーを追加および構成する方法については、「 Azure API Management のポリシー」をご覧ください。For information on adding and configuring policies, see Policies in API Management.

アクセス制限ポリシーAccess restriction policies

HTTP ヘッダーを確認するCheck HTTP header

check-header ポリシーを使用して、HTTP ヘッダーの指定がもれなく要求に含まれるようにします。Use the check-header policy to enforce that a request has a specified HTTP header. 必要に応じて、ヘッダーに特定の値が指定されているかどうか、または許可されている範囲内の値かどうかを確認できます。You can optionally check to see if the header has a specific value or check for a range of allowed values. チェックに失敗した場合、このポリシーに従って要求の処理は終了し、ポリシーで指定した HTTP 状態コードとエラー メッセージが返されます。If the check fails, the policy terminates request processing and returns the HTTP status code and error message specified by the policy.

ポリシー ステートメントPolicy statement

<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>  

Example

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

要素Elements

NameName 説明Description 必須Required
check-headercheck-header ルート要素。Root element. [はい]Yes
valuevalue 許可される HTTP ヘッダーの値。Allowed HTTP header value. 複数の要素を指定した場合、いずれかの値に一致すればチェックは成功とみなされます。When multiple value elements are specified, the check is considered a success if any one of the values is a match. いいえ No

属性Attributes

NameName 説明Description 必須Required 既定値Default
failed-check-error-messagefailed-check-error-message ヘッダーが存在しないかヘッダーが無効な値である場合に HTTP 応答本文で返されるエラー メッセージ。Error message to return in the HTTP response body if the header doesn't exist or has an invalid value. このメッセージ内では、特殊文字を適切にエスケープする必要があります。This message must have any special characters properly escaped. [はい]Yes 該当なしN/A
failed-check-httpcodefailed-check-httpcode ヘッダーが存在しないかヘッダーが無効な値である場合に返される HTTP 状態コード。HTTP Status code to return if the header doesn't exist or has an invalid value. [はい]Yes 該当なしN/A
header-nameheader-name チェックする HTTP ヘッダーの名前。The name of the HTTP Header to check. [はい]Yes 該当なしN/A
ignore-caseignore-case True または False に設定できます。Can be set to True or False. True に設定した場合、ヘッダー値と許容される値セットとの比較時に大文字と小文字は区別されません。If set to True case is ignored when the header value is compared against the set of acceptable values. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

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

  • ポリシー スコープ: グローバル、製品、API、操作Policy scopes: global, product, API, operation

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

rate-limit ポリシーは、指定期間あたりの呼び出しレートを指定数に制限することで、サブスクリプションごとに API 使用量の急増を防ぎます。The rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period. このポリシーがトリガーされると、呼び出し元は 429 Too Many Requests 応答状態コードを受け取ります。When this policy is triggered the caller receives a 429 Too Many Requests response status code.

重要

このポリシーは、ポリシー ドキュメントごとに 1 回のみ使用できます。This policy can be used only once per policy document.

このポリシー内のポリシー属性では、ポリシー式は使用できません。Policy expressions cannot be used in any of the policy attributes for this policy.

ポリシー ステートメントPolicy statement

<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" />  
    </api>  
</rate-limit>  

Example

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

要素Elements

NameName 説明Description 必須Required
set-limitset-limit ルート要素。Root element. [はい]Yes
apiapi 製品内の API に対して呼び出しレート制限をかけるには、これらの要素を 1 つまたは複数追加します。Add one or more of these elements to impose a call rate limit on APIs within the product. 製品と API の呼び出しレート制限は別々に適用されます。Product and API call rate limits are applied independently. API は name または id のいずれかによって参照できます。API can be referenced either via name or id. 両方の属性が提供された場合、id が使用されて name は無視されます。If both attributes are provided, id will be used and name will be ignored. いいえ No
operationoperation API 内の操作に対して呼び出しレート制限をかけるには、これらの要素を 1 つまたは複数追加します。Add one or more of these elements to impose a call rate limit on operations within an API. 製品、API、および操作の呼び出しレート制限は別々に適用されます。Product, API, and operation call rate limits are applied independently. 操作は name または id のいずれかによって参照できます。Operation can be referenced either via name or id. 両方の属性が提供された場合、id が使用されて name は無視されます。If both attributes are provided, id will be used and name will be ignored. いいえ No

属性Attributes

NameName 説明Description 必須Required 既定値Default
namename レート制限の適用対象になる API の名前。The name of the API for which to apply the rate limit. [はい]Yes 該当なしN/A
callscalls renewal-period で指定した期間中に許容する最大呼び出し総数。The maximum total number of calls allowed during the time interval specified in the renewal-period. [はい]Yes 該当なしN/A
renewal-periodrenewal-period クォータのリセット間隔 (秒単位)。The time period in seconds after which the quota resets. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

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

  • ポリシー スコープ: 製品Policy scopes: product

呼び出しレートをキー別に制限するLimit call rate by key

重要

この機能は、API Management の従量課金レベルでは使用できません。This feature is unavailable in the Consumption tier of API Management.

rate-limit-by-key ポリシーは、指定期間あたりの呼び出しレートを指定数に制限することで、キーごとに API 使用量の急増を防ぎます。The rate-limit-by-key policy prevents API usage spikes on a per key basis by limiting the call rate to a specified number per a specified time period. キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。The key can have an arbitrary string value and is typically provided using a policy expression. 必要に応じて増分条件を追加し、制限に対してカウントする要求を指定することもできます。Optional increment condition can be added to specify which requests should be counted towards the limit. このポリシーがトリガーされると、呼び出し元は 429 Too Many Requests 応答状態コードを受け取ります。When this policy is triggered the caller receives a 429 Too Many Requests response status code.

このポリシーの詳細と例については、「Azure API Management を使用した高度な要求スロットル」を参照してください。For more information and examples of this policy, see Advanced request throttling with Azure API Management.

ポリシー ステートメントPolicy statement

<rate-limit-by-key calls="number"  
                   renewal-period="seconds"   
                   increment-condition="condition"   
                   counter-key="key value" />  

Example

次のサンプルでは、レート制限のキーに呼び出し元 IP を設定しています。In the following example, the rate limit is keyed by the caller IP address.

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

要素Elements

NameName 説明Description 必須Required
set-limitset-limit ルート要素。Root element. [はい]Yes

属性Attributes

NameName 説明Description 必須Required 既定値Default
callscalls renewal-period で指定した期間中に許容する最大呼び出し総数。The maximum total number of calls allowed during the time interval specified in the renewal-period. [はい]Yes 該当なしN/A
counter-keycounter-key レート制限ポリシーに使用するキー。The key to use for the rate limit policy. [はい]Yes 該当なしN/A
increment-conditionincrement-condition クォータに対して要求の件数をカウントするかどうかを指定するブール式です (true)。The boolean expression specifying if the request should be counted towards the quota (true). いいえ No 該当なしN/A
renewal-periodrenewal-period クォータのリセット間隔 (秒単位)。The time period in seconds after which the quota resets. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

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

  • ポリシー スコープ: グローバル、製品、API、操作Policy scopes: global, product, API, operation

呼び出し元 IP を制限するRestrict caller IPs

ip-filter ポリシーは、特定の IP アドレスやアドレス範囲からの呼び出しをフィルター処理 (許可または拒否) します。The ip-filter policy filters (allows/denies) calls from specific IP addresses and/or address ranges.

ポリシー ステートメントPolicy statement

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

Example

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

要素Elements

NameName 説明Description 必須Required
ip-filterip-filter ルート要素。Root element. [はい]Yes
addressaddress フィルターを適用する単一の IP アドレスを指定します。Specifies a single IP address on which to filter. address 要素または address-range 要素は少なくとも 1 つ必要です。At least one address or address-range element is required.
address-range from="address" to="address"address-range from="address" to="address" フィルターを適用する IP アドレスの範囲を指定します。Specifies a range of IP address on which to filter. address 要素または address-range 要素は少なくとも 1 つ必要です。At least one address or address-range element is required.

属性Attributes

NameName 説明Description 必須Required 既定値Default
address-range from="address" to="address"address-range from="address" to="address" アクセスを許可または拒否する IP アドレスの範囲。A range of IP addresses to allow or deny access for. address-range 要素を使用する場合は必須です。Required when the address-range element is used. 該当なしN/A
ip-filter action="allow | forbid"ip-filter action="allow | forbid" 指定した IP アドレスおよび IP アドレス範囲に対する呼び出しを許可するかどうかを指定します。Specifies whether calls should be allowed or not for the specified IP addresses and ranges. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound
  • ポリシー スコープ: グローバル、製品、API、操作Policy scopes: global, product, API, operation

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

quota ポリシーは、更新可能な呼び出しまたは有効期間中の呼び出しのボリュームと帯域幅クォータの両方またはそのどちらかをサブスクリプションに基づいて適用します。The quota policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per subscription basis.

重要

このポリシーは、ポリシー ドキュメントごとに 1 回のみ使用できます。This policy can be used only once per policy document.

このポリシー内のポリシー属性では、ポリシー式は使用できません。Policy expressions cannot be used in any of the policy attributes for this policy.

ポリシー ステートメントPolicy statement

<quota calls="number" bandwidth="kilobytes" 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" />  
    </api>  
</quota>  

Example

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

要素Elements

NameName 説明Description 必須Required
quotaquota ルート要素。Root element. [はい]Yes
apiapi 製品内の API に対して呼び出しクォータをかけるには、これらの要素を 1 つまたは複数追加します。Add one or more of these elements to impose call quota on APIs within the product. 製品と API の呼び出しクォータは別々に適用されます。Product and API call quotas are applied independently. API は name または id のいずれかによって参照できます。API can be referenced either via name or id. 両方の属性が提供された場合、id が使用されて name は無視されます。If both attributes are provided, id will be used and name will be ignored. いいえ No
operationoperation API 内の操作に対して呼び出しクォータをかけるには、これらの要素を 1 つまたは複数追加します。Add one or more of these elements to impose call quota on operations within an API. 製品、API、および操作の呼び出しクォータは別々に適用されます。Product, API, and operation call quotas are applied independently. 操作は name または id のいずれかによって参照できます。Operation can be referenced either via name or id. 両方の属性が提供された場合、id が使用されて name は無視されます。If both attributes are provided, id will be used and name will be ignored. いいえ No

属性Attributes

NameName 説明Description 必須Required 既定値Default
namename クォータを適用する API または操作の名前。The name of the API or operation for which the quota applies. [はい]Yes 該当なしN/A
bandwidthbandwidth renewal-period で指定した期間中に許可する最大合計キロバイト数。The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. callsbandwidth のいずれかまたは両方と同時に指定する必要があります。Either calls, bandwidth, or both together must be specified. 該当なしN/A
callscalls renewal-period で指定した期間中に許容する最大呼び出し総数。The maximum total number of calls allowed during the time interval specified in the renewal-period. callsbandwidth のいずれかまたは両方と同時に指定する必要があります。Either calls, bandwidth, or both together must be specified. 該当なしN/A
renewal-periodrenewal-period クォータのリセット間隔 (秒単位)。The time period in seconds after which the quota resets. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound
  • ポリシー スコープ: 製品Policy scopes: product

使用量のクォータをキー別に設定するSet usage quota by key

重要

この機能は、API Management の従量課金レベルでは使用できません。This feature is unavailable in the Consumption tier of API Management.

quota-by-key ポリシーは、更新可能な呼び出しまたは有効期間中の呼び出しのボリュームと帯域幅クォータの両方またはそのどちらかをキーに基づいて適用します。The quota-by-key policy enforces a renewable or lifetime call volume and/or bandwidth quota, on a per key basis. キーには任意の文字列値を設定でき、通常はポリシー式を使用して指定します。The key can have an arbitrary string value and is typically provided using a policy expression. 必要に応じて増分条件を追加し、クォータに対してカウントする要求を指定することもできます。Optional increment condition can be added to specify which requests should be counted towards the quota. 複数のポリシーによって同じキー値が増分される場合は、要求ごとに 1 回だけ増分されます。If multiple policies would increment the same key value, it is incremented only once per request. この呼び出し制限に達すると、呼び出し元は 403 Forbidden 応答状態コードを受信します。When the call limit is reached, the caller receives a 403 Forbidden response status code.

このポリシーの詳細と例については、「Azure API Management を使用した高度な要求スロットル」を参照してください。For more information and examples of this policy, see Advanced request throttling with Azure API Management.

このポリシー内のポリシー属性では、ポリシー式は使用できません。Policy expressions cannot be used in any of the policy attributes for this policy.

ポリシー ステートメントPolicy statement

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

Example

次のサンプルでは、クォータのキーに呼び出し元 IP を設定しています。In the following example, the quota is keyed by the caller IP address.

<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>  

要素Elements

NameName 説明Description 必須Required
quotaquota ルート要素。Root element. [はい]Yes

属性Attributes

NameName 説明Description 必須Required 既定値Default
bandwidthbandwidth renewal-period で指定した期間中に許可する最大合計キロバイト数。The maximum total number of kilobytes allowed during the time interval specified in the renewal-period. callsbandwidth のいずれかまたは両方と同時に指定する必要があります。Either calls, bandwidth, or both together must be specified. 該当なしN/A
callscalls renewal-period で指定した期間中に許容する最大呼び出し総数。The maximum total number of calls allowed during the time interval specified in the renewal-period. callsbandwidth のいずれかまたは両方と同時に指定する必要があります。Either calls, bandwidth, or both together must be specified. 該当なしN/A
counter-keycounter-key クォータ ポリシーに使用するキー。The key to use for the quota policy. [はい]Yes 該当なしN/A
increment-conditionincrement-condition クォータに対して要求の件数をカウントするかどうかを指定するブール式 (true)The boolean expression specifying if the request should be counted towards the quota (true) いいえ No 該当なしN/A
renewal-periodrenewal-period クォータのリセット間隔 (秒単位)。The time period in seconds after which the quota resets. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound
  • ポリシー スコープ: グローバル、製品、API、操作Policy scopes: global, product, API, operation

JWT を検証するValidate JWT

validate-jwt ポリシーは、指定した HTTP ヘッダーまたは指定したクエリ パラメーターのどちらかから抽出した JWT が存在し、有効であることを必須にします。The validate-jwt policy enforces existence and validity of a JWT extracted from either a specified HTTP Header or a specified query parameter.

重要

validate-jwt ポリシーは、require-expiration-time 属性を指定し false に設定した場合を除いて、exp 登録クレームが JWT トークンに含まれていることを必須にします。The validate-jwt policy requires that the exp registered claim is included in the JWT token, unless require-expiration-time attribute is specified and set to false.
validate-jwt ポリシーでは HS256 署名アルゴリズムと RS256 署名アルゴリズムがサポートされています。The validate-jwt policy supports HS256 and RS256 signing algorithms. HS256 の場合、キーをポリシー内に base64 エンコード形式でインライン指定する必要があります。For HS256 the key must be provided inline within the policy in the base64 encoded form. RS256 の場合、キーは Open ID 構成エンドポイントを介して指定する必要があります。For RS256 the key has to be provide via an Open ID configuration endpoint.

ポリシー ステートメントPolicy statement

<validate-jwt   
    header-name="name of http header containing the token (use query-parameter-name attribute if the token is passed in the URL)"   
    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">  
  <issuer-signing-keys>  
    <key>base64 encoded signing key</key>  
    <!-- if there are multiple keys, then add additional key elements -->  
  </issuer-signing-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>  
  <openid-config url="full URL of the configuration endpoint, e.g. https://login.constoso.com/openid-configuration" />  
  <zumo-master-key id="key identifier">key value</zumo-master-key>  
</validate-jwt>  

Examples

Azure Mobile Services のトークン検証Azure Mobile Services token validation

<validate-jwt header-name="x-zumo-auth" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Supplied access token is invalid.">  
    <issuers>  
        <issuer>urn:microsoft:windows-azure:zumo</issuer>  
    </issuers>  
    <audiences>  
        <audience>Facebook</audience>  
    </audiences>  
    <issuer-signing-keys>  
        <zumo-master-key id="0">insert key here</zumo-master-key>  
    </issuer-signing-keys>  
</validate-jwt>  

Azure Active Directory のトークン検証Azure Active Directory token validation

<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/.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 のトークン検証Azure Active Directory B2C token validation

<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>  

トークン クレームに基づいて操作へのアクセスを承認するAuthorize access to operations based on token claims

次の例では、JWT を検証するポリシーを使用して、トークン クレームに基づいて操作へのアクセスを事前に承認する方法を示します。This example shows how to use the Validate JWT policy to pre-authorize access to operations based on token claims. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky」(クラウド カバー エピソード 177: Vlad Vinogradsky によるその他の API Management 機能の紹介) を 13:50 まで早送りしてご覧ください。For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 13:50. 15:00 まで早送りし、ポリシー エディターで構成されるポリシーをご覧いただいた後、開発者ポータルから操作を呼び出す方法について、必要な認証トークンを使用した場合と使用しない場合の両方のデモを 18:50 からご覧ください。Fast forward to 15:00 to see the policies configured in the policy editor and then to 18:50 for a demonstration of calling an operation from the developer portal both with and without the required authorization token.

<!-- Copy the following snippet into the inbound section at the api (or higher) level to pre-authorize access to operations based on token claims -->  
<set-variable name="signingKey" value="insert signing key here" />  
<choose>  
  <when condition="@(context.Request.Method.Equals("patch",StringComparison.OrdinalIgnoreCase))">  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
      <required-claims>  
        <claim name="edit">  
          <value>true</value>  
        </claim>  
      </required-claims>  
    </validate-jwt>  
  </when>  
  <when condition="@(new [] {"post", "put"}.Contains(context.Request.Method,StringComparer.OrdinalIgnoreCase))">  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
      <required-claims>  
        <claim name="create">  
          <value>true</value>  
        </claim>  
      </required-claims>  
    </validate-jwt>  
  </when>  
  <otherwise>  
    <validate-jwt header-name="Authorization">  
      <issuer-signing-keys>  
        <key>@((string)context.Variables["signingKey"])</key>  
      </issuer-signing-keys>  
    </validate-jwt>  
  </otherwise>  
</choose>  

要素Elements

要素Element 説明Description 必須Required
validate-jwtvalidate-jwt ルート要素。Root element. [はい]Yes
audiencesaudiences トークン上に存在する可能性がある、許容される対象ユーザー クレームの一覧を記載します。Contains a list of acceptable audience claims that can be present on the token. 対象ユーザー値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。If multiple audience values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. 少なくとも 1 つの対象ユーザーを指定する必要があります。At least one audience must be specified. いいえ No
issuer-signing-keysissuer-signing-keys 署名付きトークンの検証に使用する base64 でエンコードされたセキュリティ キーの一覧。A list of Base64-encoded security keys used to validate signed tokens. セキュリティ キーが複数存在する場合は、すべてのキーが消費される (この場合検証は失敗します) かいずれかのキーの検証が成功する (トークンのロールオーバーに使用されます) まで、各キーについて検証が行われます。If multiple security keys are present, then each key is tried until either all are exhausted (in which case validation fails) or until one succeeds (useful for token rollover). キー要素には、kid クレームとの照合に使用される id 属性を必要に応じて設定できます。Key elements have an optional id attribute used to match against kid claim. いいえ No
issuersissuers トークンを発行した、許容されるプリンシパルの一覧。A list of acceptable principals that issued the token. 発行者の値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。If multiple issuer values are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. いいえ No
openid-configopenid-config 署名キーと発行者を取得可能な準拠している Open ID 構成エンドポイントを指定するために使用する要素。The element used for specifying a compliant Open ID configuration endpoint from which signing keys and issuer can be obtained. いいえ No
required-claimsrequired-claims トークン上に存在すると予測される、有効とみなすクレームの一覧を記載します。Contains a list of claims expected to be present on the token for it to be considered valid. match 属性を all に設定した場合、検証が成功するにはポリシー内のクレーム値がすべてトークン内に存在する必要があります。When the match attribute is set to all every claim value in the policy must be present in the token for validation to succeed. match 属性を any に設定した場合、検証が成功するには少なくとも 1 つのクレームがトークン内に存在する必要があります。When the match attribute is set to any at least one claim must be present in the token for validation to succeed. いいえ No
zumo-master-keyzumo-master-key Azure Mobile Services によって発行されたトークンのマスター キーMaster key for tokens issued by Azure Mobile Services いいえ No

属性Attributes

NameName 説明Description 必須Required 既定値Default
clock-skewclock-skew 期間。Timespan. トークンの発行者と API Management インスタンスのシステム クロックの間に予想される最大時間差を指定するために使用します。Use to specify maximum expected time difference between the system clocks of the token issuer and the API Management instance. いいえ No 0 秒0 seconds
failed-validation-error-messagefailed-validation-error-message JWT が検証で不合格となった場合に HTTP 応答本文で返すエラー メッセージ。Error message to return in the HTTP response body if the JWT does not pass validation. このメッセージ内では、特殊文字を適切にエスケープする必要があります。This message must have any special characters properly escaped. いいえ No 既定のエラー メッセージは検証の問題によって異なります ("JWT not present" (JWT が存在しません) など)。Default error message depends on validation issue, for example "JWT not present."
failed-validation-httpcodefailed-validation-httpcode JWT が検証で不合格となった場合に返す HTTP 状態コード。HTTP Status code to return if the JWT doesn't pass validation. いいえ No 401401
header-nameheader-name トークンを保持する HTTP ヘッダーの名前。The name of the HTTP header holding the token. header-namequery-parameter-name はどちらかを指定する必要がありますが、両方を指定する必要はありません。Either header-name or query-parameter-name must be specified; but not both. 該当なしN/A
idid key 要素の id 属性を使用すると、署名検証用の適切なキーを確認するためにトークン内の kid クレーム (存在する場合) と照合する文字列を指定できます。The id attribute on the key element allows you to specify the string that will be matched against kid claim in the token (if present) to find out the appropriate key to use for signature validation. いいえ No 該当なしN/A
matchmatch claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。The match attribute on the claim element specifies whether every claim value in the policy must be present in the token for validation to succeed. 次のいずれかの値になります。Possible values are:

- all - 検証が成功するには、ポリシー内のクレーム値がすべてトークン内に存在する必要があります。- all - every claim value in the policy must be present in the token for validation to succeed.

- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。- any - at least one claim value must be present in the token for validation to succeed.
いいえ No すべてall
query-paremeter-namequery-paremeter-name トークンを保持するクエリ パラメーターの名前。The name of the query parameter holding the token. header-namequery-paremeter-name はどちらかを指定する必要がありますが、両方を指定する必要はありません。Either header-name or query-paremeter-name must be specified; but not both. 該当なしN/A
require-expiration-timerequire-expiration-time ブール値。Boolean. トークン内に有効期限クレームが存在する必要があるかどうかを指定します。Specifies whether an expiration claim is required in the token. いいえ No truetrue
require-schemerequire-scheme トークンの名前。例: "Bearer"。The name of the token scheme, e.g. "Bearer". この属性が設定されている場合、ポリシーは指定したスキームが承認ヘッダーの値に存在していることを確認します。When this attribute is set, the policy will ensure that specified scheme is present in the Authorization header value. いいえ No 該当なしN/A
require-signed-tokensrequire-signed-tokens ブール値。Boolean. トークンに署名が必要かどうかを指定します。Specifies whether a token is required to be signed. いいえ No truetrue
separatorseparator 文字列 をオンにします。String. 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。Specifies a separator (e.g. ",") to be used for extracting a set of values from a multi-valued claim. いいえ No 該当なしN/A
urlurl Open ID 構成メタデータを取得可能な Open ID 構成エンドポイントの URL。Open ID configuration endpoint URL from where Open ID configuration metadata can be obtained. 応答は、URL で定義されている仕様に従っている必要があります:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadataThe response should be according to specs as defined at URL:https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. Azure Active Directory の場合は、https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration という URL をご使用のディレクトリ テナント名 (contoso.onmicrosoft.com など) に置き換えて使用します。For Azure Active Directory use the following URL: https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration substituting your directory tenant name, e.g. contoso.onmicrosoft.com. [はい]Yes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound
  • ポリシー スコープ: グローバル、製品、API、操作Policy scopes: global, product, API, operation

次の手順Next steps

ポリシーを使用する方法の詳細については、次のトピックを参照してください。For more information working with policies, see: