이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
이 주제에서는 JWT(JSON 웹 토큰) 및 JWS(JSON 웹 서명)와 Apigee 프록시 개발자가 관심을 가질 수 있는 Apigee JWS/JWT 정책에 대한 일반적인 정보를 제공합니다.
소개
일반적으로 JWS와 JWT 모두 연결된 애플리케이션 간의 클레임 또는 어설션을 공유하는 데 사용됩니다. JWS/JWT 정책은 Apigee API 프록시를 사용하여 다음을 수행할 수 있습니다.
후자의 두 경우에서는 정책이 추가 정책 또는 백엔드 서비스 자체를 허용하는 변수를 설정하여 확인된 클레임을 검사하고 이러한 클레임을 바탕으로 결정을 내립니다.
JWS/JWT 확인 정책을 사용하면 잘못된 JWS/JWT가 거부되고 오류 조건이 발생합니다. 마찬가지로, JWS/JWT 디코딩 정책을 사용하는 경우 잘못된 JWS/JWT로 오류 조건이 발생합니다.
동영상
JWT에 대한 간단한 소개 동영상을 시청하세요. 이 동영상은 JWT를 생성하는 데만 해당하지만 대부분의 개념은 JWS와 동일합니다.
JWT 구조에 대해 자세히 알아볼 수 있는 짧은 동영상입니다.
사용 사례
JWS/JWT 정책을 사용하여 다음을 수행할 수 있습니다.
- Apigee 프록시의 프록시 또는 대상 엔드포인트 측에서 새 JWS/JWT를 생성합니다. 예를 들어 JWS/JWT를 생성하고 클라이언트에 반환하는 프록시 요청 흐름을 만들 수 있습니다. 또는 대상 요청 흐름에서 JWS/JWT를 생성하고 프록시로 전송되는 요청에 연결하도록 프록시를 설계할 수 있습니다. 그런 다음 백엔드 서비스가 추가 보안 처리를 적용할 수 있도록 이러한 클레임을 사용할 수 있습니다.
- 수신 클라이언트 요청, 대상 서비스 응답, 서비스 콜아웃 정책 응답 또는 다른 소스에서 가져온 JWS/JWT에서 클레임을 확인하고 추출합니다. Apigee는 RSA 또는 HMAC 알고리즘을 사용하여 JWS/JWT를 제3자가 생성했는지 아니면 Apigee 자체에서 생성했는지 JWS/JWT의 서명을 확인합니다.
- JWS/JWT를 디코딩합니다. 디코딩은 JWS/JWT를 확인하기 전에 JWS/JWT 내에서 클레임(JWT) 또는 헤더(JWS/JWT)의 값을 알아야 하는 경우 JWS/JWT 확인 정책과 함께 사용할 때 가장 유용합니다.
JWS/JWT를 구성하는 요소
서명된 JWS/JWT는 헤더, 페이로드, 서명 등 마침표로 구분된 세 부분으로 정보를 인코딩합니다.
header.payload.signature
- JWS/JWT 생성 정책은 세 부분을 모두 만듭니다.
- JWS/JWT 확인 정책은 세 부분을 모두 검사합니다.
- JWS/JWT 디코딩 정책은 헤더 및 페이로드만 검사합니다.
JWS는 JWS에서 페이로드를 생략하는 분리 형식도 지원합니다.
header..signature
분리 JWS를 사용하면 페이로드가 JWS와 별도로 전송됩니다. JWS 확인 정책의 <DetachedContent> 요소를 사용하여 인코딩되지 않은 원시 JWS 페이로드를 지정합니다.
그런 다음 JWS 확인 정책은 JWS의 헤더 및 서명과 <DetachedContent> 요소에 지정된 페이로드를 사용하여 JWS를 확인합니다.
토큰과 인코딩 및 서명 방법에 대해 자세히 알아보려면 다음을 참조하세요.
- JWT: IETF RFC7519
- JWS: IETF RFC7515
JWS와 JWT 간 차이점
JWT 또는 JWS를 사용하여 연결된 애플리케이션 간에 클레임 또는 어설션을 공유할 수 있습니다. 이 둘의 주요 차이점은 페이로드를 나타냅니다.
- JWT
- 페이로드는 항상 JSON 객체입니다.
- 페이로드는 항상 JWT에 연결됩니다.
- 토큰의
typ헤더는 항상JWT로 설정됩니다.
- JWS
- 페이로드는 JSON 객체, 바이트 스트림, 옥텟 스트림 등의 모든 형식으로 표현될 수 있습니다.
- 페이로드는 JWS에 연결할 필요가 없습니다.
JWT 형식은 항상 JSON 객체를 사용하여 페이로드를 나타내기 때문에 Apigee JWT 생성 및 JWT 확인 정책에는 기본적으로 aud, iss, sub 등과 같은 일반적인 등록된 클레임 이름을 처리하는 기본 지원 기능이 있습니다. 즉, JWT 생성 정책의 요소를 사용하여 페이로드에 이러한 클레임을 설정하고 JWT 확인 정책의 요소를 사용하여 값을 확인할 수 있습니다. 자세한 내용은 JWT 사양의 등록된 클레임 이름 섹션을 참조하세요.
JWT 생성 정책은 특정한 등록된 클레임 이름을 지원할 뿐만 아니라 JWT에 임의 이름의 클레임 추가를 직접 지원합니다. 각 클레임은 단순한 이름/값 쌍이며 값은 숫자, 부울, 문자열, 맵, 배열 유형일 수 있습니다.
JWS는 페이로드의 모든 데이터 표현을 사용할 수 있으므로 페이로드에 클레임을 추가할 수 없습니다. JWS 생성 정책은 JWS 헤더에 임의 이름의 클레임 추가를 지원합니다. 또한 JWS 정책은 JWS가 페이로드를 생략하는 분리 페이로드를 지원합니다. 분리 페이로드를 사용하면 JWS와 페이로드를 별도로 전송할 수 있으며 여러 보안 표준에 필요합니다.
서명 알고리즘 정보
JWS/JWT 확인 및 JWS/JWT 생성 정책은 비트 강도가 256, 384, 512인 SHA2 체크섬을 사용하여 RSA, RSASSA-PSS, ECDSA, HMAC 알고리즘을 지원합니다. JWS/JWT 디코딩 정책은 JWS/JWT 서명에 사용된 알고리즘과 관계없이 작동합니다.
HMAC 알고리즘
HMAC 알고리즘은 서명(JWS/JWT 서명이라고도 함)을 만들고 서명을 확인하기 위해 보안 비밀 키라고 하는 공유 비밀번호를 사용합니다.
보안 비밀 키의 최소 길이는 알고리즘의 비트 강도에 따라 다릅니다.
- HS256: 최소 32바이트 키 길이
- HS386: 최소 48바이트 키 길이
- HS512: 최소 64바이트 키 길이
RSA 알고리즘
RSA 알고리즘은 암호화 서명에 공개 키/비공개 키 쌍을 사용합니다. RSA 서명을 사용하면 서명 당사자는 RSA 비공개 키를 사용하여 JWS/JWT에 서명하고 확인 당사자는 일치하는 RSA 공개 키를 사용하여 JWS/JWT의 서명을 확인합니다. 키에는 크기 요구사항이 없습니다.
RSASSA-PSS 알고리즘
RSASSA-PSS 알고리즘은 RSA 알고리즘에 대한 업데이트입니다. RSS와 마찬가지로 RSASSA-PSS는 암호화 서명에 RSA 공개 키/비공개 키 쌍을 사용합니다. 키 형식은 RSS와 동일합니다. 서명 당사자는 비공개 키를 사용하여 JWS/JWT에 서명하고 확인 당사자는 일치하는 공개 키를 사용하여 JWS/JWT의 서명을 확인합니다. 키에는 크기 요구사항이 없습니다.
ECDSA 알고리즘
ECDSA(타원 곡선 디지털 서명 알고리즘) 알고리즘은 P-256, P-384, P-521 곡선이 있는 타원 곡선 암호 알고리즘입니다. ECDSA 알고리즘을 사용하는 경우 알고리즘은 지정해야 하는 공개 및 비공개 키의 유형을 결정합니다.
| 알고리즘 | 곡선 | 키 요구사항 |
|---|---|---|
| ES256 | P-256 | P-256 곡선에서 생성된 키(secp256r1 또는 prime256v1이라고도 함) |
| ES384 | P-384 | P-384 곡선에서 생성된 키(secp384r1이라고도 함) |
| ES512 | P-521 | P-521 곡선에서 생성된 키(secp521r1이라고도 함) |
키 암호화 알고리즘
JWS/JWT 정책은 OpenSSL에서 지원하는 모든 키 암호화 알고리즘을 지원합니다.
JSON 웹 키 세트(JWKS)를 사용하여 JWS/JWT 인증
서명된 JWS/JWT를 확인할 때는 토큰 서명에 사용된 비공개 키와 연결된 공개 키를 제공해야 합니다. JWS/JWT 확인 정책에 공개 키를 제공하기 위한 두 가지 옵션이 있습니다.
- 실제 공개 키 값(일반적으로 흐름 변수에 제공됨) 사용
- JWKS로 래핑된 공개 키 사용
JWKS 정보
JWKS는 JSON 웹 키(JWK) 세트를 나타내는 JSON 구조입니다. JWK는 암호화 키를 나타내는 JSON 데이터 구조입니다. JWK와 JWKS는 RFC7517에 설명되어 있습니다. JKWS 예시는 부록 A. JSON 웹 키 세트 예시를 참조하세요.
JWKS 구조
RFC7517은 RSA 또는 EC와 같은 각 키 유형의 JWKS 키 요소를 설명합니다. 예를 들어 키 유형에 따라 이러한 매개변수는 다음을 포함할 수 있습니다.
- kty - 키 유형(예:
RSA또는EC) - kid(키 ID) - 임의의 값(키 세트 내에서 중복 없음). 인바운드 JWT가 JWKS 세트에 있는 키 ID를 보유하는 경우, 정책은 올바른 공개 키를 사용하여 JWS/JWT 서명을 인증합니다.
다음은 선택적 요소와 해당 값의 예시입니다.
- alg: 키 알고리즘. JWS/JWT의 서명 알고리즘과 일치해야 합니다.
- use: 존재하는 경우
sig여야 함.
다음 JWKS에는 필수 요소와 값이 포함되어 있으며 Apigee(https://www.googleapis.com/oauth2/v3/certs)에서 유효합니다.
{
"keys":[
{
"kty":"RSA",
"alg":"RS256",
"use":"sig",
"kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
"n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
"e":"AQAB"
},
{
"kty":"EC",
"alg":"ES256",
"use":"enc",
"kid":"k05TUSt7-V7KDjCq0_N"
"crv":"P-256",
"x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
"y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
}
]
}
JWKS를 사용하도록 프록시 설계
발급기관에서 JWS/JWT를 가져올 때 발급기관은 JWS/JWT 헤더에 키 ID (또는 하위 요소)를 삽입하는 경우가 많습니다. 이 키는 JWS/JWT 수신자에게 서명된 JWS/JWT에서 서명을 확인하는 데 필요한 공개 키 또는 보안 비밀 키를 찾는 방법을 알려줍니다.
예를 들어 발급기관이 비공개 키로 JWT에 서명한다고 가정합니다. '키 ID'는 JWT를 확인하는 데 사용할 일치하는 공개 키를 식별합니다. 공개 키 목록은 일반적으로 잘 알려진 엔드포인트(예: https://www.googleapis.com/oauth2/v3/certs)에서 사용할 수 있습니다.
다음은 Apigee(또는 JWKS와 함께 작동하는 모든 플랫폼)가 JWKS가 있는 JWS/JWT로 작동하기 위해 수행해야 하는 기본 순서입니다.
- JWS/JWT 헤더를 검사하여 키 ID(kid)를 찾습니다.
- JWS/JWT 헤더를 검사하여 RS256과 같은 서명 알고리즘(alg)을 찾습니다.
- 지정된 발급기관에 대해 잘 알려진 엔드포인트의 JWKS에서 키 및 ID 목록을 검색합니다.
- JWKS 키가 알고리즘을 지정하는 경우 JWS/JWT 헤더에 명시된 키 ID와 일치하는 알고리즘을 사용하여 키 목록에서 공개 키를 추출합니다.
- 이 공개 키를 사용하여 JWS/JWT의 서명을 확인합니다.
Apigee API 프록시 개발자는 JWS/JWT 확인을 수행하려면 다음을 수행해야 합니다.
- 지정된 발급기관에 대해 잘 알려진 엔드포인트에서 키 및 ID 목록을 검색합니다. 이 단계에서 서비스 콜아웃 정책을 사용할 수 있습니다.
- JWS/JWT 확인 정책에서는
<Source>요소에 JWS/JWT 위치를 지정하고<PublicKey/JWKS>요소에 JWKS 페이로드를 지정합니다. 예를 들어 JWT 확인 정책의 경우 다음과 같습니다.<VerifyJWT name="JWT-Verify-RS256"> <Algorithm>RS256</Algorithm> <Source>json.jwt</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> <Subject>apigee-seattle-hatrack-montage</Subject> <Issuer>urn://apigee-edge-JWT-policy-test</Issuer> <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> </VerifyJWT>
JWT 확인 정책은 그 외 모든 작업을 수행합니다.
- JWT에서 어설션된 키 ID(kid)와 일치하는 키 ID가 있는 키가 JWKS에 없으면 JWT 확인 정책에 따라 오류가 발생하고 JWT가 검증되지 않습니다.
- 인바운드 JWT가 헤더에 키 ID(kid)를 보유하지 않으면 이 keyid-to-verification-key의 매핑이 불가능합니다.
프록시 디자이너는 사용할 키를 결정할 책임이 있습니다. 경우에 따라 고정된 하드 코딩 키일 수 있습니다.