JWT を検証する

  • [アーティクル]

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

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

Note

Microsoft Entra サービスによって提供された JWT を検証するために、API Management でも validate-azure-ad-token ポリシーが提供されます。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 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, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </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 value, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

属性

属性 説明 必要 Default
header-name トークンを保持する HTTP ヘッダーの名前。 ポリシー式を使用できます。 header-name、query-parameter-name、token-value のいずれかを指定する必要があります。 該当なし
query-parameter-name トークンを保持するクエリ パラメーターの名前。 ポリシー式を使用できます。 header-name、query-parameter-name、token-value のいずれかを指定する必要があります。 該当なし
token-value トークンを含む文字列を返す式。 トークン値の一部として Bearer を返すことはできません。 ポリシー式を使用できます。 header-name、query-parameter-name、token-value のいずれかを指定する必要があります。 該当なし
failed-validation-httpcode JWT が検証で不合格となった場合に返す HTTP 状態コード。 ポリシー式を使用できます。 いいえ 401
failed-validation-error-message JWT が検証で不合格となった場合に HTTP 応答本文で返すエラー メッセージ。 このメッセージ内では、特殊文字を適切にエスケープする必要があります。 ポリシー式を使用できます。 いいえ 既定のエラー メッセージは検証の問題によって異なります ("JWT not present" (JWT が存在しません) など)。
require-expiration-time ブール型。 トークン内に有効期限クレームが存在する必要があるかどうかを指定します。 ポリシー式を使用できます。 いいえ true
require-scheme トークン スキームの名前、(例: 「Bearer」)。 この属性が設定されている場合、ポリシーは指定したスキームが承認ヘッダーの値に存在していることを確認します。 ポリシー式を使用できます。 いいえ 該当なし
require-signed-tokens ブール型。 トークンに署名が必要かどうかを指定します。 ポリシー式を使用できます。 いいえ true
clock-skew 期間。 トークンの発行者と API Management インスタンスのシステム クロックの間に予想される最大時間差を指定するために使用します。 ポリシー式を使用できます。 いいえ 0 秒
output-token-variable-name 文字列 をオンにします。 成功したトークンの検証において、Jwt 型のオブジェクトとしてトークン値を受け取るコンテキスト変数の名前。 ポリシー式は使用できません。 いいえ 該当なし

要素

要素 説明 必須
openid-config これらの要素を 1 つ以上追加して、署名キーと発行者を取得可能な準拠している OpenID 構成エンドポイント URL を指定します。

JSON Web Key Set (JWKS) を含む構成は、エンドポイントから 1 時間ごとにプルされ、キャッシュされます。 検証対象のトークンが、キャッシュされた構成に存在しない検証キー (kid 要求を使用) を参照している場合、または取得に失敗した場合、API Management はエンドポイントから最大 5 分に 1 回プルします。 これらの間隔は予告なしに変更されることがあります。

応答は、URL https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata で定義されている仕様に従っている必要があります。

Microsoft Entra ID には、アプリ登録で構成された次のような 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
- 顧客テナント (プレビュー) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

ディレクトリ テナント名または ID を置き換えます (例: {tenant-name} を contoso.onmicrosoft.com に置き換えます)。		 いいえ
issuer-signing-keys key サブ要素内の、署名付きトークンの検証に使用する base64 でエンコードされたセキュリティ キーの一覧。 セキュリティ キーが複数存在する場合は、すべてのキーが処理される (この場合検証は失敗します) かいずれかのキーの検証が成功する (トークンのロールオーバーに使用されます) まで、各キーについて検証が行われます。

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

