JWT의 유효성 검증

JWT 유효성 검증 보안 정책을 사용하여 API에 대한 액세스를 허용하기 전에 요청에서 JWT (JSON Web Token) 의 유효성 검증을 사용으로 설정하십시오.

게이트웨이 지원

표 1. 이 정책을 지원하는 게이트웨이 및 해당 정책 버전을 표시하는 테이블
게이트웨이	정책 버전
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0

이 주제에서는 어셈블리 사용자 인터페이스에서 정책을 구성하는 방법에 대해 설명합니다. OpenAPI 소스에서 정책을 구성하는 방법에 대한 세부사항은 jwt-validate를 참조하십시오.

정보

JWT(JSON Web Token)는 두 당사자 사이에서 전송할 청구를 나타내는, 안전한 URL을 사용하는 압축된 방식입니다. JWT 유효성 검증 정책을 사용하면 JWT 유효성 검증을 사용하여 API에 대한 액세스를 보호할 수 있습니다. 예를 들어, 헤더에 JWT를 포함하는 입력 요청이 수신되면 JWT 유효성 검증 정책이 토큰을 추출하고 서명을 확인하고 복호화 (해당되는 경우) 하고 청구의 유효성을 검증합니다. 유효한 경우 청구는 런타임 변수에 배치되며(필요한 경우 후속 사용을 위해), API에 대한 액세스가 허용됩니다. 청구가 유효하지 않으면, 액세스는 거부됩니다.

JWT 유효성 검증 정책에 지정된 모든 청구의 유효성이 검증되지만 JWT에 포함된 모든 청구가 반드시 검증되는 것은 아닙니다. JWT에 있는 모든 청구의 유효성을 검증해야 하는 것은 아니지만 JWT 유효성 검증 정책에 지정된 청구 중 하나가 실패하면 전체 유효성 검증이 실패합니다. 유효성 검증에 성공하면 JWT에 포함된 청구의 전체 세트가 Output Claims 특성에 지정된 런타임 변수에 쓰여집니다. 따라서 후속 조치에서 필요한 경우 이 런타임 변수를 사용하여 JWT에 있는 전체 청구 세트의 유효성을 추가로 검증하도록 허용합니다.

참고:

원래 메시지가 공유되는 비밀 키로 서명된 경우 지정된 암호 오브젝트도 공유되는 비밀 키여야 합니다.
원래 메시지가 개인 키로 서명된 경우 지정된 암호 오브젝트는 암호 인증서(공용 인증서)여야 합니다.
암호 자료는 JWK(JSON Web Key)를 통해 제공할 수 있습니다.
JWK 헤더 매개변수가 JWT의 헤더에 포함된 경우 매개변수는 정책에 지정된 JWK 또는 암호 오브젝트와 일치해야 합니다. 그렇지 않으면 JWT 유효성 검증에 실패합니다.
암호 오브젝트 및 JWK 모두 지정하면 JWT의 암호화 및 확인에 암호 오브젝트를 사용합니다.
DataPower API Gateway 의 JWT 유효성 검증 조치는 단일 JWK 또는 JWK 세트를 사용하여 JWT를 확인할 수 있습니다.

전제조건

다음과 같은 전제조건이 적용됩니다.

IBM® DataPower V7.5 (AO (Application Optimization) 옵션 포함).
IBM API Connect 하나 이상의 암호화 객체(crypto objects)를 사용하는 경우, 그것들은 DataPower 기기. 암호 오브젝트는 JWT 컨텐츠에 서명하거나 서명을 확인하는 데 필요한 공유되는 비밀 키 또는 공용 인증서를 참조해야 합니다.
JWK (JSON Web Key) 또는 JWK 세트가 사용되는 경우 런타임 변수에서 참조해야 합니다.

특성

다음 표에서는 정책 특성을 나열하고, 특성이 필수인지 여부를 표시하며, 올바른 입력 값과 기본 입력 값을 지정하고, 값의 데이터 유형을 지정합니다.

