DecodeJWT 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

대상

JWT에서 서명을 확인하지 않고 JWT를 디코딩합니다. 이것은 VerifyJWT 정책과 함께 사용될 때, JWT 서명을 확인하기 전 JWT 내의 클레임 값을 알아야 할 때 가장 유용합니다.

JWT 디코딩 정책은 JWT에 서명할 때 사용된 알고리즘과 관계없이 작동합니다. 자세한 소개는 JWS 및 JWT 정책 개요를 참조하세요.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

동영상

참고: 다음 동영상에서는 Apigee UI의 기본 프록시 편집기를 보여줍니다. Apigee는 동영상에 표시된 기본 버전과 설계가 다른 새 버전의 프록시 편집기를 도입합니다.

JWT를 디코딩하는 방법을 알아보려면 짧은 동영상을 시청하세요.

샘플: JWT 디코딩

아래에 표시된 정책은 흐름 변수 var.jwt에 있는 JWT를 디코딩합니다. 이 변수는 존재해야 하며 실행 가능한(디코딩 가능한) JWT를 포함해야 합니다. 이 정책은 모든 흐름 변수에서 JWT를 가져올 수 있습니다.

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

정책은 API 프록시의 후속 정책 또는 조건이 해당 값을 검사할 수 있도록 출력물을 컨텍스트 변수에 씁니다. 이 정책에 의해 설정된 변수 목록은 흐름 변수를 참조하세요.

JWT 디코딩용 요소 참조

정책 참조는 JWT 디코딩 정책의 요소 및 속성을 설명합니다.

최상위 요소에 적용되는 속성

<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">

다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.

속성	설명	기본값	정보
이름	정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ %로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다. 선택적으로 <displayname></displayname> 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다.	거짓	선택사항
사용 설정됨	정책을 시행하려면 true로 설정합니다. false로 설정하여 정책을 '사용 중지'합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	참	선택사항
async	이 속성은 지원이 중단되었습니다.	거짓	지원 중단됨

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

이름 속성 외에도 이 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

기본값	이 요소를 생략하면 정책 이름 속성 값이 사용됩니다.
정보	선택사항
유형	문자열

<Source>

<Source>jwt-variable</Source>

존재하는 경우 정책에서 디코딩할 JWT를 찾고자 하는 흐름 변수를 지정합니다.

참고: 기본적으로 JWT는 변수 request.header.authorization에서 가져옵니다. 이 경우 Apigee는 요청 승인 헤더에서 JWT를 찾습니다. JWT를 승인 헤더에 전달하면 소스 요소를 정책에 포함할 필요가 없지만 인증 헤더에 Bearer를 포함해야 합니다. 예를 들어 다음과 같이 승인 헤더에 JWT를 전달합니다.

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

양식 또는 쿼리 매개변수 변수나 기타 변수에서 JWT를 검색하도록 정책을 구성할 수 있습니다. 변수가 존재하지 않거나 정책이 JWT를 찾지 못하면 오류가 반환됩니다.

기본값	request.header.authorization (기본값에 관한 중요한 정보는 위 참고 사항을 확인하세요.)
정보	선택사항
유형	문자열
유효한 값	Apigee 흐름 변수 이름

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name	Description
claim.audience	The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry	The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat	The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer	The JWT issuer claim.
claim.notbefore	If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject	The JWT subject claim.
claim.name	The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name	The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name	The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted	The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm	The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid	The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type	Will be set to JWT.
header.name	The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json	The header in JSON format.
is_expired	true or false
payload-claim-names	An array of claims supported by the JWT.
payload-json	The payload in JSON format.
seconds_remaining	The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted	The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid	In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false. In the case of DecodeJWT, this variable is not set.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인	수정
steps.jwt.FailedToDecode	401	정책이 JWT를 디코딩할 수 없는 경우에 발생합니다. JWT의 형식이 잘못되었거나 유효하지 않거나 디코딩할 수 없습니다.
steps.jwt.FailedToResolveVariable	401	정책의 <Source> 요소에 지정된 흐름 변수가 존재하지 않는 경우 발생합니다.
steps.jwt.InvalidToken	401	정책의 <Source> 요소에 지정된 흐름 변수가 범위를 벗어나거나 해결할 수 없는 경우 발생합니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름	원인	수정
InvalidEmptyElement	디코딩할 JWT가 포함된 흐름 변수가 정책의 <Source> 요소에 지정되지 않은 경우 발생합니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수	장소	예
fault.name="fault_name"	fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "InvalidToken"
JWT.failed	모든 JWT 정책은 오류 발생 시 동일한 변수를 설정합니다.	JWT.failed = true

오류 응답 예시

오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

오류 규칙 예시

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>