이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
대상
JWS의 서명을 확인하지 않고 JWS 헤더를 디코딩하여 각 헤더를 흐름 변수에 씁니다. 이 정책은 JWS의 서명을 확인하기 전에 JWS 내의 헤더 값을 알아야 하는 경우 VerifyJWS 정책과 함께 사용할 때 가장 유용합니다.
JWS는 연결된 페이로드를 포함하여 다음과 같은 형식입니다.
header.payload.signature
또는 JWS에서 페이로드를 생략하고(분리된 페이로드) 다음과같은 형식입니다.
header..signature
DecodeJWS 정책은 JWS의 헤더 부분만 디코딩하므로 두 형식 모두에서 작동합니다. 또한 DecodeJWS 정책은 JWS 서명에 사용된 알고리즘과 관계없이 작동합니다.
JWS 형식에 대한 자세한 소개와 개요를 보려면 JWS 및 JWT 정책 개요를 참조하세요.
이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.
동영상
JWT를 디코딩하는 방법을 알아보려면 짧은 동영상을 시청하세요. 이 동영상은 JWT에 해당하지만 대부분의 개념은 JWS와 동일합니다.
샘플: JWS 디코딩
아래에 표시된 정책은 흐름 변수 var.JWS에 있는 JWS를 디코딩합니다. 이 변수는 존재해야 하며 실행 가능한(취소 가능한) JWS를 포함해야 합니다. 이 정책은 모든 흐름 변수에서 JWS를 가져올 수 있습니다.
<DecodeJWS name="JWS-Decode-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Source>var.JWS</Source> </DecodeJWS>
정책은 JWS의 헤더 부분에 있는 각 헤더에 대해 다음과 같은 흐름 변수를 설정합니다.
jws.policy-name.header.header-name
JWS에 연결된 페이로드가 있으면 jws.policy-name.header.payload 흐름 변수를 페이로드로 설정합니다. 분리된 페이로드의 경우 payload가 비어 있습니다.
이 정책에서 설정한 전체 변수 목록은 흐름 변수를 참조하세요.
Decode JWS에 대한 요소 참조
정책 참조는 Decode JWS 정책의 요소 및 속성을 설명합니다.
최상위 요소에 적용되는 속성
<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">
다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.
| 속성 | 설명 | 기본 | Presence |
|---|---|---|---|
| 이름 |
정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ %로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.
선택적으로 |
해당 사항 없음 | 필수 |
| continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.
정책이 실패해도 흐름 실행이 계속되도록 하려면 |
false | 선택사항 |
| enabled | 정책을 시행하려면 true로 설정합니다.
|
true | 선택사항 |
| async | 이 속성은 지원이 중단되었습니다. | false | 지원 중단됨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
이름 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기에서 다른 자연어 이름으로 정책에 라벨을 지정합니다.
| 기본 | 이 요소를 생략하면 정책 이름 속성 값이 사용됩니다. |
| Presence | 선택사항 |
| 유형 | 문자열 |
<Source>
<Source>JWS-variable</Source>
존재하는 경우 정책에서 디코딩할 JWS를 찾고자 하는 흐름 변수를 지정합니다.
| 기본값 | request.header.authorization (기본값에 관한 중요한 정보는 위 참고 사항을 확인하세요.) |
| Presence | 선택사항 |
| 유형 | 문자열 |
| 유효한 값 | Apigee 흐름 변수 이름 |
흐름 변수
성공하면 JWS 인증 및 JWS 디코딩 정책이 다음 패턴에 따라 컨텍스트 변수를 설정합니다.
jws.{policy_name}.{variable_name}
예를 들어 정책 이름이 verify-jws이면 정책은 JWS에 지정된 알고리즘을 이 jws.verify-jws.header.algorithm 컨텍스트 변수에 저장합니다.
| 변수 이름 | 설명 |
|---|---|
decoded.header.name |
페이로드에 있는 헤더의 JSON 파싱 가능 값입니다. 페이로드의 모든 헤더에 하나의 변수가 설정됩니다. header.name 흐름 변수를 사용할 수도 있지만 헤더에 액세스하는 데 권장되는 변수는 이 값입니다. |
header.algorithm |
JWS에서 사용되는 서명 알고리즘입니다. 예를 들어 RS256, HS384 등입니다. 자세한 내용은 (알고리즘) 헤더 매개변수를 참조하세요. |
header.kid |
JWS가 생성될 때 추가된 경우, 키 ID입니다. JWS를 확인하려면 JWT 및 JWS 정책 개요의 'JSON 웹 키 세트(JWKS) 사용'을 참조하세요. 자세한 내용은 (키 ID)헤더 매개변수를 참조하세요. |
header.type |
헤더 유형 값입니다. 자세한 내용은 (유형) 헤더 매개변수를 참조하세요. |
header.name |
이름이 지정된 헤더 값(표준 또는 추가)입니다. 이 중 하나가 JWS의 헤더 부분에 있는 모든 추가 헤더에 설정됩니다. |
header-json |
JSON 형식의 헤더입니다. |
payload |
JWS에 연결된 페이로드가 있는 경우의 JWS 페이로드입니다. 분리된 페이로드의 경우 이 변수는 비어 있습니다. |
valid |
VerifyJWS의 경우 서명이 인증되고 현재 시간이 토큰 만료 전 및 토큰 notBefore 값 후인 경우 이 변수는 true가 됩니다. 그 이외의 경우는 false입니다.
DecodeJWS의 경우 이 변수가 설정되지 않습니다. |
오류 참조
이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
| 오류 코드 | HTTP 상태 | 발생 상황 |
|---|---|---|
steps.jws.FailedToDecode |
401 |
정책에서 JWS를 디코딩할 수 없습니다. JWS가 손상되었을 수 있습니다. |
steps.jws.FailedToResolveVariable |
401 |
정책의 <Source> 요소에 지정된 흐름 변수가 존재하지 않는 경우 발생합니다. |
steps.jws.InvalidClaim |
401 |
소유권 클레임 누락 또는 소유권 클레임 불일치, 헤더 또는 헤더 불일치 누락일 때 발생합니다. |
steps.jws.InvalidJsonFormat |
401 |
JWS 헤더에 잘못된 JSON이 있습니다. |
steps.jws.InvalidJws |
401 |
이 오류는 JWS 서명 확인이 실패하면 발생합니다. |
steps.jws.InvalidPayload |
401 |
JWS 페이로드가 잘못되었습니다. |
steps.jws.InvalidSignature |
401 |
<DetachedContent>가 생략되고 JWS에 분리된 콘텐츠 페이로드가 있습니다. |
steps.jws.MissingPayload |
401 |
JWS 페이로드가 누락되었습니다. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
JWS에서 알고리즘 헤더가 생략되면 발생합니다. |
steps.jws.UnknownException |
401 |
알 수 없는 예외가 발생했습니다. |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
| 오류 이름 | 발생 상황 |
|---|---|
InvalidAlgorithm |
다음 값만 유효: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512 |
|
|
기타 발생 가능한 배포 오류 |
오류 변수
이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.
| 변수 | 장소 | 예 |
|---|---|---|
fault.name="fault_name" |
fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. | fault.name Matches "TokenExpired" |
JWS.failed |
모든 JWS 정책은 오류 발생 시 동일한 변수를 설정합니다. | jws.JWS-Policy.failed = true |
오류 응답 예시
오류 처리에서 오류 응답의 errorcode 부분을 트래핑하는 것이 가장 좋습니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.
오류 규칙 예시
<FaultRules>
<FaultRule name="JWS Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWS.failed=true</Condition>
</FaultRule>
</FaultRules>