이 페이지는 Cloud Translation API를 통해 번역되었습니다.

DecodeJWT 정책

<ph type="x-smartling-placeholder"></ph> 현재 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는 영숫자가 아닌 문자를 자동으로 삭제하는 등의 제한 사항이 있습니다. 선택적으로 `<displayname></displayname>` 요소를 사용하여 관리 UI 프록시 편집기에서 다른 자연어 이름으로 정책에 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 `false`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다.	거짓	선택사항
사용 설정됨	정책을 시행하려면 `true`로 설정합니다. `false`로 설정하여 정책을 '사용 중지'합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
비동기	이 속성은 지원이 중단되었습니다.	거짓	지원 중단됨

<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의 경우 이 변수는 서명이 인증되고 현재 시간이 토큰 만료 전 및 토큰 notBefore 값(존재하는 경우) 이후일 때 true가 됩니다. 그렇지 않으면 false입니다. DecodeJWT의 경우 이 변수가 설정되지 않습니다.

오류 참조

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.jwt.FailedToDecode`	401	Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
`steps.jwt.FailedToResolveVariable`	401	Occurs when the flow variable specified in the `<Source>` element of the policy does not exist.
`steps.jwt.InvalidToken`	401	Occurs when the flow variable specified in the `<Source>` element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidEmptyElement`	Occurs when the flow variable containing the JWT to be decoded is not specified in the `<Source>` element of the policy.

오류 변수

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

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

오류 응답 예시

JWT 정책 오류 코드

오류 처리에서 권장사항은 오류 응답의 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>