JWT 검증 문제해결

클라이언트 애플리케이션이 API로 보내는 요청에 JSON 웹 토큰(JWT)을 포함하는 경우 Extensible Service Proxy(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는 유효한 대상입니다.