Wenn eine Clientanwendung einer API-Anfrage ein JSON Web Token (JWT) hinzufügt, validiert der Extensible Service Proxy (ESP) das JWT, bevor die Anfrage an das API-Backend gesendet wird. Auf dieser Seite finden Sie Informationen zur Fehlerbehebung, falls die JWT-Validierung fehlschlägt und der ESP in der Antwort an den Client einen Fehler zurückgibt. Weitere Informationen zu JWTs finden Sie in RFC 7519.
Fehler: 401: Jwt issuer is not configured
Dies kann passieren, wenn Sie ESPv2 in Cloud Run bereitstellen und das Flag --allow-unauthenticated nicht im Befehl gcloud run deploy verwenden.
Wenn das Flag nicht verwendet wird, wird das JWT-Token abgefangen und von Cloud Run <a=" docs=""managing-access"="" run="" secure=""> Zugriffssteuerung-IAM Server überprüft und nicht von ESPv2. IAM verwendet möglicherweise einen anderen Aussteller als ESPv2.
</a=">
Fehler: BAD_FORMAT
Prüfen Sie Folgendes:
Achten Sie darauf, dass das JWT gültigen JSON-Code enthält.
Prüfen Sie, ob im JWT-Header das Feld "alg" enthalten und dafür einer der folgenden Werte festgelegt ist: "RS256", "HS256", "RS384", "HS384", "RS512" oder "HS512".
Prüfen Sie den Datentyp der folgenden Felder (falls vorhanden) in der JWT-Nutzlast:
Die Anforderungen "iat" (issued at), "exp" (expiration time) und "nbf" (not before) sind Zahlen größer als 0 und keine Strings.
Die Felder "sub" (subject), "iss" (issuer) und "jti" (JWT ID) sind Strings.
Die Anforderung "aud" (audience) ist entweder ein String oder ein Array mit Strings.
Achten Sie darauf, dass die folgenden Anforderungen in der JWT-Nutzlast vorhanden sind: "sub" (subject), "iss" (issuer) und "aud" (audience).
Das folgende Beispiel enthält ein decodiertes gültiges JWT:
Decodieren Sie das JWT mit jwt.io und stellen Sie Folgendes sicher:
Die Anforderung "exp" (expiration time) ist vorhanden.
Die Anforderung "exp" (expiration time) enthält einen Datum/Uhrzeit-Wert in der Zukunft. Das aktuelle Datum und die aktuelle Uhrzeit müssen vor dem Ablaufdatum und der Ablaufzeit liegen, die in der Anforderung "exp" angegeben sind.
Die Anforderung "nbf" (not before) ist, sofern vorhanden, ein Datum und eine Uhrzeit in der Vergangenheit. Das aktuelle Datum und die aktuelle Uhrzeit müssen nach dem Datum und der Uhrzeit liegen, die in der Anforderung "nbf" angegeben sind, oder diesen Werten entsprechen.
Fehler: UNKNOWN
Decodieren Sie das JWT mit jwt.io und gewährleisten Sie Folgendes:
Wenn die Anforderung "iss" (issuer) eine E-Mail-Adresse ist, müssen die Anforderungen "sub" (subject) und "iss" identisch sein.
Damit wird bei E-Mail-Ausstellern sichergestellt, dass es sich um ein selbst ausgestelltes JWT handelt.
Fehler: KEY_RETRIEVAL_ERROR
Prüfen Sie, ob der URI des öffentlichen Schlüssels, der im Feld jwks_uri im Abschnitt authentication: providers der gRPC-.yaml-Konfigurationsdatei angegeben ist, korrekt und gültig ist.
Fehler: Issuer not allowed
Prüfen Sie, ob die Anforderung "iss" (issuer) im JWT mit dem Feld issuer im Abschnitt authentication: providers Ihrer gRPC-.yaml-Konfigurationsdatei übereinstimmt.
Fehler: Audience not allowed
Wenn die Anforderung "aud" (audience) in einem JWT mit dem Endpoints-Dienstnamen übereinstimmt, validiert der ESP die Zielgruppe und ignoriert die Werte von audiences in Ihrer gRPC-.yamlKonfigurationsdatei. Wenn Ihr Dienstname beispielsweise "myservice.endpoints.example-project-12345.cloud.goog" lautet, ist ein JWT mit "aud" für "myservice.endpoints.example-project-12345.cloud.goog" oder "https://myservice.endpoints.example-project-12345.cloud.goog" eine gültige Zielgruppe.
Wenn die Anforderung "aud" nicht mit dem Endpoints-Dienstnamen identisch ist, gehen Sie so vor:
Prüfen Sie, ob die Anforderung "aud" im JWT mit einem der audiences-Werte übereinstimmt, die im Abschnitt authentication: providers der gRPC-.yaml-Konfigurationsdatei angegeben sind.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThe Extensible Service Proxy (ESP) validates JSON Web Tokens (JWTs) before forwarding requests to the API backend, and this page offers troubleshooting for JWT validation failures.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eBAD_FORMAT\u003c/code\u003e error indicates potential issues with the JWT's structure, such as invalid JSON, incorrect \u003ccode\u003e"alg"\u003c/code\u003e field values, or incorrect data types for fields like \u003ccode\u003e"iat"\u003c/code\u003e, \u003ccode\u003e"exp"\u003c/code\u003e, \u003ccode\u003e"nbf"\u003c/code\u003e, \u003ccode\u003e"sub"\u003c/code\u003e, \u003ccode\u003e"iss"\u003c/code\u003e, \u003ccode\u003e"jti"\u003c/code\u003e, and \u003ccode\u003e"aud"\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eTIME_CONSTRAINT_FAILURE\u003c/code\u003e error means that either the \u003ccode\u003e"exp"\u003c/code\u003e (expiration time) claim is missing or invalid, or the \u003ccode\u003e"nbf"\u003c/code\u003e (not before) claim, if present, indicates that the token is not yet valid.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eKEY_RETRIEVAL_ERROR\u003c/code\u003e error suggests a problem with the \u003ccode\u003ejwks_uri\u003c/code\u003e specified in the gRPC configuration, which should be checked for accuracy.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eAudience not allowed\u003c/code\u003e error occurs when the \u003ccode\u003e"aud"\u003c/code\u003e claim in the JWT does not match either the Endpoints service name or the \u003ccode\u003eaudiences\u003c/code\u003e values specified in the gRPC configuration.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting JWT validation\n\n[OpenAPI](/endpoints/docs/openapi/troubleshoot-jwt \"View this page for the Cloud Endpoints OpenAPI docs\") \\| gRPC\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 [`jwks_uri`](/endpoints/docs/grpc/service-account-authentication#set_up_authentication_in_the_grpc_api_configuration) field in the `authentication: providers` section of your gRPC `.yaml` configuration file is correct and valid.\n\n**Error: `Issuer not allowed`**\n\n- Check that the `\"iss\"` (issuer) claim in your JWT token matches the [`issuer`](/endpoints/docs/grpc/service-account-authentication#set_up_authentication_in_the_grpc_api_configuration) field in the `authentication: providers` section of your gRPC `.yaml` configuration file.\n\n**Error: `Audience not allowed`**\n\nIf the `\"aud\"` (audience) claim in a JWT token matches the Endpoints\nservice name, then the ESP validates the audience\nand ignores the `audiences` values in your gRPC `.yaml` configuration file. For\nexample, if your service name is\n`\"myservice.endpoints.example-project-12345.cloud.goog\"`,\nthen a JWT with `\"aud\"` set to\n`\"myservice.endpoints.example-project-12345.cloud.goog\"`\nor `\"https://myservice.endpoints.example-project-12345.cloud.goog\"` is a valid\naudience.\n\nIf the `\"aud\"` claim isn't the same as the Endpoints service\nname:\n\n- Check that the `\"aud\"` claim in the JWT matches one of the `audiences` values specified in the `authentication: providers` section of your gRPC `.yaml` configuration file."]]
