驗證 JWT

適用於：所有 APIM 層

validate-jwt 原則會強制必須存在擷取自指定 HTTP 標頭、擷取自指定查詢的參數，或對應的指定值，指定查詢參數的受支援 JSON Web 權杖 (JWT)，且為有效。

原則陳述式

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

屬性

元素

金鑰屬性

宣告屬性

使用方式

• 原則區段︰inbound
• 原則範圍︰全域、工作區、產品、API、作業
• 閘道： 傳統、v2、使用量、自我裝載、工作區

使用注意事項

• validate-jwt 原則會要求 exp 註冊的宣告包含在 JWT 權杖中 (除非已指定 require-expiration-time 屬性並設定為 false)。
• 此原則支援對稱和非對稱簽署演算法：
  • 對稱 - 支援下列加密演算法：A128CBC-HS256、A192CBC-HS384、A256CBC-HS512。
    • 如果在原則中使用，則必須以 Base64 編碼形式內嵌在原則內提供金鑰。
  • 非對稱 - 支援下列加密演算法：PS256、RS256、RS512、ES256。
    • 如果在原則中使用，則金鑰可透過 OpenID 設定端點提供，或對於包含公開金鑰或公開金鑰模數指數組的上傳憑證提供識別碼 (以 PFX 格式)。
• 若要搭配自主裝載閘道使用一或多個 OpenID 設定端點來設定原則，則雲端閘道也必須可連線 OpenID 設定端點 URL。
• 您可以針對不同的用途，在不同的範圍中使用存取限制原則。 例如，您可以藉由在 API 層級套用 validate-jwt 原則，以 Microsoft Entra 驗證保護整個 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 原則來根據權杖宣告值授與作業的存取權。

<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 管理 原則工具組
• 使用 Microsoft Azure Copilot 撰寫原則