Skip to content

Allow configurable OAuth scopes for the Okta/OIDC sign-in provider #1549

Open

Description

@nickytonline

Summary

OpenBot's OKTA_OAUTH_* settings can work with OIDC providers other than Okta because better-auth's okta() helper uses OIDC discovery against the configured issuer.

However, OpenBot doesn't pass scopes to the helper (server/src/auth/index.ts), so better-auth always requests its default scopes:

openid profile email

Providers that support a different scope set can reject the authorization request with invalid_scope, preventing sign-in entirely.

I encountered this while integrating OpenBot with Pomerium's OIDC bridge, a new feature in our upcoming release (I work at Pomerium).

The bridge allows Pomerium, an identity-aware proxy, to act as the OIDC provider for an application behind it. Users authenticate at the proxy, and the application can establish its own session without requiring another interactive login.

The bridge currently supports only the openid scope. Consequently, OpenBot's authorization request fails with:

error=invalid_scope
error_description=unsupported scope requested : openid profile email

The bridge returns the user's email, email_verified, name, and groups through its UserInfo endpoint. Better Auth's generic OAuth implementation supports retrieving user information from that endpoint, so requesting additional scopes should not be necessary for this particular integration.

Why the runtime SSO provider doesn't solve this

Admin → Identity providers uses the @better-auth/sso plugin and supports configuring scopes.

However, OpenBot's startup configuration requires Google, Microsoft, or Okta to be configured through environment variables to enable sign-in. Without one, the server refuses to start unless OPENBOT_SINGLE_USER is enabled.

That means the runtime SSO provider cannot be the only sign-in mechanism for this deployment, and the environment-configured provider still encounters invalid_scope.

Suggested fix

Add an optional OKTA_OAUTH_SCOPES environment variable and pass the configured scopes to better-auth.

  • In server/src/config.ts, parse a space- or comma-separated list of scopes. If the variable is unset, preserve the current behavior. Reject configurations that explicitly omit openid.
  • In server/src/auth/index.ts, pass the scopes through to the existing okta() helper.
  • Document the setting in .env.example, the README's sign-in section, and docs/configuration.md.

For example:

okta({
  clientId,
  clientSecret,
  issuer,
  ...(scopes ? { scopes } : {}),
})

Example configuration:

OKTA_OAUTH_ISSUER=https://authenticate.example.com
OKTA_OAUTH_CLIENT_ID=https://openbot.example.com/
OKTA_OAUTH_CLIENT_SECRET=...
OKTA_OAUTH_SCOPES=openid

Keeping the setting optional ensures existing deployments continue requesting openid profile email.

A provider-neutral naming convention, such as OIDC_SCOPES, could also make sense, particularly given the discussion in #258 about supporting a generic OIDC provider. I'm suggesting OKTA_OAUTH_SCOPES to keep this change small and consistent with the current configuration.

Happy to open a PR if this approach sounds reasonable.

AI Disclosure

Investigated with Claude Code (Opus 5.5), issue drafted with Claude Code (Sonnet 5.5) and edited by me.

Metadata

Metadata

Assignees

No one assigned

    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