GenerateJWS 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보

대상

구성 가능한 클레임 세트를 포함하는 서명된 JWS를 생성합니다. JWS는 클라이언트에 반환되거나, 백엔드 대상으로 전송되거나, 다른 방식으로 사용될 수 있습니다. 자세한 소개는 JWS 및 JWT 정책 개요를 참조하세요.

JWS의 각 부분, 암호화, 서명 방법에 대한 자세한 내용은 RFC7515를 참조하세요.

동영상

짧은 동영상을 시청하여 서명된 JWT를 생성하는 방법을 알아보세요. 이 동영상은 JWT를 생성하는 데만 해당하지만 대부분의 개념은 JWS와 동일합니다.

샘플

HS256 알고리즘으로 서명된 연결 JWS 생성

이 예시 정책은 연결된 JWS를 생성하고 HS256 알고리즘을 사용하여 서명합니다. HS256은 서명 및 서명 확인 모두에서 공유 보안 비밀에 의존합니다.

연결 JWS에는 인코딩된 헤더, 페이로드, 서명이 포함됩니다.

header.payload.signature

<DetachContent>를 true로 설정하여 분리된 콘텐츠를 생성합니다. JWS의 구조와 형식에 대한 자세한 내용은 JWS/JWT를 구성하는 요소를 참조하세요.

<Payload> 요소를 사용하여 인코딩되지 않은 원시 JWS 페이로드를 지정합니다. 이 예시에서는 변수에 페이로드가 포함됩니다. 이 정책 작업이 트리거되면 Edge는 JWS 헤더와 페이로드를 인코딩한 다음 인코딩된 서명을 추가하여 JWS에 디지털 서명합니다.

아래의 정책 구성은 private.payload 변수에 포함된 페이로드에서 JWS를 만듭니다.

<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="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

RS256 알고리즘으로 서명된 분리 JWS 생성

이 예시 정책은 분리된 JWS를 생성하고 RS256 알고리즘을 사용하여 이를 서명합니다. RS256 서명 생성에는 RSA 비공개 키가 사용되며, 이는 PEM 인코딩 형식으로 제공되어야 합니다.

분리 JWS는 JWS에서 페이로드를 생략합니다.

header..signature

<Payload> 요소를 사용하여 인코딩되지 않은 원시 JWS 페이로드를 지정합니다. 이 정책이 트리거되면 Edge는 JWS 헤더와 페이로드를 인코딩합니다. 이를 사용하여 인코딩된 서명을 생성합니다. 하지만 생성된 JWS가 페이로드를 생략합니다. VerifyJWS 정책의 <DetachedContent> 요소를 사용하여 VerifyJWS 정책에 페이로드를 전달하는 것은 사용자에게 달려 있습니다.

<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="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-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>

<Password> 및 <Id> 요소는 선택사항입니다.
*키 요구사항에 대한 자세한 내용은 서명 암호화 알고리즘 정보를 참조하세요.

Generate JWS의 요소 참조

정책 참조는 Generate JWS 정책의 요소 및 속성을 설명합니다.

참고: 구성은 사용하는 암호화 알고리즘에 따라 다소 달라질 수 있습니다. 특정 사용 사례의 구성을 보여주는 예시는 샘플을 참조하세요.

최상위 요소에 적용되는 속성

<GenerateJWS name="JWS" 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 선택사항
유형 문자열

<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 수신자가 알고 인식해야 하는 헤더 이름의 배열입니다. 예를 들면 다음과 같습니다.

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

런타임 시 VerifyJWS 정책이 crit 헤더를 검사합니다. crit 헤더에 나열된 각 항목에 대해, VerifyJWS 정책의 <KnownHeaders> 요소에도 해당 헤더가 나열되는지 확인합니다. 정책이 crit에서 발견하고 <KnownHeaders>에도 나열되지 않는 모든 헤더는 VerifyJWS 정책에 오류를 발생시킵니다.

기본값 해당 사항 없음
Presence 선택사항
유형 쉼표로 구분된 문자열 배열
유효한 값 배열 또는 배열이 포함된 변수의 이름

<DetachContent>

<DetachContent>true|false</DetachContent>

분리된 페이로드(<DetachContent>true</DetachContent>) 또는 그렇지 않은 페이로드(<DetachContent>false</DetachContent>)로 JWS를 생성할지 여부를 지정합니다.

