<ph type="x-smartling-placeholder"></ph>
현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보
대상
클라이언트 또는 다른 시스템에서 수신한 JWS의 서명을 인증합니다. 또한 이 정책은 헤더를 컨텍스트 변수로 추출하여 이후 정책 또는 조건이 해당 값을 검사하여 승인 또는 라우팅을 결정할 수 있도록 합니다. 자세한 소개는 JWS 및 JWT 정책 개요를 참조하세요.
JWS가 인증되고 유효한 경우 요청을 진행할 수 있습니다. JWS 서명을 인증할 수 없거나 일부 유형의 오류로 인해 JWS가 유효하지 않은 경우 모든 처리가 중지되고 응답에서 오류가 반환됩니다.
JWS의 각 부분, 암호화, 서명 방법에 대한 자세한 내용은 RFC7515를 참조하세요.
동영상
짧은 동영상을 보고 JWS에서 서명을 인증하는 방법을 알아보세요. 이 동영상은 JWT를 인증하는 데만 해당하지만 대부분의 개념은 JWS와 동일합니다.
샘플
HS256 알고리즘으로 서명된 연결 JWS 인증
이 정책 예시에서는 SHA-256 체크섬을 사용하여 HS256 암호화 알고리즘인 HMAC로 서명된 연결 JWS를 확인합니다. JWS는 프록시 요청에서 JWS
라는 양식 매개변수를 사용하여 전달됩니다. 이 키는 private.secretkey
라는 변수에 포함됩니다.
연결 JWS에는 인코딩된 헤더, 페이로드, 서명이 포함됩니다.
header.payload.signature
정책 구성에는 Edge에서 JWS를 디코딩하고 평가하는 데 필요한 정보가 포함됩니다.
<Source>
요소에 지정된 흐름 변수에서 JWS를 찾을 위치 등
필요한 서명 알고리즘, 보안 비밀 키 (에지 흐름 변수에 저장됨)를 찾을 위치
예를 들어 Edge KVM에서 검색됨).
<VerifyJWS name="JWS-Verify-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </VerifyJWS>
정책은 API 프록시의 후속 정책 또는 조건이 해당 값을 검사할 수 있도록 출력물을 컨텍스트 변수에 씁니다. 이 정책에 의해 설정된 변수 목록은 흐름 변수를 참조하세요.
RS256 알고리즘으로 서명된 분리 JWS 확인
이 예시 정책은 RS256 알고리즘으로 서명된 분리 JWS를 인증합니다. 확인하려면 공개 키를 제공해야 합니다. JWS는 프록시 요청에서 JWS
라는 양식 매개변수를 사용하여 전달됩니다. 공개 키는 이름이 public.publickey
인 변수에 포함되어 있습니다.
분리 JWS는 JWS에서 페이로드를 생략합니다.
header..signature
페이로드가 포함된 변수 이름을 <DetachedContent>
요소에 지정하여 VerifyJWS 정책에 페이로드를 전달할 수 있습니다. <DetachedContent>
에 지정된 콘텐츠는 JWS 서명이 생성될 때 원래 인코딩되지 않은 형식이어야 합니다.
<VerifyJWS name="JWS-Verify-RS256"> <DisplayName>JWS Verify RS256</DisplayName> <Algorithm>RS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </PublicKey> <DetachedContent>private.payload</DetachedContent> </VerifyJWS>
정책은 API 프록시의 후속 정책 또는 조건이 해당 값을 검사할 수 있도록 출력물을 컨텍스트 변수에 씁니다. 이 정책에 의해 설정된 변수 목록은 흐름 변수를 참조하세요.
주요 요소 설정
JWS 인증 에 사용되는 키를 지정하는 데 사용하는 요소는 다음 표와 같이 선택한 알고리즘에 따라 다릅니다.
알고리즘 | 주요 요소 | |
---|---|---|
HS* |
<SecretKey> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key"/> </PublicKey> 또는: <PublicKey> <JWKS ref="jwks_val_ref_or_url"/> </PublicKey> |
|
*키 요구사항에 대한 자세한 내용은 서명 암호화 알고리즘 정보를 참조하세요. |
요소 참조
정책 참조는 JWS 정책 인증의 요소 및 속성을 설명합니다.
참고: 구성은 사용하는 암호화 알고리즘에 따라 다소 달라질 수 있습니다. 특정 사용 사례의 구성을 보여주는 예시는 샘플을 참조하세요.
최상위 요소에 적용되는 속성
<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">
다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.
속성 | 설명 | 기본 | Presence |
---|---|---|---|
이름 |
정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ % 로 제한됩니다. 하지만 에지 관리 UI는
영숫자가 아닌 문자를 자동으로 삭제하는 등의 제한 사항이 있습니다.
선택적으로 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.
정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
사용 설정됨 | 정책을 시행하려면 true 로 설정합니다.
|
true | 선택사항 |
비동기 | 이 속성은 지원이 중단되었습니다. | 거짓 | 지원 중단됨 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
이름 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기에서 다른 자연어 이름으로 정책에 라벨을 지정합니다.
기본 | 이 요소를 생략하면 정책 이름 속성 값이 사용됩니다. |
Presence | 선택사항 |
유형 | 문자열 |
<Algorithm>
<Algorithm>HS256</Algorithm>
토큰 서명을 위한 암호화 알고리즘을 지정합니다. RS*/PS*/ES* 알고리즘은 공개/보안 비밀 키 쌍을 사용하지만 HS* 알고리즘은 공유 보안 비밀을 사용합니다. 서명 암호화 알고리즘 정보도 참조하세요.
여러 값을 쉼표로 구분하여 지정할 수 있습니다. 예를 들면 'HS256, HS512' 또는 'RS256, PS256'입니다. 그러나 HS* 알고리즘은 다른 알고리즘이나 ES* 알고리즘과 결합할 수 없습니다. 이 경우 특정 키 유형이 필요합니다. RS* 및 PS* 알고리즘은 결합할 수 있습니다.
기본 | 해당 사항 없음 |
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 헤더에 지정된 추가 클레임 이름/값 쌍이 포함되어 있고 보장된 클레임 값이 일치하는지 확인합니다.
추가 클레임은 등록된 표준 JWS 클레임 이름이 아닌 다른 이름을 사용합니다. 추가 클레임 값은 문자열, 숫자, 부울, 지도, 배열일 수 있습니다. 지도는 단순히 이름/값 쌍의 조합입니다. 이러한 모든 유형의 클레임 값은 정책 구성에서 명시적으로 지정하거나 흐름 변수 참조를 통해 간접적으로 지정할 수 있습니다.
기본 | 해당 사항 없음 |
Presence | 선택사항 |
유형 |
문자열(기본값), 숫자, 부울 또는 맵입니다. 유형이 지정되지 않은 경우 유형은 기본적으로 문자열입니다. |
배열 | 값이 유형 배열인지 여부를 나타내기 위해 true로 설정합니다. 기본값: false |
유효한 값 | 추가 클레임에 사용할 모든 값입니다. |
<Claim>
요소는 다음 속성을 사용합니다.
- name - (필수) 클레임의 이름입니다.
- ref - (선택사항) 흐름 변수의 이름입니다. 이 이름이 있으면 정책에서는 이 변수의 값을 클레임으로 사용합니다. ref 속성 및 명시적 클레임 값이 모두 지정되면 명시적 값이 기본값이 되고 참조된 흐름 변수가 해결되지 않은 경우에 사용됩니다.
- type - (선택사항) 문자열(기본값), 숫자, 부울, 맵 중 하나입니다.
- array - (선택사항) 값이 유형의 배열인지 나타내려면 true로 설정합니다. 기본값은 false입니다.
<DetachedContent>
<DetachedContent>variable-name-here</DetachedContent>
콘텐츠 페이로드가 포함된 생성된 JWS는 다음과 같은 형식입니다.
header.payload.signature
GenerateJWS 정책을 사용하여 분리된 페이로드를 만드는 경우 생성된 JWS는 페이로드를 생략하고 다음과 같은 형식이 됩니다.
header..signature
분리된 페이로드의 경우 <DetachedContent>
요소를 사용하여 페이로드를 VerifyJWS 정책에 전달할 책임은 사용자에게 있습니다. 지정된 콘텐츠 페이로드는 JWS 서명이 생성될 때 원래 인코딩되지 않은 형식이어야 합니다.
다음과 같은 경우 정책에서 오류가 발생합니다.
- JWS가 분리된 콘텐츠 페이로드를 포함하지 않은 경우
<DetachedContent>
가 지정됩니다(결함 코드는steps.jws.ContentIsNotDetached
). <DetachedContent>
가 생략되고 JWS에는 분리된 콘텐츠 페이로드가 있습니다(결함 코드는steps.jws.InvalidSignature
).
기본값 | N/A |
Presence | 선택사항 |
유형 | 변수 참조 |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
JWS의 crit 헤더에 나열된 헤더가 <KnownHeaders>
요소에 나열되지 않는 경우 정책에서 오류가 발생하도록 하려면 false로 설정합니다.
VerifyJWS 정책이 crit 헤더를 무시하도록 하려면 true로 설정합니다.
이 요소를 true로 설정하는 이유 중 하나는 테스트 환경에 있고 누락된 헤더로 인해 정책에 오류가 생기지 않도록 하기 위함입니다.
기본값 | 거짓 |
Presence | 선택사항 |
유형 | 부울 |
유효한 값 | true 또는 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
정책에 지정된 참조 변수를 해결할 수 없는 경우 정책에서 오류가 발생하게 하려면 false로 설정합니다. 해결할 수 없는 변수를 빈 문자열(null)로 취급하려면 true로 설정합니다.
기본 | 거짓 |
Presence | 선택사항 |
유형 | 부울 |
유효한 값 | true 또는 false |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
GenerateJWS 정책은 <CriticalHeaders>
요소를 사용하여 토큰의 crit 헤더를 입력합니다. 예:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
VerifyJWS 정책은 JWS에서 crit 헤더가 있는 경우 이를 검사하고 나열된 각 항목에 대해 <KnownHeaders>
요소에 해당 헤더가 나열되는지 확인합니다. <KnownHeaders>
요소에는 crit에 나열된 항목의 상위 집합이 포함될 수 있습니다.
crit에 나열된 모든 헤더만 <KnownHeaders>
요소에 나열되어야 합니다. 정책이 crit에서 발견하고 <KnownHeaders>
에도 나열되지 않는 모든 헤더는 VerifyJWS 정책에 오류를 발생시킵니다.
선택적으로 <IgnoreCriticalHeaders>
요소를 true
로 설정하여 crit 헤더를 무시하도록 VerifyJWS 정책을 구성할 수 있습니다.
기본값 | 해당 사항 없음 |
Presence | 선택사항 |
유형 | 쉼표로 구분된 문자열 배열 |
유효한 값 | 배열 또는 배열이 포함된 변수의 이름입니다. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
공개 키 집합이 포함된 JWKS 형식(RFC 7517)의 값을 지정합니다. 알고리즘이 RS256/RS384/RS512, PS256/PS384/PS512 또는 ES256/ES384/ES512 중 하나인 경우에만 사용합니다.
인바운드 JWS가 JWKS 세트에 있는 키 ID를 보유하는 경우, 정책은 올바른 공개 키를 사용하여 JWS 서명을 인증합니다. 이 기능에 대한 자세한 내용은 JSON 웹 키 세트(JWKS)를 사용하여 JWS 인증을 참조하세요.
공개 URL에서 값을 가져오면 Edge는 300초 동안 JWKS를 캐시합니다. 캐시가 만료되면 Edge는 JWKS를 다시 가져옵니다.
기본 | 해당 사항 없음 |
Presence | RSA 알고리즘을 사용하여 JWS를 인증하려면 JWKS 또는 값 요소를 사용해야 합니다. |
유형 | 문자열 |
유효한 값 | 흐름 변수, 문자열 값 또는 URL입니다. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickey"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
JWS에서 서명을 인증하는 데 사용되는 공개 키를 지정합니다. ref 속성을 사용하여 흐름 변수의 키를 전달하거나 PEM으로 인코딩된 키를 직접 지정합니다. 알고리즘은 RS256/RS384/RS512, PS256/PS384/PS512 또는 ES256/ES384/ES512 중 하나인 경우에만 사용합니다.
기본 | 해당 사항 없음 |
Presence | RSA 알고리즘으로 서명된 JWS를 인증하려면 JWKS 또는 값 요소를 사용해야 합니다. |
유형 | 문자열 |
유효한 값 | 흐름 변수 또는 문자열입니다. |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
HMAC 알고리즘으로 토큰을 인증하거나 서명하는 데 사용되는 보안 비밀 키를 제공합니다. 알고리즘이 HS256, HS384, HS512 중 하나인 경우에만 사용합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다.
기본값 | 해당 사항 없음 |
Presence | HMAC 알고리즘에 필요합니다. |
유형 | 문자열 |
유효한 값 | 문자열을 참조하는 흐름 변수입니다. 참고: 흐름 변수의 경우 프리픽스 'private'이 있어야 합니다. 예를 들면 |
<Source>
<Source>JWS-variable</Source>
존재하는 경우 정책에서 JWS가 인증하기 위해 찾고자 하는 흐름 변수를 지정합니다.
기본값 | request.header.authorization (기본값에 관한 중요한 정보는 위 참고 사항을 확인하세요.) |
Presence | 선택사항 |
유형 | 문자열 |
유효한 값 | 에지 흐름 변수 이름입니다. |
흐름 변수
성공하면 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의 경우 이 변수가 설정되지 않습니다. |
오류 참조
이 섹션에서는 반환되는 오류 코드, 오류 메시지, 정책이 오류를 트리거할 때 Edge에서 설정하는 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.
런타임 오류
이러한 오류는 정책이 실행될 때 발생할 수 있습니다.
오류 코드 | HTTP 상태 | 발생 상황 |
---|---|---|
steps.jws.AlgorithmInTokenNotPresentInConfiguration |
401 | 확인 정책에 알고리즘이 여러 개 있으면 발생합니다. |
steps.jws.AlgorithmMismatch |
401 | 생성 정책에 의해 헤더에 지정된 알고리즘이 확인 정책에서 예상한 알고리즘과 일치하지 않습니다. 지정된 알고리즘이 일치해야 합니다. |
steps.jws.ContentIsNotDetached |
401 | <DetachedContent> 는 JWS에 분리된 콘텐츠 페이로드가 포함되어 있지 않으면 지정됩니다. |
steps.jws.FailedToDecode |
401 | 정책에서 JWS를 디코딩할 수 없습니다. JWS가 손상되었을 수 있습니다. |
steps.jws.InsufficientKeyLength |
401 | HS256 알고리즘의 키가 32바이트 미만인 경우 |
steps.jws.InvalidClaim |
401 | 소유권 주장 누락, 소유권 주장 불일치, 헤더 또는 헤더 불일치 누락 |
steps.jws.InvalidCurve |
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.KeyIdMissing |
401 | 인증 정책은 JWKS를 공개 키의 소스로 사용하지만 서명된 JWS의 헤더에 kid 속성이 포함되어 있지 않습니다. |
steps.jws.KeyParsingFailed |
401 | 주어진 키 정보에서 공개 키를 파싱할 수 없습니다. |
steps.jws.MissingPayload |
401 | JWS 페이로드가 누락되었습니다. |
steps.jws.NoAlgorithmFoundInHeader |
401 | JWS에서 알고리즘 헤더가 생략되면 발생합니다. |
steps.jws.NoMatchingPublicKey |
401 | 확인 정책은 JWKS를 공개 키의 소스로 사용하지만 서명된 JWS의 kid 는 JWKS에 나열되지 않습니다. |
steps.jws.UnhandledCriticalHeader |
401 | crit 헤더의 JWS 확인 정책에서 발견한 헤더는 KnownHeaders 에 나열되지 않습니다. |
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>