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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<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 (기본값에 관한 중요한 정보는 위 참고 사항을 확인하세요.)
Presence	선택사항
유형	문자열
유효한 값	Apigee 흐름 변수 이름

흐름 변수

성공하면 JWT 인증 및 JWT 디코딩 정책이 다음 패턴에 따라 컨텍스트 변수를 설정합니다.

jwt.{policy_name}.{variable_name}

예를 들어 정책 이름이 jwt-parse-token인 경우 정책은 JWT에 지정된 주체를 jwt.jwt-parse-token.decoded.claim.sub라는 컨텍스트 변수에 저장합니다. (이전 버전과의 호환성을 위해 jwt.jwt-parse-token.claim.subject에서도 사용할 수 있습니다.)

변수 이름	설명
claim.audience	JWT 잠재고객 클레임입니다. 이 값은 문자열이거나 문자열 배열일 수 있습니다.
claim.expiry	만료일/시간으로 에포크 이후 밀리초 단위로 표시됩니다.
claim.issuedat	토큰이 발행된 날짜로 에포크 이후 밀리초 단위로 표시됩니다.
claim.issuer	JWT 발급자 클레임입니다.
claim.notbefore	JWT에 nbf 클레임이 포함된 경우 에포크 이후 밀리초로 표시되는 값이 이 변수에 포함됩니다.
claim.subject	JWT 주체 클레임입니다.
claim.name	페이로드에 있는 명명된 클레임(표준 또는 추가) 값입니다. 이 중 하나가 페이로드의 모든 클레임에 설정됩니다.
decoded.claim.name	페이로드에 있는 명명된 클레임(표준 또는 추가)의 JSON 파싱 가능 값입니다. 페이로드의 모든 클레임에 하나의 변수가 설정됩니다. 예를 들어 decoded.claim.iat를 사용하여 JWT의 발급 시간을 에포크 이후의 초 단위로 검색할 수 있습니다. claim.name 흐름 변수를 사용할 수도 있지만 클레임에 액세스하는 데 권장되는 변수는 이 값입니다.
decoded.header.name	페이로드에 있는 헤더의 JSON 파싱 가능 값입니다. 페이로드의 모든 헤더에 하나의 변수가 설정됩니다. header.name 흐름 변수를 사용할 수도 있지만 헤더에 액세스하는 데 권장되는 변수는 이 값입니다.
expiry_formatted	만료일/시간으로 인간이 읽을 수 있는 문자열 형식입니다. 예: 2017-09-28T21:30:45.000+0000
header.algorithm	JWT에서 사용되는 서명 알고리즘입니다. 예를 들어 RS256, HS384 등입니다. 자세한 내용은 (알고리즘) 헤더 매개변수를 참조하세요.
header.kid	JWT가 생성될 때 추가된 경우, 키 ID입니다. JWT를 확인하려면 JWT 정책 개요의 'JSON 웹 키 세트(JWKS) 사용'을 참조하세요. 자세한 내용은 (키 ID)헤더 매개변수를 참조하세요.
header.type	JWT로 설정됩니다.
header.name	이름이 지정된 헤더 값(표준 또는 추가)입니다. 이 중 하나가 JWT의 헤더 부분에 있는 모든 추가 헤더에 설정됩니다.
header-json	JSON 형식의 헤더입니다.
is_expired	true 또는 false
payload-claim-names	JWT에서 지원되는 클레임 배열입니다.
payload-json	JSON 형식의 페이로드입니다.
seconds_remaining	토큰이 만료되기까지 걸리는 시간(초)입니다. 토큰이 만료된 경우 이 숫자는 음수입니다.
time_remaining_formatted	토큰이 만료되기까지 남은 시간으로 인간이 읽을 수 있는 문자열 형식입니다. 예: 00:59:59.926
valid	VerifyJWT의 경우 이 변수는 서명이 인증되고 현재 시간이 토큰 만료 전 및 토큰 notBefore 값(존재하는 경우) 이후일 때 true가 됩니다. 그렇지 않으면 false입니다. DecodeJWT의 경우 이 변수가 설정되지 않습니다.

오류 참조

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

런타임 오류

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

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

배포 오류

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

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

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "InvalidToken"
JWT.failed	All JWT policies set the same variable in the case of a failure.	JWT.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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