{"record":{"id":"97e505896433075f","repo":"Tencent/WeKnora","slug":"token-lifetime-exceeds-s","errorCode":null,"errorMessage":"token lifetime exceeds %s","messagePattern":"token lifetime exceeds (.+?)","errorType":"validation","errorClass":null,"httpStatus":401,"severity":"error","filePath":"internal/middleware/auth.go","lineNumber":643,"sourceCode":"\t)\n\ttoken, err := parser.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {\n\t\tif _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {\n\t\t\treturn nil, fmt.Errorf(\"unexpected signing method: %v\", token.Header[\"alg\"])\n\t\t}\n\t\treturn []byte(secret), nil\n\t})\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif token == nil || !token.Valid {\n\t\treturn \"\", errors.New(\"invalid external user token\")\n\t}\n\texp, err := claims.GetExpirationTime()\n\tif err != nil || exp == nil {\n\t\treturn \"\", errors.New(\"missing expiration\")\n\t}\n\tif time.Until(exp.Time) > maxExternalUserTokenTTL {\n\t\treturn \"\", fmt.Errorf(\"token lifetime exceeds %s\", maxExternalUserTokenTTL)\n\t}\n\tif nbf, nbfErr := claims.GetNotBefore(); nbfErr == nil && nbf != nil && time.Now().Before(nbf.Time) {\n\t\treturn \"\", errors.New(\"token not yet valid\")\n\t}\n\tif got := principalTenantIDFromClaims(claims); got != tenantID {\n\t\treturn \"\", fmt.Errorf(\"workspace mismatch: got %d want %d\", got, tenantID)\n\t}\n\tsub, _ := claims[\"sub\"].(string)\n\tsub = strings.TrimSpace(sub)\n\tif sub == \"\" {\n\t\treturn \"\", errors.New(\"missing subject\")\n\t}\n\treturn sub, nil\n}\n\nfunc validateExternalUserID(id string) error {\n\tid = strings.TrimSpace(id)\n\tif id == \"\" {","sourceCodeStart":625,"sourceCodeEnd":661,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/middleware/auth.go#L625-L661","documentation":"verifyExternalUserJWT in internal/middleware/auth.go:643 rejects tokens whose time until expiration exceeds maxExternalUserTokenTTL. Even correctly signed, unexpired tokens are refused if their total remaining lifetime is too long, capping how long a stolen token remains usable.","triggerScenarios":"A validly signed HS256 token for the right tenant/audience has exp further in the future than maxExternalUserTokenTTL; resolveAPIPrincipal surfaces it wrapped as errInvalidExternalUserToken.","commonSituations":"Issuer configures 30-day token lifetimes while the server enforces a short TTL; long-lived \"API tokens\" reused as external user tokens.","solutions":["Shorten the token lifetime at issuance to at most maxExternalUserTokenTTL.","Implement token refresh instead of long-lived tokens.","If the business case truly needs longer TTLs, adjust maxExternalUserTokenTTL deliberately (security trade-off)."],"exampleFix":"// before\nclaims[\"exp\"] = time.Now().Add(720 * time.Hour).Unix() // exceeds TTL\n// after\nclaims[\"exp\"] = time.Now().Add(10 * time.Minute).Unix() // within maxExternalUserTokenTTL","handlingStrategy":"validation","validationCode":"exp := time.Now().Add(lifetime)\nif lifetime > maxExternalUserTokenTTL { // shorten before signing\n    lifetime = maxExternalUserTokenTTL\n}","typeGuard":null,"tryCatchPattern":"if err != nil {\n    if strings.Contains(err.Error(), \"token lifetime exceeds\") {\n        // mint a shorter-lived token\n    }\n}","preventionTips":["Default to short-lived tokens (minutes) plus refresh flows.","Align issuer TTL config with server maxExternalUserTokenTTL.","Unit-test issued tokens against the server TTL before rollout."],"tags":["jwt","security","expiration"],"backgroundTag":"jwt-token-lifetime-exceeded","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}