{"record":{"id":"dec58d893979c2b2","repo":"gethomepage/homepage","slug":"oidc-auth-is-enabled-but-required-settings-are-mis","errorCode":null,"errorMessage":"OIDC auth is enabled but required settings are missing.","messagePattern":"OIDC auth is enabled but required settings are missing\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/pages/api/auth/[...nextauth].js","lineNumber":61,"sourceCode":"  } catch {\n    throw new Error(\"HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL.\");\n  }\n\n  if (\n    ![\"http:\", \"https:\"].includes(parsedAuthUrl.protocol) ||\n    parsedAuthUrl.username ||\n    parsedAuthUrl.password ||\n    parsedAuthUrl.search ||\n    parsedAuthUrl.hash\n  ) {\n    throw new Error(\n      \"HOMEPAGE_EXTERNAL_URL (or NEXTAUTH_URL) must be an absolute HTTP(S) URL without credentials, query, or fragment.\",\n    );\n  }\n\n  if (hasOidcConfig) {\n    if (!process.env.NEXTAUTH_SECRET) {\n      throw new Error(\"OIDC auth is enabled but required settings are missing.\");\n    }\n  } else if (hasAnyOidcConfig) {\n    throw new Error(\"OIDC auth is enabled but required settings are missing.\");\n  } else if (!homepageAuthPassword || !process.env.NEXTAUTH_SECRET) {\n    throw new Error(\"Password auth is enabled but required settings are missing.\");\n  }\n\n  if (process.env.NEXTAUTH_SECRET.length < MIN_AUTH_SECRET_LENGTH) {\n    throw new Error(\n      `HOMEPAGE_AUTH_SECRET (or NEXTAUTH_SECRET) must be at least ${MIN_AUTH_SECRET_LENGTH} characters. Generate one with: openssl rand -base64 32`,\n    );\n  }\n}\n\n// Give fail2ban / CrowdSec etc something to match on\nfunction logFailedPasswordSignIn() {\n  createLogger(\"nextauth\").warn(\"Failed password sign-in attempt\");\n}","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/gethomepage/homepage/blob/b6dca1ae033e613d8e692f9a161a3cc53a5a2857/src/pages/api/auth/[...nextauth].js#L43-L79","documentation":"Thrown when full OIDC config is detected (issuer + clientId + clientSecret all present) but NEXTAUTH_SECRET is unset. NextAuth requires a secret to sign and/or encrypt its session JWTs; Homepage treats its absence as a hard blocker for the OIDC path.","triggerScenarios":"`hasOidcConfig` is true (HOMEPAGE_OIDC_ISSUER, HOMEPAGE_OIDC_CLIENT_ID, HOMEPAGE_OIDC_CLIENT_SECRET all set) and `process.env.NEXTAUTH_SECRET` is falsy. Path: `if (hasOidcConfig) { if (!process.env.NEXTAUTH_SECRET) throw ... }`.","commonSituations":"Operator moved from password auth to OIDC and forgot to add the secret; secret was loaded from a file/docker secret that wasn't mounted; misnamed the variable (HOMEPAGE_AUTH_SECRET is not read for this — only NEXTAUTH_SECRET is checked here).","solutions":["Generate a secret: `openssl rand -base64 32`.","Set it as NEXTAUTH_SECRET (Homepage also accepts HOMEPAGE_AUTH_SECRET in other places, but for this guard NEXTAUTH_SECRET must be populated).","Restart the app so the module re-reads env.","Verify the secret is at least 32 chars to also satisfy the downstream length check."],"exampleFix":"// before\nHOMEPAGE_OIDC_ISSUER=https://idp.example.com\nHOMEPAGE_OIDC_CLIENT_ID=homepage\nHOMEPAGE_OIDC_CLIENT_SECRET=***\n# no NEXTAUTH_SECRET\n\n// after\nNEXTAUTH_SECRET=$(openssl rand -base64 32)","handlingStrategy":"validation","validationCode":"function validateOidc(env) {\n  const hasFull = env.HOMEPAGE_OIDC_ISSUER && env.HOMEPAGE_OIDC_CLIENT_ID && env.HOMEPAGE_OIDC_CLIENT_SECRET;\n  if (hasFull && !env.NEXTAUTH_SECRET) {\n    throw new Error('OIDC configured but NEXTAUTH_SECRET is missing');\n  }\n}","typeGuard":"function hasCompleteOidc(env) {\n  return Boolean(env.HOMEPAGE_OIDC_ISSUER && env.HOMEPAGE_OIDC_CLIENT_ID && env.HOMEPAGE_OIDC_CLIENT_SECRET);\n}","tryCatchPattern":null,"preventionTips":["Generate NEXTAUTH_SECRET with `openssl rand -base64 32` on every deploy that uses auth.","Use Docker/Kubernetes secrets rather than baking it into the image.","Treat the OIDC triple as inseparable from the secret in env templates.","Add a preflight check pairing OIDC + secret."],"tags":["auth","oidc","configuration","env","secret","startup"],"backgroundTag":null,"analyzedSha":"b6dca1ae033e613d8e692f9a161a3cc53a5a2857","analyzedAt":"2026-08-13T04:48:44.121Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}