{"record":{"id":"9f60ba58faaf78e1","repo":"hashicorp/nomad","slug":"invalid-keyidheader","errorCode":null,"errorMessage":"invalid KeyIDHeader","messagePattern":"invalid KeyIDHeader","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/acl.go","lineNumber":1844,"sourceCode":"\t}\n\tif k.KeyIDHeader == \"\" {\n\t\tif k.KeyID != \"\" {\n\t\t\tk.KeyIDHeader = OIDCClientAssertionHeaderKid\n\t\t}\n\t\tif k.PemCert != \"\" || k.PemCertFile != \"\" {\n\t\t\tk.KeyIDHeader = OIDCClientAssertionHeaderX5tS256\n\t\t}\n\t}\n}\n\nvar (\n\tErrMissingClientAssertionKey      = errors.New(\"missing PemKey or PemKeyFile\")\n\tErrAmbiguousClientAssertionKey    = errors.New(\"require only one of PemKey or PemKeyFile\")\n\tErrMissingClientAssertionKeyID    = errors.New(\"missing PemCert, PemCertFile, or KeyID\")\n\tErrAmbiguousClientAssertionKeyID  = errors.New(\"require only one of PemCert, PemCertFile, or KeyID\")\n\tErrInvalidClientAssertionKeyPath  = errors.New(\"invalid PemKeyFile\")\n\tErrInvalidClientAssertionCertPath = errors.New(\"invalid PemCertFile\")\n\tErrInvalidKeyIDHeader             = errors.New(\"invalid KeyIDHeader\")\n)\n\n// Validate ensures that one Key and one Cert or KeyID are provided,\n// and that the key ID header is valid for the provided KeyID or cert.\nfunc (k *OIDCClientAssertionKey) Validate() error {\n\tif k == nil {\n\t\treturn nil\n\t}\n\n\t// mutually exclusive key fields\n\t// must have key file or base64, but not both\n\tif k.PemKey == \"\" && k.PemKeyFile == \"\" {\n\t\treturn ErrMissingClientAssertionKey\n\t}\n\tif k.PemKey != \"\" && k.PemKeyFile != \"\" {\n\t\treturn ErrAmbiguousClientAssertionKey\n\t}\n\tif k.PemKeyFile != \"\" {","sourceCodeStart":1826,"sourceCodeEnd":1862,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/acl.go#L1826-L1862","documentation":"KeyIDHeader for a client assertion must be one of \"x5t\", \"x5t#S256\" (certificate-derived) or \"kid\" (when a raw KeyID is used). ErrInvalidKeyIDHeader is returned by Validate() and defensively by lib/auth/oidc hashKeyID when the header name is anything else, since the OIDC provider would not recognize the header.","triggerScenarios":"Validate() where KeyID is set but KeyIDHeader != \"kid\"; or a cert is set with KeyIDHeader not in {\"x5t\",\"x5t#S256\"}; at runtime, hashKeyID hitting its default branch with an unknown header.","commonSituations":"Typo'd header values (\"x5T\", \"kid #256\"); copying JWT header names from another IdP's docs; older configs written before x5t#S256 support existed.","solutions":["When using KeyID, set KeyIDHeader to structs.OIDCClientAssertionHeaderKid (\"kid\")","When using a cert, set KeyIDHeader to \"x5t#S256\" (preferred) or \"x5t\"","Fix typos/whitespace in the header string in the auth-method config"],"exampleFix":"// before\nkey := &structs.OIDCClientAssertionKey{\n  KeyID: \"abc123\",\n  KeyIDHeader: \"Kid\",\n}\n// after\nkey := &structs.OIDCClientAssertionKey{\n  KeyID: \"abc123\",\n  KeyIDHeader: structs.OIDCClientAssertionHeaderKid,\n}","handlingStrategy":"validation","validationCode":"valid := map[string]bool{\n    structs.OIDCClientAssertionHeaderKid: true,\n    structs.OIDCClientAssertionHeaderX5t: true,\n    structs.OIDCClientAssertionHeaderX5tS256: true,\n}\nif !valid[key.KeyIDHeader] {\n    return fmt.Errorf(\"KeyIDHeader %q not allowed\", key.KeyIDHeader)\n}","typeGuard":null,"tryCatchPattern":"if err := key.Validate(); err != nil {\n    if errors.Is(err, structs.ErrInvalidKeyIDHeader) {\n        // set KeyIDHeader to kid, x5t, or x5t#S256\n    }\n    return err\n}","preventionTips":["Use the exported OIDCClientAssertionHeader* constants, never raw strings","Remember kid pairs with KeyID; x5t/x5t#S256 pair with certs","Check your IdP's documented assertion header support before choosing"],"tags":["nomad","oidc","jwt","client-assertion"],"backgroundTag":"invalid-jwt-header","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}