GenerateJWT 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

내용

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

동영상

짧은 동영상을 시청하여 서명된 JWT를 생성하는 방법을 알아보세요.

샘플

• HS256 알고리즘으로 서명된 JWT 생성
• RS256 알고리즘으로 서명된 JWT 생성

HS256 알고리즘으로 서명된 JWT 생성

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

이 정책 작업이 트리거되면 Edge는 JWT 헤더와 페이로드를 인코딩한 후 JWT에 디지털 서명합니다. 위의 동영상을 통해 정책에 대해 요청을 수행하는 방법을 포함한 전체 예시를 확인하세요.

여기에서 정책 구성은 JWT 사양에 정의된 대로 1시간의 만료 시간을 포함하는 표준 클레임과 추가 클레임을 생성합니다. 추가 클레임은 원하는 만큼 포함할 수 있습니다. 이 샘플 정책의 각 요소에 대한 요구사항 및 옵션에 대한 자세한 내용은 요소 참조를 확인하세요.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

결과 JWT에는 다음 헤더가 포함됩니다.

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

그리고 다음과 같은 콘텐츠가 포함된 페이로드를 가집니다.

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

iat, exp, jti 클레임의 값은 달라집니다.

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

이 정책 예시에서는 새 JWT를 생성하고 RS256 알고리즘을 사용하여 서명합니다. RS256 서명 생성에는 RSA 비공개 키가 사용되며, 이는 PEM 인코딩 형식으로 제공되어야 합니다. 위의 동영상을 통해 정책에 대해 요청을 수행하는 방법을 포함한 전체 예시를 확인하세요.

이 정책 작업이 트리거되면 Edge는 클레임을 포함하여 JWT를 인코딩하고 디지털 방식으로 서명합니다. JWT의 부분과 암호화 및 서명 방법을 알아보려면 RFC7519를 참조하세요.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

주요 요소 설정

JWT 생성에 사용되는 키를 지정하는 데 사용하는 요소는 다음 표와 같이 선택한 알고리즘에 따라 다릅니다.

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

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

Generate JWT의 요소 참조

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

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

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

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

이름 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기에서 다른 자연어 이름으로 정책에 라벨을 지정합니다.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

토큰 서명을 위한 암호화 알고리즘을 지정합니다.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

정책은 지정된 값으로 설정된 aud 클레임을 포함하는 JWT를 생성합니다. 이 클레임은 JWT가 대상인 수신자를 식별하며, RFC7519에 언급된 등록된 클레임 중 하나입니다.

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

JWT의 페이로드에 추가 클레임 이름/값 쌍을 지정할 수 있습니다. 클레임을 문자열, 숫자, 부울, 맵 또는 배열로 명시적으로 지정할 수 있습니다. 맵은 단순히 이름/값 쌍의 집합입니다.

<Claim> 요소는 다음 속성을 사용합니다.

• name - (필수) 클레임의 이름입니다.
• ref - (선택사항) 흐름 변수의 이름입니다. 이 이름이 있으면 정책에서는 이 변수의 값을 클레임으로 사용합니다. ref 속성 및 명시적 클레임 값이 모두 지정되면 명시적 값이 기본값이 되고 참조된 흐름 변수가 해결되지 않은 경우에 사용됩니다.
• type - (선택사항) 문자열(기본값), 숫자, 부울, 맵 중 하나입니다.
• array - (선택사항) 값이 유형의 배열인지 나타내려면 true로 설정합니다. 기본값은 false입니다.

<Claim> 요소를 포함하면 정책을 구성할 때 클레임 이름이 정적으로 설정됩니다. 또는 JSON 객체를 전달하여 클레임 이름을 지정할 수 있습니다. JSON 객체는 변수로 전달되므로 생성된 JWT의 클레임 이름은 런타임에 결정됩니다.

예를 들면 다음과 같습니다.

<AdditionalClaims ref='json_claims'/>

여기서 변수 json_claims에는 JSON 객체가 다음 형식으로 포함됩니다.

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