표 2. JWT 유효성 검증 정책 특성
특성 레이블	필수	설명	데이터 유형
제목	예	해당 정책의 제목입니다. 기본값은 `jwt-validate`입니다.	문자열
설명	아니오	정책의 설명입니다.	문자열
JWT(JSON Web Token)	예	유효성 검증할 JWT가 포함된 컨텍스트 또는 런타임 변수입니다. 기본값은 `request.headers.authorization`입니다. 그러나 설정하지 않을 경우 정책은 기본적으로 `request.headers.authorization` 위치에서 JWT를 검색합니다. 주: 권한 부여 헤더의 형식은 다음과 같아야 합니다. `"Authorization: Bearer jwt-token"` 여기서 `jwt-token`은 인코딩된 JWT입니다.	문자열
출력 청구	예	JWT에 포함된 전체 청구 세트가 지정된 런타임 변수입니다. 기본값은 `decoded.claims`입니다.	문자열
발행자 청구	아니오	발행자 (iss) 청구의 유효성을 검증하는 데 사용할 Perl Compatible Regular Expressions (PCRE) .	문자열
대상 청구	아니오	대상(aud) 청구를 유효성 검증하는 데 사용할 PCRE입니다.	문자열
암호 오브젝트 복호화	아니오	청구를 디코딩하는 데 사용할 암호화 오브젝트 (공유 키 또는 인증서) 입니다.^¹	문자열
암호 JWK 변수 이름 복호화	아니오	JWT를 복호화하는 데 사용할 JWK가 포함된 런타임 변수입니다.^¹	문자열
암호 오브젝트 확인	아니오	서명을 확인하는 데 사용할 암호화 오브젝트 (공유 키 또는 인증서) 입니다.^²	문자열
암호 JWK 변수 이름 확인	아니오	서명을 확인하는 데 사용할 JWK 또는 JWK 세트가 포함된 런타임 변수입니다.^²	문자열

예

- jwt-validate:
    version: 1.0.0
    title: jwt-validate
    jwt: request.headers.authorization
    output-claims: decoded.claims
    iss-claim: "'^data.*'"
    aud-claim: "'^id.*'"
    jwe-crypto: jweCryptoObjectName
    jwe-jwk: jwe.jwk
    jws-crypto: jwsCryptoObjectName
    jws-jwk: jws.jwk

오류

정책 실행 중에 다음 오류를 예외 처리할 수 있습니다.

RuntimeError - 정책 실행 중에 발생하는 모든 오류를 캡처하는 일반 오류입니다. 유효성 검증에 실패한 경우 기본 JOSE 모듈에서 수신된 자세한 오류 메시지는 오류 메시지로 기본 시스템 로그에 기록됩니다. 이 자세한 오류 메시지는 런타임 변수 jwt-validate.error-message에도 지정되므로, 발견을 통해 검색할 수 있습니다.

HTTP 캐치가 설정되지 않은 경우, 유효성 검사 실패 시 Validate JWT 정책은 500 Invalid-JWT-Validate 실패 코드를 반환합니다. 기본 JOSE 모듈에서 자세한 오류 메시지는 시스템 로그에서 찾을 수 있습니다.

주의: API에 대한 고객 중 하나의 실패를 해결하는 API 개발자인 경우, 고객에게 로그 메시지의 정확한 컨텐츠를 보내기 전에 보안 위험을 고려하십시오. 고객에게 메시지에 대해 일반적인 정보만 전송하여 로그 메시지에서 수신하는 정보를 기반으로 누군가가 공격할 가능성을 피할 수 있습니다.

예를 들어, jwt-validate를 참조하십시오.

¹ JWK및 암호 오브젝트는 모두 JWT를 복호화하는 데 필요한 암호화 데이터를 제공하는 올바른 방법입니다. 그러나 두 데이터 유형을 지정하면 암호 오브젝트만 사용됩니다. IBM API Connect 하나 이상의 암호화 객체(crypto objects)를 사용하는 경우, 그것들은 DataPower 기기. 암호 오브젝트는 JWT 컨텐츠에 서명하거나 서명을 확인하는 데 필요한 공유되는 비밀 키 또는 공용 인증서를 참조해야 합니다.

² JWK 또는 JWK 세트 및 암호 오브젝트는 모두 JWT를 확인하는 데 필요한 암호화 데이터를 제공하는 올바른 방법입니다. 그러나 두 데이터 유형을 지정하면 암호 오브젝트만 사용됩니다.