必要に応じて、id 属性を使用して kid クレームを照合するキーを指定します。 非対称キーで暗号化トークンを復号化するには、必要に応じて、API Management にアップロードされた証明書の識別子を持つ certificate-id 属性、または Base64url でエンコードされた形式のキーの RSA モジュラス n とエクスポーネント e のペアを使用して公開キーを指定します。		 いいえ
audiences audience サブ要素内の、トークン上に存在する可能性がある、許容される対象ユーザー クレームの一覧。 対象ユーザー値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 少なくとも 1 つの対象ユーザーを指定する必要があります。 いいえ
issuers issuer サブ要素内の、トークンを発行した、許容されるプリンシパルの一覧。 発行者の値が複数存在する場合は、すべての値が消費される (この場合検証は失敗します) かいずれかの値の検証が成功するまで、各値について検証が行われます。 いいえ
required-claims claim サブ要素内の、トークン上に存在すると予測される、有効とみなすクレームの一覧。 複数のクレームが存在する場合、トークンは match 属性の値に従ってクレームの値と一致する必要があります。 いいえ

key の属性

属性 説明 必要 Default
id 文字列 をオンにします。 JWT で提示される kid クレームを照合するために使用される識別子。 いいえ 該当なし
証明書 ID API Management にアップロードされた証明書エンティティの識別子。非対称キーで署名付きトークンを検証する際に、公開キーを指定するために使用されます。 いいえ 該当なし
n 非対称キーで署名付きトークンの発行者を検証するために使用される公開キーのモジュラス。 エクスポーネント e の値を指定する必要があります。 ポリシー式は使用できません。 いいえ 該当なし
e 非対称キーで署名付きトークンの発行者を検証するために使用される公開キーのエクスポーネント。 モジュラス n の値を指定する必要があります。 ポリシー式は使用できません。 いいえ 該当なし

claim の属性

属性 説明 必要 Default
match claim 要素の match 属性では、検証が成功するためにポリシー内のクレーム値がすべてトークン内に存在する必要があるかどうかを指定します。 次のいずれかの値になります。

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

- any - 検証が成功するには、ポリシー内のクレーム値が少なくとも 1 つトークン内に存在する必要があります。		 No all
separator 文字列。 複数値を含む要求から一連の値を抽出するために使用する区切り記号を指定します (例: ",")。 いいえ 該当なし

使用法

使用上の注意

  • validate-jwt ポリシーは、require-expiration-time 属性を指定し false に設定した場合を除いて、exp 登録クレームが JWT トークンに含まれていることを必須にします。
  • このポリシーでは、対称と非対称の両方の署名アルゴリズムがサポートされています。
    • 対称 - A128CBC-HS256、A192CBC-HS384、A256CBC-HS512 の暗号化アルゴリズムがサポートされています。
      • このポリシーで使用する場合、キーをポリシー内に Base64 エンコード形式でインライン指定する必要があります。
    • 非対称 - PS256、RS256、RS512 の暗号化アルゴリズムがサポートされています。
      • このポリシーで使用する場合、キーは OpenID 構成エンドポイント経由で指定するか、公開キーまたは公開キーのモジュラスとエクスポーネントのペアが含まれる (PFX 形式の) アップロードされた証明書の ID を提供することで指定できます。
  • セルフホステッド ゲートウェイで使用する 1 つ以上の OpenID 構成エンドポイントを使用してポリシーを構成するには、OpenID 構成エンドポイント URL もクラウド ゲートウェイから到達可能である必要があります。
  • さまざまな目的に応じて異なるスコープでアクセス制限ポリシーを使用できます。 たとえば、API 全体を Microsoft Entra 認証を使用して保護するには、validate-jwt ポリシーを API レベルに適用します。または、これを API 操作レベルに適用して、claims を使用してきめ細かい制御を行うこともできます。
  • カスタム ヘッダー (header-name) を使用する場合、構成済みの必須スキーム (require-scheme) は無視されます。 必須スキームを使用するには、JWT トークンを Authorization ヘッダーに指定する必要があります。

例

単純なトークン検証

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

Microsoft Entra ID シングル テナント トークンの検証

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

Microsoft Entra ID 顧客テナント トークンの検証

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" 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>

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

次の例では、validate-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>

関連するコンテンツ

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