생성된 JWT에는 JSON 객체의 모든 클레임이 포함됩니다.

<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>

JWT의 헤더에 추가 클레임 이름/값 쌍을 넣습니다.

<Claim> 요소는 다음 속성을 사용합니다.

• name - (필수) 클레임의 이름입니다.
• ref - (선택사항) 흐름 변수의 이름입니다. 이 이름이 있으면 정책에서는 이 변수의 값을 클레임으로 사용합니다. ref 속성 및 명시적 클레임 값이 모두 지정되면 명시적 값이 기본값이 되고 참조된 흐름 변수가 해결되지 않은 경우에 사용됩니다.
• type - (선택사항) 문자열(기본값), 숫자, 부울, 맵 중 하나입니다.
• array - (선택사항) 값이 유형의 배열인지 나타내려면 true로 설정합니다. 기본값은 false입니다.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

JWT 헤더에 critical header(crit)를 추가합니다. crit 헤더는 JWT 수신자가 알고 인식할 수 있어야 하는 헤더 이름의 배열입니다. 예를 들면 다음과 같습니다.

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

런타임 시 VerifyJWT 정책이 crit 헤더를 검사합니다. crit 헤더에 나열된 각 항목에 대해, VerifyJWT 정책의 <KnownHeaders> 요소에도 해당 헤더가 나열되는지 확인합니다. VerifyJWT 정책이 <KnownHeaders>에 나열되지 않은 crit에서 찾은 모든 헤더로 인해 VerifyJWT 정책이 실패합니다.

<CustomClaims>

참고: 현재 UI를 통해 새 GenerateJWT 정책을 추가하면 CustomClaims 요소가 삽입됩니다. 이 요소는 작동하지 않으며 무시됩니다. 대신 사용할 수 있는 올바른 요소는 <AdditionalClaims>입니다. 이 UI는 나중에 올바른 요소를 삽입하도록 업데이트됩니다.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

JWT의 수명을 밀리초, 초, 분, 시간, 일로 지정합니다.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

특정 jti 클레임이 있는 JWT를 생성합니다. 텍스트 값과 ref 속성이 모두 비어있으면 정책은 임의의 UUID를 포함하는 jti를 생성합니다. JWT ID(jti) 클레임은 JWT의 고유 식별자입니다. jti에 대한 자세한 내용은 RFC7519를 참조하세요.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

이 정책은 값이 특정 값으로 설정된 iss라는 클레임을 포함하는 JWT를 생성합니다. iss라는 클레임은 JWT의 발급자를 식별하는 클레임이며, 이는 RFC7519에 언급된, 등록된 클레임 중 하나입니다.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

토큰이 유효해지는 시간을 지정합니다. 토큰은 지정된 시간까지 유효하지 않습니다. 절대적 시간 값 또는 토큰이 생성되는 시간을 기준으로 하는 상대적 시간을 지정할 수 있습니다.

절대적 시간 값에 대한 NotBefore 요소의 올바른 시간 값

상대적 시간 값의 경우 다음과 같이 정수와 기간을 지정합니다.

• 10s
• 60m
• 12시간

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

이 정책으로 생성된 JWT를 저장할 위치를 지정합니다. 기본적으로 흐름 변수 jwt.POLICYNAME.generated_jwt에 저장됩니다.

<PrivateKey/Id>

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

or

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

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

<PrivateKey/Password>

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

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

<PrivateKey/Value>

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

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

<SecretKey/Id>

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

or

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

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

<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바이트입니다. 낮은 안정성의 키를 사용하면 런타임 오류가 발생합니다.

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

예를 들면 다음과 같습니다.

<Subject ref="apigee.developer.email"/>

이 정책은 특정 값으로 설정된 sub 클레임을 포함하는 JWT를 생성합니다. 이 클레임은 JWT의 제목을 식별하거나 설명합니다. 이는 RFC7519에 언급된 표준 클레임 중 하나입니다.

흐름 변수

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

오류 참조

이 섹션에서는 반환되는 오류 코드, 오류 메시지, 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 변수

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

오류 응답 예시

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