Support OAuth2-only providers for OpenID login (providers that cannot issue an id_token)

[mkroemer]

What feature would you like to see added?

An OPENID_USE_OAUTH2 mode that authenticates against explicitly configured OAuth 2.0 endpoints
instead of OIDC discovery, so providers that expose OAuth 2.0 but will not issue an id_token to
third-party clients can be used for login.

The problem

setupOpenId() requires OIDC discovery and a validated id_token. Some providers cannot supply
one to third-party apps at all, which makes them impossible to use for LibreChat login today —
not misconfigured, just unreachable.

Atlassian is the concrete case, and it fails in a way that is easy to misread as a config error:

1. Its OAuth 2.0 (3LO) apps can only be granted API scopes. The User identity API
   permission in the developer console offers exactly read:me and read:account — no OIDC
   scopes are selectable, for existing apps or newly created ones.
2. auth.atlassian.com does publish a discovery document advertising openid, profile and
   email in scopes_supported — but that appears to be the identity platform's stock output
   rather than a description of what a 3LO app may request. The document exposes
   mfa_challenge_endpoint, device_authorization_endpoint and /oidc/register, so the
   authorization server itself speaks full OIDC; the 3LO app-registration layer in front of it is
   what does not offer those scopes.
3. Atlassian's 3LO documentation
   documents the token response as access_token, expires_in and scope — no id_token — and
   does not mention openid or OpenID Connect anywhere.
4. So discovery succeeds, the authorization request is well-formed, and the flow still cannot
   complete. In my testing, requesting openid profile email from a 3LO app failed at Atlassian's
   consent screen before the callback was reached; requesting the API scopes it will grant means
   no id_token comes back for openid-client to validate.

I should be candid about the limits of that evidence: I could not find an Atlassian statement
explicitly ruling out the openid scope for 3LO apps, so the above is convergent evidence
(documented token response, developer-console scope list, and an observed consent failure) rather
than a quotable prohibition. Note also that Atlassian's own OpenID Connect documentation covers
Data Center and Access acting as a relying party consuming an external IdP — the opposite
direction from what this needs.

Identity for such providers also lives at a provider-specific endpoint — https://api.atlassian.com/me
for Atlassian — rather than a standard userinfo_endpoint.

Every documented provider today (Apple, Auth0, Authelia, Authentik, AWS, Azure, Discord, Keycloak)
is a full OIDC provider, so this gap has not come up in the existing guides.

Prior art worth noting: passport-atlassian-oauth2
(2019) solves this outside LibreChat with exactly the same shape — auth.atlassian.com/authorize,
auth.atlassian.com/oauth/token, a profile fetched from api.atlassian.com/me, an audience
parameter, and no openid scope or id_token anywhere in its source. That a dedicated Atlassian
strategy arrived at this independently is part of why I think the generic version belongs upstream
rather than as a per-provider package.

I could not find an existing request for this. The closest prior art I found is
Discussion #8986, which is a different
problem — a refresh response dropping the id_token when OPENID_REUSE_TOKENS=true — though it
does show the OIDC path assuming id_token availability. This proposal does not fix that, and the
two are independent.

Proposed implementation

Only the transport differs. The result feeds into the same processOpenIDAuth, so user
provisioning, role sync, avatars and email-domain restrictions behave identically to the OIDC path.

packages/api/src/oauth/oauth2Login.ts (new, TypeScript)

• fetchOAuth2UserInfo(url, accessToken) — bearer request to the userinfo endpoint, honouring the
  existing OpenID proxy dispatcher
• resolveOAuth2Subject(userinfo) — sub → account_id → id, since OAuth2 userinfo endpoints
  are not bound by the OIDC spec and name this field differently
• getMissingOAuth2LoginConfig(env) — reports every missing required variable at once
• buildOAuth2StrategyOptions(env) — maps the environment onto the strategy options
• buildOAuth2AuthorizationParams(env) — sends OPENID_AUDIENCE on the authorization request,
  using the same comma-separated "first non-empty wins" semantics as the OIDC path

