이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
대상
구성 가능한 클레임 세트를 포함하는 서명된 JWS를 생성합니다. JWS는 클라이언트에 반환되거나, 백엔드 대상으로 전송되거나, 다른 방식으로 사용될 수 있습니다. 자세한 소개는 JWS 및 JWT 정책 개요를 참조하세요.
JWS의 각 부분, 암호화, 서명 방법에 대한 자세한 내용은 RFC7515를 참조하세요.
이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.
동영상
짧은 동영상을 시청하여 서명된 JWT를 생성하는 방법을 알아보세요. 이 동영상은 JWT를 생성하는 데만 해당하지만 대부분의 개념은 JWS와 동일합니다.
샘플
HS256으로 서명된 JWS 생성
이 정책 예시에서는 HS256 알고리즘을 통해 서명된 JWS를 생성합니다. HS256은 서명 및 서명 확인 모두에서 공유 보안 비밀에 의존합니다. 이 JWS는 '연결된' 콘텐츠를 사용합니다. 즉, 인코딩된 헤더, 페이로드, 서명이 점으로 연결되어 최종 JWS가 생성됩니다.
[header].[payload].[signature]
<Payload>
요소를 사용하여 인코딩되지 않은 원시 JWS 페이로드를 지정합니다.
이 예시에서는 변수에 페이로드가 포함됩니다. 이 정책 작업을 트리거할 때 Apigee는 JWS 헤더 및 페이로드를 인코딩한 후 JWS를 디지털로 서명하기 위해 인코딩된 서명을 추가합니다.
다음 정책 구성에서는 my-payload
변수에 포함된 페이로드에서 JWS를 만들고 결과 JWS를 output-variable
변수에 저장합니다.
<GenerateJWS name="JWS-Generate-HS256"> <DisplayName>JWS Generate HS256</DisplayName> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <Payload ref="my-payload"/> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
HS256 서명 JWT 생성
이 예시에서는 HS256 알고리즘을 통해 서명된 콘텐츠가 연결된 JWS도 생성합니다. 이 경우 페이로드는 JSON입니다. typ
헤더를 JWT로 설정하면 서명된 JWT인 서명된 JWS가 생성됩니다.
(참조)
다음 정책 구성에서는 json-content
변수에 포함된 페이로드에서 JWS를 만들고 결과 JWS를 output-variable
변수에 저장합니다. 결과는 json-content
변수에 JSON 페이로드가 있고 JSON 페이로드 내 속성이 JWT에 유효한 경우에만 서명된 JWT가 됩니다. 예를 들어 exp
속성이 있는 경우 이 속성에 숫자 값이 있어야 합니다. aud
속성이 있는 경우 문자열이나 문자열 배열이어야 합니다. 그 밖에도 많은 사례가 있습니다. JWT 클레임에 유효한 값에 대한 자세한 내용은 IETF RFC7519를 참조하세요.
<GenerateJWS name="JWS-Generate-HS256-JWT"> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <Payload ref="json-content"/> <AdditionalHeaders> <Claim name="typ">JWT</Claim> </AdditionalHeaders> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
분리 JWS 생성
이 정책 예시에서는 RS256 알고리즘을 사용하여 서명된 분리된 콘텐츠로 JWS를 생성합니다. RS256 서명 생성에는 RSA 비공개 키가 사용되며, 이는 PEM 인코딩 형식으로 제공되어야 합니다.
분리 콘텐츠가 있는 JWS는 생성된 JWS에서 페이로드를 생략합니다.
[header]..[signature]
<Payload>
요소를 사용하여 인코딩되지 않은 원시 JWS 페이로드를 지정합니다.
이 정책이 트리거될 때 Apigee는 JWS 헤더와 페이로드를 인코딩한 후 이를 사용하여 인코딩된 서명을 생성합니다. 그러나 생성된 JWS는 직렬화된 JWS에서 인코딩된 페이로드를 생략합니다. 이 기능은 서명된 콘텐츠가 대용량이거나 바이너리(예: 이미지 또는 PDF)인 경우에 유용합니다. 유효성 검사를 허용하려면 요소 및 서명된 콘텐츠에 포함된 JWS와 페이로드를 모두 확인 당사자에게 전달해야 합니다. VerifyJWS 정책을 사용하여 JWS를 확인하는 경우 VerifyJWS 정책의 <DetachedContent>
요소를 사용하여 페이로드가 포함된 변수를 지정할 수 있습니다.
<GenerateJWS name="JWS-Generate-RS256"> <DisplayName>JWS Generate RS256</DisplayName> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Payload ref="my-payload"/> <DetachContent>true</DetachContent> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
주요 요소 설정
JWS를 생성하는 데 사용되는 키 지정에 사용하는 요소는 다음 표와 같이 선택한 알고리즘에 따라 다릅니다.
알고리즘 | 주요 요소 | |
---|---|---|
HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> |
|
RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey>
|
|
*키 요구사항에 대한 자세한 내용은 서명 암호화 알고리즘 정보를 참조하세요. |
Generate JWS의 요소 참조
정책 참조는 Generate JWS 정책의 요소 및 속성을 설명합니다.
참고: 구성은 사용하는 암호화 알고리즘에 따라 다소 달라질 수 있습니다. 특정 사용 사례의 구성을 보여주는 예시는 샘플을 참조하세요.
최상위 요소에 적용되는 속성
<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">
다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.
속성 | 설명 | 기본값 | Presence |
---|---|---|---|
이름 |
정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ % 로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.
선택적으로 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.
정책이 실패해도 흐름 실행이 계속되도록 하려면 |
false | 선택사항 |
사용 설정됨 | 정책을 시행하려면 true 로 설정합니다.
|
true | 선택사항 |
async | 이 속성은 지원이 중단되었습니다. | false | 지원 중단됨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
이름 속성 외에도 이 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.
기본값 | 이 요소를 생략하면 정책 이름 속성 값이 사용됩니다. |
Presence | 선택사항 |
유형 | 문자열 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
토큰 서명을 위한 암호화 알고리즘을 지정합니다.
기본값 | 해당 사항 없음 |
Presence | 필수 |
유형 | 문자열 |
유효한 값 | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
JWS의 헤더에 추가 클레임 이름/값 쌍을 넣습니다.
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유효한 값 | 추가 클레임에 사용할 값입니다. 클레임을 문자열, 숫자, 부울, 맵 또는 배열로 명시적으로 지정할 수 있습니다. |
<Claim>
요소는 다음 속성을 사용합니다.
- name - (필수) 매개변수라고도 하는 클레임의 이름입니다.
- ref - (선택사항) 흐름 변수의 이름입니다. 이 이름이 있으면 정책에서는 이 변수의 값을 클레임으로 사용합니다. ref 속성 및 명시적 클레임 값이 모두 지정되면 명시적 값이 기본값이 되고 참조된 흐름 변수가 해결되지 않은 경우에 사용됩니다.
- type - (선택사항) 문자열(기본값), 숫자, 부울, 맵 중 하나입니다.
- array - (선택사항) 값이 유형의 배열인지 나타내려면 true로 설정합니다. 기본값은 false입니다.
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
JWS에 critical header(crit)를 추가합니다. crit 헤더는 JWS 수신자가 알고 인식해야 하는 헤더 이름의 배열입니다. 예를 들어 이 구성 요소를 사용하여 디코딩 시 다음과 같은 JWS 헤더를 생성할 수 있습니다.
{ "typ": "...", "alg" : "...", "hyb" : "some-value-here", "crit" : [ "hyb" ], }
이 JWS 헤더는 hyb 헤더 매개변수가 중요도가 높으며, JWS의 모든 수신자가 해당 매개변수의 의미와 값을 이해하도록 어설션합니다.
IETF RFC 7515에 따라 JWS 수신자는 수신자가 crit 매개변수를 참조하는 매개변수 하나 이상을 이해하지 못하면 JWS를 잘못된 것으로 여겨 거부해야 합니다. Apigee에서 VerifyJWS 정책은 이 동작을 따릅니다.
crit 매개변수에 나열된 각 매개변수의 경우 VerifyJWS 정책의 <KnownHeaders>
요소에도 해당 매개변수가 나열되는지 확인합니다.
VerifyJWS 정책이 <KnownHeaders>
에 나열되지 않은 crit에서 찾은 모든 헤더로 인해 VerifyJWS 정책에서 JWS를 거부합니다.
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유형 | 쉼표로 구분된 문자열 하나 이상의 배열 |
유효한 값 | 배열 또는 배열이 포함된 변수에 대한 참조 |
<DetachContent>
<DetachContent>true|false</DetachContent>
분리된 페이로드(<DetachContent>true</DetachContent>
) 또는 그렇지 않은 페이로드(<DetachContent>false</DetachContent>
)로 JWS를 생성할지 여부를 지정합니다.
기본값 false를 지정하면 생성되는 JWS가 다음과 같은 형식입니다.
[header].[payload].[signature]
분리된 페이로드를 사용하여 JWS를 만들기 위해 true를 지정하면 생성된 JWS에서 페이로드를 생략하고 다음과 같은 형식이 됩니다.
[header]..[signature]
분리 페이로드를 사용하는 JWS를 사용하면 직렬화된 JWS와 함께 인코딩되지 않은 원본 페이로드를 확인 당사자에게 전달할 책임은 사용자에게 있습니다.
기본값 | false |
Presence | 선택사항 |
유형 | 불리언 |
유효한 값 | true 또는 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
정책에 지정된 참조 변수를 해결할 수 없는 경우 정책에서 오류가 발생하게 하려면 false로 설정합니다. 해결할 수 없는 변수를 빈 문자열(null)로 취급하려면 true로 설정합니다.
기본값 | false |
Presence | 선택사항 |
유형 | 불리언 |
유효한 값 | true 또는 false |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
정책이 생성된 JWS로 설정할 컨텍스트 변수의 이름을 지정합니다.
기본적으로 정책은 JWS를 jws.POLICYNAME.generated_jws
라는 컨텍스트 변수에 배치합니다.
기본값 | jws.POLICYNAME.generated_jws |
Presence | 선택사항 |
유형 | 문자열(흐름 변수 이름) |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
인코딩되지 않은 원시 JWS 페이로드를 지정합니다. 페이로드가 포함된 변수 또는 문자열을 지정합니다.
기본값 | 해당 사항 없음 |
Presence | 필수 |
유형 | 문자열, 바이트 배열, 스트리밍, 다른 인코딩되지 않은 JWS 페이로드 표현 |
유효한 값 | 메시지 템플릿 또는 페이로드가 포함된 변수에 대한 참조 |
<PrivateKey> 요소
<Algorithm>
가 RS*, PS* 또는 ES* 옵션 중 하나인 경우에만 사용할 수 있습니다. 서명에 사용할 비공개 키와 비공개 키와 관련된 기타 정보를 지정합니다. 이는 알고리즘이 비대칭 알고리즘인 경우에 사용됩니다.
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
기본값: | 해당 사항 없음 |
Presence: | 선택사항. 그러나 <PrivateKey> 또는 <SecretKey> 요소 중 하나가 정확하게 포함되어야 합니다.
알고리즘이 RS*, PS* 또는 ES*인 경우에는 <PrivateKey> 요소를 사용하고 알고리즘이 HS*인 경우에는 <SecretKey> 요소를 사용합니다.
|
유형: | 해당 사항 없음 |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
JWS 헤더에 포함할 키 ID(kid)를 지정합니다.
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유형 | 문자열 |
유효한 값 | 흐름 변수 또는 문자열 |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
필요한 경우 정책에서 비공개 키를 복호화하는 데 사용할 비밀번호를 지정합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다.
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유형 | 문자열 |
유효한 값 |
흐름 변수 참조입니다. 참고: ref 속성이 있는 흐름 변수를 지정해야 합니다. Apigee는 비밀번호가 일반 텍스트로 지정된 정책 구성을 잘못된 것으로 여겨 거부합니다. 흐름 변수에는 'private' 프리픽스가 있어야 합니다. 예를 들면 |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
JWS에 서명하는 데 사용되는 PEM 인코딩 비공개 키를 지정합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다.
기본값 | 해당 사항 없음 |
Presence | RS*, PS* 또는 ES* 알고리즘 중 하나를 사용하여 JWS를 생성하는 정책을 사용할 때 필요합니다. |
유형 | 문자열 |
유효한 값 | PEM 인코딩 비공개 키 값을 나타내는 문자열을 포함하는 흐름 변수입니다. 참고: 흐름 변수에는 프리픽스 'private'이 있어야 합니다. 예를 들면 |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
HS256, HS384 또는 HS512 중 하나의 대칭(HS*) 알고리즘을 사용하는 JWS를 생성할 때 사용할 보안 비밀 키를 지정합니다.
이 요소는 선택사항입니다. 그러나 <PrivateKey>
또는 <SecretKey>
요소 중 하나가 정확하게 포함되어야 합니다.
비대칭 알고리즘(RS*, PS*, ES* 중 하나)으로 서명된 JWS를 생성할 때는 <PrivateKey>
요소를 사용하고, HS*와 같은 대칭 알고리즘을 사용하여 JWS를 생성할 때는 <SecretKey>
요소를 사용합니다.
<SecretKey>
의 하위 요소
다음 표에서는 <SecretKey>
의 하위 요소와 속성에 대한 설명을 제공합니다.
자녀 | Presence | 설명 |
---|---|---|
인코딩(속성) | 선택사항 | 참조된 변수에서 키가 인코딩되는 방식을 지정합니다. 기본적으로 <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 위의 예시에서는 인코딩이 |
ID(요소) | 선택사항 | 키 식별자입니다. 이 값은 어떤 문자열이라도 가능합니다. <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> 정책은 이 키 식별자를 생성된 JWS의 헤더에서 |
값(요소) | 필수 | 인코딩된 보안 비밀 키 페이로드에 서명하는 데 사용되는 보안 비밀 키를 지정합니다.
<SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee는 HS256/HS384/HS512 알고리즘에 최소한의 키 안전성을 적용합니다. 최소 키 길이는 HS256의 경우 32바이트, HS384의 경우 48바이트, HS512의 경우 64바이트입니다. 낮은 안정성의 키를 사용하면 런타임 오류가 발생합니다. |
<Type>
<Type>type-string-here</Type>
허용된 값만 Signed
인 선택적 요소로, 정책이 서명된 JWS를 생성하도록 지정합니다. <Type>
은 GenerateJWT 및 VerifyJWT 정책의 해당 요소를 일치시키기 위해 제공됩니다(Signed
또는 Encrypted
값 중 하나에서 사용 가능).
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유형 | 문자열 |
유효한 값 | Signed |
흐름 변수
Generate JWS 정책은 흐름 변수를 설정하지 않습니다.
오류 참조
이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 발생 상황 |
---|---|---|
steps.jws.GenerationFailed |
401 |
정책이 JWS를 생성하지 못했습니다. |
steps.jws.InsufficientKeyLength |
401 |
HS256 알고리즘의 키가 32바이트 미만인 경우 |
steps.jws.InvalidClaim |
401 |
소유권 클레임 누락 또는 소유권 클레임 불일치, 헤더 또는 헤더 불일치 누락일 때 발생합니다. |
steps.jws.InvalidCurve |
401 |
키에서 지정한 곡선은 타원 곡선 알고리즘에 유효하지 않습니다. |
steps.jws.InvalidJsonFormat |
401 |
JWS 헤더에 잘못된 JSON이 있습니다. |
steps.jws.InvalidPayload |
401 |
JWS 페이로드가 잘못되었습니다. |
steps.jws.InvalidSignature |
401 |
<DetachedContent> 가 생략되고 JWS에 분리된 콘텐츠 페이로드가 있습니다. |
steps.jws.KeyIdMissing |
401 |
확인 정책은 JWKS를 공개 키의 소스로 사용하지만 서명된 JWS에는 헤더의 kid 속성이 포함되지 않습니다. |
steps.jws.KeyParsingFailed |
401 |
지정된 키 정보에서 공개 키를 파싱할 수 없습니다. |
steps.jws.MissingPayload |
401 |
JWS 페이로드가 누락되었습니다. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
JWS에서 알고리즘 헤더가 생략되면 발생합니다. |
steps.jws.SigningFailed |
401 |
GenerateJWS에서 HS384 또는 HS512 알고리즘의 최소 크기보다 작은 키일 때 발생합니다. |
steps.jws.UnknownException |
401 |
알 수 없는 예외가 발생했습니다. |
steps.jws.WrongKeyType |
401 |
잘못된 유형의 키가 지정되었습니다. 예를 들어 타원 곡선 알고리즘의 RSA 키를 지정하거나 RSA 알고리즘의 곡선 키를 지정하는 경우입니다. |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 발생 상황 |
---|---|
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>