{"record":{"id":"c3585b9b4b2c72ec","repo":"Tencent/WeKnora","slug":"empty-external-user-id","errorCode":null,"errorMessage":"empty external user id","messagePattern":"empty external user id","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/middleware/auth.go","lineNumber":662,"sourceCode":"\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 == \"\" {\n\t\treturn errors.New(\"empty external user id\")\n\t}\n\tif len(id) > maxExternalUserIDLen {\n\t\treturn fmt.Errorf(\"external user id too long (max %d)\", maxExternalUserIDLen)\n\t}\n\tfor _, r := range id {\n\t\tif r < 0x20 || r == 0x7f {\n\t\t\treturn errors.New(\"external user id contains invalid characters\")\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc apiPrincipalAuthErrorMessage(err error) string {\n\tswitch {\n\tcase errors.Is(err, errMissingDirectHeader):\n\t\treturn \"Unauthorized: missing external user id header\"\n\tcase errors.Is(err, errInvalidExternalUserID):\n\t\treturn \"Unauthorized: invalid external user id\"","sourceCodeStart":644,"sourceCodeEnd":680,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/middleware/auth.go#L644-L680","documentation":"validateExternalUserID performs post-JWT sanity checks on the external user identifier extracted from the token. It rejects an empty (after trimming) ID because a principal without an ID cannot be persisted or authorized. This guards against tokens whose sub passed a whitespace-only trim earlier or IDs supplied through alternate lookup paths.","triggerScenarios":"resolveAPIPrincipal calling validateExternalUserID with an ID that is empty after TrimSpace — e.g. sub claim containing only spaces, or an empty ID passed when resolving a principal by explicit external user ID.","commonSituations":"IdP that issues blank sub values; callers extracting the ID from a header/query param that was not sent; data migration bugs where user records lack the external ID field.","solutions":["Ensure the upstream token/parameter actually carries the external user ID before calling the API.","If the ID comes from a request field, add client-side/earlier middleware validation for non-empty values.","Check the external user provisioning flow: the account must be created with a real external identifier.","If calling validateExternalUserID directly in tests/tools, pass a real trimmed ID string."],"exampleFix":"// before\nif err := validateExternalUserID(c.GetHeader(\"X-External-User-Id\")); err != nil { ... }\n// after: check presence first\nextID := strings.TrimSpace(c.GetHeader(\"X-External-User-Id\"))\nif extID == \"\" {\n    c.AbortWithStatusJSON(400, gin.H{\"error\": \"external user id header required\"})\n    return\n}\nif err := validateExternalUserID(extID); err != nil { ... }","handlingStrategy":"validation","validationCode":"func preValidateExternalUserID(id string) error {\n    if strings.TrimSpace(id) == \"\" {\n        return errors.New(\"external user id required\")\n    }\n    return nil\n}\n// call before issuing the API request","typeGuard":"func hasExternalUserID(v string) bool { return strings.TrimSpace(v) != \"\" }","tryCatchPattern":null,"preventionTips":["Always trim and check IDs at the client boundary before sending.","Ensure user provisioning always sets a real external identifier.","Add a not-null/length constraint on the external ID column in the user store."],"tags":["auth","validation","user-id"],"backgroundTag":"missing-required-identifier","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}