api/strategies/openidStrategy.js (+84 / −2)

• setupOpenId() branches to setupOpenIdOAuth2() when the mode is enabled
• the passport-oauth2 strategy registers under the existing openid name, so routes, buttons and
  callback URLs are unchanged
• processOpenIDAuth() gains an optional pre-fetched-userinfo argument, since there is no
  Configuration to hand to client.fetchUserInfo in this mode

api/package.json — declares passport-oauth2, already present transitively via
passport-github2 / passport-google-oauth20

.env.example — documents the four new variables

Per the TypeScript conversion guidance, the logic is TypeScript in /packages/api alongside the
existing oauth/ module (+123 lines), and /api gets only what has to sit next to
processOpenIDAuth and passport.use in the legacy JS server (+84 lines): the strategy
registration and the verify callback.

Configuration

OPENID_USE_OAUTH2=true
OPENID_AUTHORIZATION_URL=https://auth.atlassian.com/authorize
OPENID_TOKEN_URL=https://auth.atlassian.com/oauth/token
OPENID_USERINFO_URL=https://api.atlassian.com/me
OPENID_SCOPE="read:me read:account"

OPENID_ISSUER is unused in this mode. If any of the three URLs is missing, setup logs which ones
and returns null without registering a strategy.

Which components are impacted?

Backend / authentication only. No frontend, schema or API-contract changes — the login button,
routes and callback URL are the existing OpenID ones.

Default behaviour is unchanged: OPENID_USE_OAUTH2 defaults to false and the OIDC path is untouched.

Testing

I have a working branch, rebased on dev:

• 23 TypeScript tests for the new helpers
• 12 tests for the strategy (registration, option mapping, discovery not being invoked, missing-URL
  handling, the ignored PKCE flag, the bearer userinfo request, subject resolution and its fallbacks, userinfo
  failure, missing identifier, domain rejection)
• the existing 126 openidStrategy tests pass unchanged; api/strategies/ is 308/308 and
  packages/api/src/oauth/ is 129/129

Also verified end-to-end against Atlassian with a real 3LO app: login succeeds, and the identifier
resolved this way matches the account IDs already stored in openidId for users provisioned
through that provider — so existing installs would not be stranded behind a second identity.

Open questions for maintainers

1. Is this welcome as a generic mode, or too niche? I have written it provider-agnostically
   rather than as an Atlassian special case, but you may prefer it scoped differently.
2. setupOpenIdAdmin is not wired up for this mode — it needs an openid-client
Configuration, which does not exist here. Leave it OIDC-only, or should OAuth2 admin login be
   part of this?
3. State verification is weaker than the OIDC path. /oauth/openid passes state: randomState() to passport.authenticate, and passport-oauth2 short-circuits on a string
   state: it puts the value on the authorization URL and never calls the state store, so any
   store other than the NullStore has nothing to verify against and every callback fails. The
   strategy therefore sets state: false, which means the returned state is not checked (and PKCE
   is unavailable, since its verifier lives in that same store — OPENID_USE_PKCE logs a warning
   and is ignored). Letting the store manage state would fix both, but that means changing the
   shared route, which also feeds the OIDC strategy — I did not want to touch that unilaterally.
   How would you prefer this handled?
4. Token refresh / OPENID_REUSE_TOKENS is likewise OIDC-specific and not claimed by this
   mode. Is that an acceptable limitation to document?
5. Account linking. My own deployment also needs linking an OAuth2 login to an existing local
   account, which I have deliberately kept out of this proposal since it is orthogonal and I saw
   account linking mentioned as already planned. Happy to raise separately.

Happy to open the PR once there is a signal this is wanted, or to adjust the approach first.

[mkroemer]

Can I open a PR?

[mkroemer]

Opened as #16410, rebased on current dev.

Since the proposal, the OAuth2-only path also verifies state: it uses createOAuthStateStore from #15880, the same signed-cookie store the other OAuth2 providers use, and /oauth/openid no longer presets a state string in this mode. The OIDC path is unchanged. Happy to adjust the approach if you would prefer it done differently.