클라이언트 애플리케이션이 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 토큰의 "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는 유효한 대상입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis document provides troubleshooting steps for JSON Web Token (JWT) validation failures encountered when using the Extensible Service Proxy (ESP) with an API.\u003c/p\u003e\n"],["\u003cp\u003eCommon JWT validation errors include \u003ccode\u003eBAD_FORMAT\u003c/code\u003e, \u003ccode\u003eTIME_CONSTRAINT_FAILURE\u003c/code\u003e, \u003ccode\u003eUNKNOWN\u003c/code\u003e, \u003ccode\u003eKEY_RETRIEVAL_ERROR\u003c/code\u003e, \u003ccode\u003eIssuer not allowed\u003c/code\u003e, and \u003ccode\u003eAudience not allowed\u003c/code\u003e, each with specific diagnostic instructions.\u003c/p\u003e\n"],["\u003cp\u003eWhen using Cloud Run, make sure the \u003ccode\u003e--allow-unauthenticated\u003c/code\u003e flag is used to prevent Cloud Run from intercepting and verifying the JWT token.\u003c/p\u003e\n"],["\u003cp\u003eThe document emphasizes checking the JWT's structure, ensuring the presence of required fields like \u003ccode\u003e"iss"\u003c/code\u003e, \u003ccode\u003e"sub"\u003c/code\u003e, and \u003ccode\u003e"aud"\u003c/code\u003e, and using \u003ca href=\"https://jwt.io/\"\u003ejwt.io\u003c/a\u003e to decode and examine the JWT's content.\u003c/p\u003e\n"],["\u003cp\u003eCorrect configuration of the \u003ccode\u003ex-google-jwks_uri\u003c/code\u003e, \u003ccode\u003ex-google-issuer\u003c/code\u003e, and \u003ccode\u003ex-google-audiences\u003c/code\u003e fields in the OpenAPI document is critical for successful JWT validation.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting JWT validation\n\nOpenAPI \\| [gRPC](/endpoints/docs/grpc/troubleshoot-jwt \"View this page for the Cloud Endpoints gRPC docs\")\n\n\u003cbr /\u003e\n\nWhen a client application includes a JSON Web Token (JWT) in a request to an\nAPI, the [Extensible Service Proxy (ESP)](/endpoints/docs/openapi/glossary#extensible_service_proxy)\nvalidates the JWT before sending the request to the API\nbackend. This page provides troubleshooting information if the JWT validation\nfails and ESP returns an error in the response to the client. See\n[RFC 7519](https://tools.ietf.org/html/rfc7519) for more information\nabout JWTs.\n**Error: `401: Jwt issuer is not configured`**\n\nThis may happen when deploying ESPv2 in Cloud Run, the flag\n`--allow-unauthenticated` is not used in `gcloud run deploy` command.\nIf the flag is not used, the JWT token is intercepted\nand verified by Cloud Run access control IAM server and not by ESPv2. IAM may use a different issuer than ESPv2.\n**Error: `BAD_FORMAT`**\n\nCheck the\nfollowing:\n\n- Make sure the JWT contains valid JSON.\n- Check that the JWT header has the `\"alg\"` field and is set to one of the following: `\"RS256\"`, `\"HS256\"`, `\"RS384\"`, `\"HS384\"`, `\"RS512\"`, or `\"HS512\"`\n- Check the data type of the following fields (if they are present) in the JWT payload:\n - The `\"iat\"` (issued at), `\"exp\"` (expiration time), and `\"nbf\"`(not before) claims are numbers greater than 0 and not strings.\n - The `\"sub\"` (subject), `\"iss\"` (issuer), and `\"jti\"` (JWT ID) fields are strings.\n - The `\"aud\"` (audience) claim is either a string or an array of strings.\n- Ensure that the following claims are present in the JWT payload: `\"sub\"` (subject), `\"iss\"` (issuer), and `\"aud\"` (audience).\n\nThe following is an example of a decoded JWT token that is valid: \n\n```\n{\n \"alg\": \"RS256\",\n \"typ\": \"JWT\",\n \"kid\": \"42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a\"\n}\n\nPayload:\n{\n \"iss\": \"myservice@myproject.iam.gserviceaccount.com\",\n \"iat\": 1493833746,\n \"aud\": \"myservice.appspot.com\",\n \"exp\": 1493837346,\n \"sub\": \"myservice@myproject.iam.gserviceaccount.com\"\n}\n```\n**Error: `TIME_CONSTRAINT_FAILURE`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and make sure that:\n\n- The `\"exp\"` (expiration time) claim exists.\n- The `\"exp\"` (expiration time) claim value is a date and time in the future. The current date and time must be before the expiration date and time listed in the `\"exp\"` claim.\n- The `\"nbf\"` (not before) claim (If present) is a date and time in the past. The current date and time must be after or equal to the date and time listed in the `\"nbf\"` claim.\n\n**Error: `UNKNOWN`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and ensure that:\n\n- If the `\"iss\"` (issuer) claim is an email address, then the `\"sub\"` (subject) and `\"iss\"` claims should be the same. This is to ensure that for e-mail issuers, the JWT is self issued.\n\n**Error: `KEY_RETRIEVAL_ERROR`**\n\n- Check that the public key URI specified in the [`x-google-jwks_uri`](/endpoints/docs/openapi/openapi-extensions#x-google-jwks_uri) field in your OpenAPI document is correct and valid.\n\n**Error: `Issuer not allowed`**\n\n- Check that the `\"iss\"` (issuer) claim in your JWT token matches the\n [`x-google-issuer`](/endpoints/docs/openapi/openapi-extensions#x-google-issuer)\n field in the `securityDefinitions` section of the security object in your\n OpenAPI document.\n\n- In your OpenAPI document, check that the security object is\n enabled for the API method invoked.\n\nSee the\n[sample openapi.yaml](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/endpoints/getting-started/openapi.yaml)\nfile for an example of how to describe security at the method level by using\n`securityDefinition` and `security` objects.\n\n**Error: `Audience not allowed`**\n\nCompare the `\"aud\"` (audience) claim in a JWT token to see if it matches the\nEndpoints service name, which corresponds to the `host` field in\nthe OpenAPI document.\n\nIf the `\"aud\"` claim and the Endpoints service name are\ndifferent:\n\n- Check that the `\"aud\"` claim in the JWT matches one of the\n `x-google-audiences` values specified in your OpenAPI document.\n\n- Make sure that the `x-google-audiences` and `x-google-issuer` are in the same\n `securityDefinitions` object in your OpenAPI document.\n\nIf the `\"aud\"` claim and the Endpoints service name are the same,\nthe ESP validates the audience and\nignores the\n[`x-google-audiences`](/endpoints/docs/openapi/openapi-extensions#x-google-audiences)\nvalues in your OpenAPI document. For example, if your service name\nis `\"myservice.endpoints.example-project-12345.cloud.goog\"`, then a JWT with\n`\"aud\"` set to `\"myservice.endpoints.example-project-12345.cloud.goog\"` or\n`\"https://myservice.endpoints.example-project-12345.cloud.goog\"` is a valid\naudience."]]
