JWT 유효성 검사

적용 대상: 모든 API Management 계층

validate-jwt 정책은 지정된 HTTP 헤더에서 추출되거나, 지정된 쿼리 매개 변수에서 추출되거나, 특정 값과 일치하는 지원되는 JWT(JSON 웹 토큰)의 존재 및 유효성을 적용합니다.

정책 문

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

특성

Elements

키 특성

클레임 특성

사용

• 정책 섹션: inbound
• 정책 범위: 전역, 작업 영역, 제품, API, 작업
• 게이트웨이: 클래식, v2, 사용량, 자체 호스팅, 작업 영역

사용법 참고 사항

• validate-jwt 정책에서는 require-expiration-time 특정이 지정되지 않고 false로 설정된 경우가 아니면 exp 등록 클레임이 JWT 토큰에 포함되어야 합니다.
• 이 정책은 대칭 및 비대칭 서명 알고리즘을 모두 지원합니다.
  • 대칭 - A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 암호화 알고리즘이 지원됩니다.
    • 정책에서 사용되는 경우 키를 Base64 인코딩 양식으로 정책 내에 인라인으로 제공해야 합니다.
  • 비대칭 - PS256, RS256, RS512, ES256 암호화 알고리즘이 지원됩니다.
    • 정책에서 사용되는 경우 키는 OpenID 구성 끝점을 통해 제공되거나 공개 키 또는 공개 키의 모듈러스-지수 쌍을 포함하는 업로드된 인증서(PFX 형식)의 ID를 제공하여 제공될 수 있습니다.
• 자체 호스팅 게이트웨이와 함께 사용할 하나 이상의 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 Management 정책 도구 키트
• Azure의 Microsoft Copilot을 사용하는 작성자 정책