기본값 false를 지정하면 생성되는 JWS가 다음과 같은 형식입니다.

header.payload.signature

분리된 페이로드를 만들기 위해 true를 지정하면 생성된 JWS가 페이로드를 생략하고 다음과 같은 형식이 됩니다.

header..signature

분리된 페이로드의 경우 인코딩되지 않은 원본 페이로드를 VerifyJWS 정책의 <DetachedContent> 요소를 사용하여 VerifyJWS 정책에 전달하는 것은 사용자에게 달려 있습니다.

기본값 거짓
Presence 선택사항
유형 부울
유효한 값 true 또는 false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

정책에 지정된 참조 변수를 해결할 수 없는 경우 정책에서 오류가 발생하게 하려면 false로 설정합니다. 해결할 수 없는 변수를 빈 문자열(null)로 취급하려면 true로 설정합니다.

기본 거짓
Presence 선택사항
유형 부울
유효한 값 true 또는 false

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

이 정책으로 생성된 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/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

JWS 헤더에 포함할 키 ID(kid)를 지정합니다. 알고리즘이 RS256/RS384/RS512, PS256/PS384/PS512 또는 ES256/ES384/ES512인 경우에만 사용합니다.

기본값 해당 사항 없음
Presence 선택사항
유형 문자열
유효한 값 흐름 변수 또는 문자열

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

필요한 경우 정책에서 비공개 키를 복호화하는 데 사용할 비밀번호를 지정합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다. 알고리즘이 RS256/RS384/RS512, PS256/PS384/PS512 또는 ES256/ES384/ES512인 경우에만 사용합니다.

기본값 해당 사항 없음
Presence 선택사항
유형 문자열
유효한 값 흐름 변수 참조입니다.

참고: 흐름 변수를 지정해야 합니다. Edge가 유효하지 않은 것으로 간주하여 거부합니다. 암호가 일반 텍스트로 지정된 정책 구성입니다. 흐름 변수에는 프리픽스 'private'이 있어야 합니다. 예: private.mypassword

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

JWS에 서명하는 데 사용되는 PEM 인코딩 비공개 키를 지정합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다. 알고리즘이 RS256/RS384/RS512, PS256/PS384/PS512 또는 ES256/ES384/ES512인 경우에만 사용합니다.

기본값 해당 사항 없음
현재 상태 RS256 알고리즘을 사용하여 JWS를 생성하는 데 필요합니다.
유형 문자열
유효한 값 PEM 인코딩 RSA 비공개 키 값을 나타내는 문자열을 포함하는 흐름 변수입니다.

참고: 흐름 변수에는 프리픽스 'private'이 있어야 합니다. 예를 들면 private.mykey입니다.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

HMAC 알고리즘으로 서명된 JWS의 JWS 헤더에 포함할 키 ID(kid)를 지정합니다. 알고리즘이 HS256/HS384/HS512 중 하나인 경우에만 사용합니다.

기본값 해당 사항 없음
Presence 선택사항
유형 문자열
유효한 값 흐름 변수 또는 문자열

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

HMAC 알고리즘으로 토큰을 확인하거나 서명하는 데 사용되는 보안 비밀 키를 제공합니다. 알고리즘이 HS256/HS384/HS512 중 하나인 경우에만 사용합니다. ref 속성을 사용하여 흐름 변수에 키를 전달합니다.

Edge는 HS256/HS384/HS512 알고리즘에 최소 키 강도를 적용합니다. 최소 키 길이는 HS256의 경우 32바이트, HS384의 경우 48바이트, HS512의 경우 64바이트입니다. 낮은 안정성의 키를 사용하면 런타임 오류가 발생합니다.

기본값 해당 사항 없음
Presence HMAC 알고리즘에 필요합니다.
유형 문자열
유효한 값 문자열을 참조하는 흐름 변수

참고: 흐름 변수의 경우 프리픽스 'private'이 있어야 합니다. 예를 들면 private.mysecret입니다.

흐름 변수

Generate JWS 정책은 흐름 변수를 설정하지 않습니다.

오류 참조

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 Occurs when
steps.jws.GenerationFailed 401 The policy was unable to generate the JWS.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
steps.jws.InvalidPayload 401 The JWS payload is invalid.
steps.jws.InvalidSignature 401 <DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.SigningFailed 401 In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

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

Error name Occurs when
InvalidAlgorithm The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 Other possible deployment errors.

오류 변수

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

변수 장소 예
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>