JWT を検証する

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

この validate-jwt ポリシーは、ID プロバイダーから提供された JSON Web Token (JWT) の存在と有効性を必須にします。 JWT は、指定した HTTP ヘッダーから、または指定したクエリ パラメーターから、あるいは特定の値と照合することで抽出できます。

ポリシー ステートメント

<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 id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">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 value, then add additional value elements -->
    </claim>
    <!-- if there are multiple possible allowed claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

属性

要素

key の属性

claim の属性

使用法

• ポリシー セクション: inbound
• ポリシー スコープ: グローバル、ワークスペース、製品、API、操作
• ゲートウェイ: クラシック、v2、従量課金、セルフホステッド、ワークスペース

使用上の注意

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

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>00001111-aaaa-2222-bbbb-3333cccc4444</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>11112222-bbbb-3333-cccc-4444dddd5555</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

解読キーを使用したトークンの検証

この例では、解読キーを使用して解読されたトークンを、validate-jwt ポリシーを使用して検証する方法を示します。 キーは、公開キーを含む、アップロードされた証明書 (PFX 形式) の ID を使用して指定します。

<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>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</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>

関連ポリシー

• 認証と権限承認

関連するコンテンツ

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

• チュートリアル:API を変換および保護する
• ポリシー ステートメントとその設定の一覧に関するポリシー リファレンス
• ポリシー式
• ポリシーの設定または編集
• ポリシー構成を再利用する
• ポリシー スニペットのリポジトリ
• ポリシープレイグラウンドリポジトリ
• Azure API Management ポリシー ツールキット
• ポリシーの作成、説明、トラブルシューティングを行う Copilot のサポートを受ける