Skip to content

fix(auth): validate OIDC_SCOPES at startup and document default behavior #496

@peppescg

Description

@peppescg

Problem

OIDC_SCOPES has a hardcoded default in src/lib/auth/constants.ts:

export const OIDC_SCOPES = process.env.OIDC_SCOPES?.split(",") ?? [
  "openid",
  "email",
  "profile",
  "offline_access",
];

Default scopes: openid, email, profile, offline_access.

While these defaults are reasonable for most OIDC providers, there are potential issues:

  1. offline_access — not all providers support this scope, and some require explicit configuration to allow it. If the provider doesn't support it, the auth flow may fail silently or return tokens without refresh capability.
  2. Provider-specific scopes — some providers (e.g. Azure AD) require different scope names or additional scopes for equivalent functionality.
  3. No validation — if OIDC_SCOPES is set as an env var but malformed (e.g. space-separated instead of comma-separated), the split produces wrong values with no warning.

Proposal

  1. Log the active scopes at startup so operators can verify what's being requested
  2. Validate format — warn if scopes look malformed (e.g. contain spaces within a single scope value)
  3. Document the defaults clearly in the README env var table — currently the default values are not listed there

Additional context

  • The env var uses comma-separated format: OIDC_SCOPES=openid,email,profile
  • These scopes are passed directly to the OIDC provider via Better Auth's genericOAuth plugin

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions