현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보
내용
JWT에서 서명을 확인하지 않고 JWT를 디코딩합니다. 이것은 VerifyJWT 정책과 함께 사용될 때, JWT 서명을 확인하기 전 JWT 내의 클레임 값을 알아야 할 때 가장 유용합니다.
JWT 디코딩 정책은 JWT에 서명할 때 사용된 알고리즘과 관계없이 작동합니다. 자세한 소개는 JWS 및 JWT 정책 개요를 참조하세요.
동영상
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._\-$ %로 제한됩니다. 하지만 에지 관리 UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등의 추가 제한사항을 적용합니다.
선택적으로 |
N/A | 필수 |
| continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.
정책이 실패해도 흐름 실행이 계속되도록 하려면 |
false | 선택사항 |
| 사용 설정됨 |
정책을 시행하려면 true로 설정합니다.
|
true | 선택사항 |
| async | 이 속성은 지원이 중단되었습니다. | false | 지원 중단됨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
이름 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기에서 다른 자연어 이름으로 정책에 라벨을 지정합니다.
| 기본 | 이 요소를 생략하면 정책 이름 속성 값이 사용됩니다. |
| Presence | 선택사항 |
| 유형 | 문자열 |
<Source>
<Source>jwt-variable</Source>
존재하는 경우 정책에서 디코딩할 JWT를 찾고자 하는 흐름 변수를 지정합니다.
| 기본값 | request.header.authorization (기본값에 관한 중요한 정보는 위 참고 사항을 확인하세요.) |
| Presence | 선택사항 |
| 유형 | 문자열 |
| 유효한 값 | 에지 흐름 변수 이름 |
흐름 변수
성공하면 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의 경우 이 변수는 서명이 인증될 때 true가 되고, 현재 시간은 토큰 만료 전과 토큰 notBefore 값 이후(있는 경우)입니다. 그 이외의 경우는 false입니다.
DecodeJWT의 경우 이 변수가 설정되지 않습니다. |
오류 참조
이 섹션에서는 반환되는 오류 코드, 오류 메시지, 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
| 오류 코드 | HTTP 상태 | 원인 | 수정 |
|---|---|---|---|
steps.jwt.FailedToDecode |
401 | 정책이 JWT를 디코딩할 수 없는 경우에 발생합니다. JWT의 형식이 잘못되었거나 유효하지 않거나 디코딩할 수 없습니다. | build |
steps.jwt.FailedToResolveVariable |
401 | 정책의 <Source> 요소에 지정된 흐름 변수가 존재하지 않는 경우 발생합니다. |
|
steps.jwt.InvalidToken |
401 | 정책의 <Source> 요소에 지정된 흐름 변수가 범위를 벗어나거나 해결할 수 없는 경우 발생합니다. |
build |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
| 오류 이름 | 원인 | 해결 |
|---|---|---|
InvalidEmptyElement |
디코딩할 JWT가 포함된 흐름 변수가 정책의 <Source> 요소에 지정되지 않은 경우 발생합니다.
|
build |
오류 변수
이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.
| 변수 | 각 항목의 의미는 다음과 같습니다. | 예 |
|---|---|---|
fault.name="fault_name" |
fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. | fault.name Matches "TokenExpired" |
JWT.failed |
모든 JWT 정책은 오류 발생 시 동일한 변수를 설정합니다. | JWT.failed = true |
오류 응답 예시
오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.
오류 규칙 예시
<FaultRules>
<FaultRule name="JWT Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWT.failed=true</Condition>
</FaultRule>
</FaultRules>