Add graceful error handling for SSO configuration and discovery failures

[Copilot]

Problem

SSO integration crashes the server when environment variables are invalid or when the upstream discovery service is unreachable. This prevents graceful fallback to Email OTP authentication.

Fixes FRM-2259

Solution

Breaking Changes

• No - this PR is backwards compatible

Improvements:

• Configuration validation without crashing: Added isSsoConfigured() that validates SSO_DISCOVERY_URL, SSO_CLIENT_ID, and SSO_CLIENT_SECRET at startup. Checks for blank values, default placeholders, and invalid URL formats. Logs errors but never throws.

• Lazy OIDC discovery: Moved discovery from constructor to initializeClientConfig() method that only executes when SSO is actually used. Prevents startup crashes from unreachable endpoints.

• Safe error propagation: Wrapped URL parsing in try-catch and discovery calls in promise rejection handlers. All errors converted to Result types via ResultAsync.fromPromise().

Example flow:

// Before: Constructor immediately calls external service
constructor({ discoveryUrl }) {
  const oidcServer = new URL(discoveryUrl)  // throws on invalid URL
  this.clientConfigPromise = oidcClient.discovery(...)  // network call at startup
}

// After: Constructor only validates, defers external calls
constructor(config) {
  this.isConfigured = isSsoConfigured()  // validates without throwing
}

private initializeClientConfig() {
  try {
    const oidcServer = new URL(this.config.discoveryUrl)
    this.clientConfigPromise = oidcClient.discovery(...).catch(...)
  } catch {
    this.clientConfigPromise = Promise.reject(new SsoCreateRedirectUrlError(...))
  }
}

Error scenarios now handled:

• Invalid SSO_DISCOVERY_URL format → logged, SSO disabled, Email OTP available
• Default/placeholder credentials → logged, SSO disabled, Email OTP available
• Unreachable discovery endpoint → lazy init fails gracefully, Email OTP available
• Network errors during auth flow → errors returned to client, no crash

Before & After Screenshots

N/A - Backend changes only

Tests

• Build and lint verification passing
• Code review completed
• Manual testing requires deployment with invalid SSO configuration

Deploy Notes

No new environment variables, scripts, or dependencies.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fastdl.mongodb.org
  • Triggering command: /usr/local/bin/node node --experimental-vm-modules node_modules/jest/bin/jest.js --testPathPattern=auth.service.spec --verbose all')}catch(e){}" (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

FormSG is integrated as a pilot system on the new OGP SSO platform.
This integration is configured using the environment variables SSO_CLIENT_ID, SSO_CLIENT_SECRET, and SSO_DISCOVERY_URL.

We want to prepare FormSG's SSO integration for the next phase as we build out both products. This means that the SSO implementation should meet two additional objectives:

• when SSO_DISCOVERY_URL or any of the other environment variables are left blank or invalid, the application should simply log the error and fallback to Email OTPs (the current behaviour).
• when the upstream service at SSO_DISCOVERY_URL does not respond correctly, the SSO integration should fail gracefully and securely, and must not crash the server or cause any restarts.

Check the SSO implementation and make sure that it meets these requirements. Do not introduce other unnecessary changes at this point, keep it focused.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[linear]

FRM-2259 SSO Graceful Failure