JWT 유효성 검사

적용 대상: 모든 API Management 계층

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

참고 항목

Microsoft Entra 서비스에서 제공한 JWT의 유효성을 검사하기 위해 API Management는 validate-azure-ad-token 정책도 제공합니다.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. 이 정책을 구성하는 데 도움이 되도록 포털은 양식 기반의 안내형 편집기를 제공합니다. 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 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>

특성

특성	설명	필수 항목	기본값
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의 개체로 토큰 값을 수신할 컨텍스트 변수의 이름입니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

Elements

요소	설명	필수
openid-config	이러한 요소 중 하나 이상을 추가하여 서명 키와 발급자를 가져올 수 있는 규격 OpenID 구성 엔드포인트 URL을 지정합니다. JWKS(JSON Web Key Set)를 포함한 구성은 1시간마다 엔드포인트에서 풀되고 캐시됩니다. 유효성 검사되는 토큰이 캐시된 구성에서 누락된 유효성 검사 키(kid 클레임 사용)를 참조하거나 검색에 실패하는 경우 API Management는 5분당 최대 한 번 엔드포인트에서 풀합니다. 이 간격은 통지 없이 변경될 수 있습니다. 응답은 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(예 contoso.onmicrosoft.com: )를 {tenant-name}으로 대체합니다.	아니요
issuer-signing-keys	서명된 토큰의 유효성을 검사하는 데 사용되는 key 하위 요소의 Base64 인코딩 보안 키의 목록입니다. 보안 키가 여러 개 있는 경우 각 키는 모든 키가 소진(이 경우 유효성 검사 실패)되거나 한 개 키가 성공할 때까지 시도됩니다(토큰 롤오버에 유용함). 필요에 따라 kid 클레임과 일치하도록 id 특성을 사용하여 키를 지정합니다. 비대칭 키로 서명된 토큰의 유효성을 검사하려면 필요에 따라 API Management에 업로드된 인증서의 식별자로 값이 설정된 certificate-id 특성 또는 Base64url로 인코딩된 형식의 서명 키의 RSA 모듈러스 n 및 지수 e 쌍을 사용하여 공개 키를 지정합니다.	아니요
decryption-keys	토큰의 암호를 해독하는 데 사용되는 key 하위 요소의 Base64 인코딩 키의 목록입니다. 여러 개의 보안 키가 있는 경우 모든 키가 사용되거나(유효성 검사가 실패한 경우) 키가 성공할 때까지 각 키를 시도합니다. 비대칭 키로 암호화된 토큰의 암호를 해독하려면 필요에 따라 값이 API Management에 업로드된 인증서의 식별자로 설정된 certificate-id 특성을 사용하여 공개 키를 지정합니다.	아니요
audiences	audience 하위 요소에 있으며 토큰에 있을 수 있는 허용 가능한 대상 그룹 클레임 목록입니다. 여러 대상 그룹 값이 있는 경우 각 값은 모든 값이 소진(이 경우 유효성 검사 실패)되거나 한 값이 성공할 때까지 시도됩니다. 한 명 이상의 대상 그룹을 지정해야 합니다.	아니요
issuers	issuer 하위 요소에 있으며 토큰을 발행한 허용 가능한 보안 주체 목록입니다. 여러 발급자 값이 있는 경우 각 값은 모든 값이 소진(이 경우 유효성 검사 실패)되거나 한 값이 성공할 때까지 시도됩니다.	아니요
required-claims	claim 하위 요소에 있으며 유효성을 고려할 토큰에 있을 것으로 예상되는 클레임 목록입니다. 여러 클레임이 있는 경우 토큰은 match 특성 값에 따라 클레임 값과 일치해야 합니다.	아니요

키 특성

attribute	설명	필수 항목	기본값
id	(발급자 서명 키만 해당) 문자열. JWT에 있는 kid 클레임과 일치시키는 데 사용되는 식별자입니다.	아니요	해당 없음
certificate-id	비대칭 키로 서명된 토큰을 확인하기 위해 공개 키를 지정하는 데 사용되는 API Management에 업로드된 인증서 엔터티의 식별자입니다.	아니요	해당 없음
n	(발급자 서명 키만 해당) 비대칭 키로 서명된 토큰의 발급자를 확인하는 데 사용되는 공개 키의 모듈러스입니다. 지수 e의 값으로 지정해야 합니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음
e	(발급자 서명 키만 해당) 비대칭 키로 서명된 토큰의 발급자를 확인하는 데 사용되는 공개 키의 지수입니다. 모듈러스 n의 값으로 지정해야 합니다. 정책 식은 허용되지 않습니다.	아니요	해당 없음

클레임 특성

attribute	설명	필수 항목	기본값
match	claim 요소에 있는 match 특성에 따라 유효성 검사 성공을 위해 정책에 있는 모든 클레임 값이 토큰에 표시되어야 하는지가 지정됩니다. 가능한 값은 다음과 같습니다. - all - 유효성 검사 성공을 위해 정책에 있는 모든 클레임 값이 토큰에 표시되어야 합니다. - any - 유효성 검사 성공을 위해 하나 이상의 클레임 값이 토큰에 표시되어야 합니다.	아니요	all
separator	문자열입니다. 다중 값 클레임에서 값 세트를 추출하는 데 사용할 구분 기호(예: “,”)를 지정합니다.	아니요	해당 없음

사용

• 정책 섹션: 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의 Microsoft Copilot을 사용하는 작성자 정책