JWT 검증 문제해결

OpenAPI | gRPC

클라이언트 애플리케이션이 API로 보내는 요청에 JSON 웹 토큰(JWT)을 포함하는 경우 확장 가능 서비스 프록시(ESP)는 API 백엔드에 요청을 보내기 전에 JWT를 검증합니다. 이 페이지에서는 JWT 검증이 실패하고 ESP가 클라이언트에 대한 응답에 오류를 반환하는 경우의 문제해결 정보를 제공합니다. JWT에 대한 자세한 내용은 RFC 7519를 참조하세요.

오류: 401: Jwt issuer is not configured

이는 Cloud Run에서 ESPv2를 배포할 때 발생할 수 있으며 gcloud run deploy 명령어에서 --allow-unauthenticated 플래그가 사용되지 않습니다. 이 플래그를 사용하지 않으면 ESPv2가 아닌 Cloud Run <a=" docs="" managing-access"="" run="" securing=""> 액세스 제어 IAM 서버에서 JWT 토큰을 가로채고 확인합니다. IAM은 ESPv2와 다른 발급기관을 사용할 수 있습니다. </a=">

오류: BAD_FORMAT

다음을 확인해 보세요.

JWT에 유효한 JSON이 들어 있는지 확인합니다.
JWT 헤더에 "alg" 필드가 있으며 "RS256", "HS256", "RS384", "HS384", "RS512" 또는 "HS512" 중 하나로 설정되어 있는지 확인합니다.
JWT 페이로드에서 다음 필드(있는 경우)의 데이터 유형을 확인합니다.

"iat"(발급 시점), "exp"(만료 시간), "nbf"(이전 아님) 클레임은 0보다 큰 숫자이며 문자열이 아닙니다.
"sub"(제목), "iss"(발급자), "jti"(JWT ID) 필드는 문자열입니다.
"aud"(대상) 클레임은 문자열 또는 문자열 배열입니다.

JWT 페이로드에 "sub"(제목), "iss"(발급자), "aud"(대상) 클레임이 있는지 확인합니다.

다음은 유효한 디코딩된 JWT 토큰의 예시입니다.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a"
}

Payload:
{
  "iss": "myservice@myproject.iam.gserviceaccount.com",
  "iat": 1493833746,
  "aud": "myservice.appspot.com",
  "exp": 1493837346,
  "sub": "myservice@myproject.iam.gserviceaccount.com"
}

오류: TIME_CONSTRAINT_FAILURE

jwt.io를 사용하여 JWT를 디코딩하고 다음을 확인합니다.

"exp"(만료 시간) 클레임이 있습니다.
"exp"(만료 시간) 클레임 값은 미래의 날짜와 시간입니다. 현재 날짜와 시간은 다음 "exp" 클레임에 나열된 만료일 및 시간보다 이전이어야 합니다.
"nbf"(이전 아님) 클레임은 과거의 날짜와 시간입니다. 현재 날짜와 시간은 "nbf" 클레임에 나열된 날짜 및 시간과 같거나 그 이후여야 합니다.

오류: UNKNOWN

jwt.io를 사용하여 JWT를 디코딩하고 다음을 확인합니다.

"iss"(발급자) 클레임이 이메일 주소인 경우 "sub"(제목) 및 "iss" 클레임은 동일해야 합니다. 이는 이메일 발급기관의 경우 JWT가 자체 발급된 것임을 확인하기 위한 것입니다.

오류: KEY_RETRIEVAL_ERROR

OpenAPI 문서의 x-google-jwks_uri 필드에 지정된 공개 키 URI가 올바르고 유효한지 확인합니다.

오류: Issuer not allowed

JWT 토큰의 "iss"(발급기관) 클레임이 OpenAPI 문서에 있는 보안 객체의 securityDefinitions 섹션에 있는 x-google-issuer 필드와 일치하는지 확인합니다.
OpenAPI 문서에서 호출된 API 메소드에 대해 보안 객체가 사용 설정되어 있는지 확인합니다.

securityDefinition과 security 객체를 사용하여 메서드 수준으로 보안을 기술하는 방법의 예시는 sample openapi.yaml 파일을 참조하세요.

오류: Audience not allowed

JWT 토큰의 "aud"(대상) 클레임을 비교하여 OpenAPI 문서의 host 필드에 해당하는 Endpoints 서비스 이름과 일치하는지 확인합니다.

"aud" 클레임과 Endpoints 서비스 이름이 다른 경우:

JWT의 "aud" 클레임이 OpenAPI 문서에 지정된 x-google-audiences 값 중 하나와 일치하는지 확인합니다.
x-google-audiences와 x-google-issuer가 OpenAPI 문서의 securityDefinitions 객체와 동일한지 확인합니다.

"aud" 클레임과 Endpoints 서비스 이름이 동일하면 ESP는 대상을 검증하고 OpenAPI 문서의 x-google-audiences 값을 무시합니다. 예를 들어 서비스 이름이 "myservice.endpoints.example-project-12345.cloud.goog"인 경우 "aud"가 "myservice.endpoints.example-project-12345.cloud.goog" 또는 "https://myservice.endpoints.example-project-12345.cloud.goog"로 설정된 JWT는 유효한 대상입니다.