feat(auth): control OAuth rollout through AppConfig

Author: waleedlatif1

apps/docs/content/docs/cli/authentication.mdx

@@ -237,9 +237,13 @@ Save it to avoid repeating the flag:
 sim configure --set-endpoint http://localhost:3000 --profile local
 ```
 
-A self-hosted deployment offers OAuth sign-in when
-`OAUTH_PROVIDER_ENABLED=true` and authentication is enabled. Leave it unset to
-use the pairing-code handoff; `DISABLE_AUTH=true` also forces OAuth off.
+A deployment offers OAuth sign-in when its global `oauth-provider` feature flag
+is enabled. With AppConfig, enable it in the existing `feature-flags` document
+using `"oauth-provider": { "enabled": true }`. When AppConfig is disabled or no
+AppConfig document has been loaded, `OAUTH_PROVIDER_ENABLED=true` supplies the fallback.
+With the provider off, the CLI uses the pairing-code handoff; `DISABLE_AUTH=true`
+always forces OAuth off. Operators must apply the database migration and drain
+older app instances before enabling it. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim).
 
 ## Where the login is stored
 

apps/docs/content/docs/platform/enterprise/self-hosted.mdx

@@ -90,7 +90,7 @@ Persist that value as `CRON_SECRET` on the app **and** on whatever calls these e
 <Callout type="warn">
   Both shipped deployments schedule the data-drain dispatcher and OAuth token cleanup, but **not** the three configurable data-retention endpoints. Setting `DATA_RETENTION_ENABLED=true` alone deletes no retained product data — those windows are evaluated only when one of the three endpoints is called. Add them to `cronjobs.jobs` yourself, or drive them from an external scheduler.
 
-  OAuth token cleanup continues after `OAUTH_PROVIDER_ENABLED=false` so rows created while the provider was enabled do not become permanent.
+  OAuth token cleanup continues when the global `oauth-provider` feature flag is off, so rows created while the provider was enabled do not become permanent. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for AppConfig and fallback configuration.
 </Callout>
 
 ```bash

apps/docs/content/docs/platform/self-hosting/authentication.mdx

@@ -85,23 +85,46 @@ Your deployment can act as an OAuth 2.0 authorization server using authorization
 code with PKCE and current OAuth security guidance. The Sim CLI uses it when
 enabled; see [CLI authentication](/cli/authentication).
 
-Use a two-phase rollout: apply the database migration while this flag is unset,
-deploy and drain every older app instance, then enable it in a separate config
-rollout:
+The global `oauth-provider` feature flag controls availability. Keep it off while
+applying the database migration, then deploy and drain every older app instance
+before enabling it.
+
+If your deployment uses AWS AppConfig, add this entry to the existing
+`feature-flags` document and deploy that configuration:
+
+```json
+{
+  "oauth-provider": { "enabled": true }
+}
+```
+
+Preserve the document's other entries. This flag is global: use `enabled`, not
+workspace, organization, user, or admin targeting. Set `enabled` to `false` to
+turn it off; changes take effect as instances refresh their AppConfig cache.
+
+When AppConfig is disabled or no AppConfig document has been loaded, the
+fallback is:
 
 ```bash
 OAUTH_PROVIDER_ENABLED=true
 ```
 
-With it unset or false, the discovery document at `/.well-known/oauth-authorization-server`
-returns 404 and the CLI falls back to the pairing-code handoff on its own.
+In that fallback mode, unset or false keeps the provider off. An available
+AppConfig document takes precedence over this variable, including when the
+`oauth-provider` entry is missing or disabled. AppConfig fetch failures retain
+the last successfully loaded document.
+
+When the provider is off, discovery at `/.well-known/oauth-authorization-server`
+returns 404 and the CLI falls back to the pairing-code handoff.
 `DISABLE_AUTH=true` also forces the provider off because the authorization flow
 requires a real Better Auth user session.
 
 Access tokens are opaque and last an hour; refresh tokens rotate on every use.
 Each login has a fixed thirty-day lifetime that refreshing does not extend.
-Nothing is cached, so revoking a grant under
-**Settings → Authorized apps** stops the app on its very next request.
+Token validation checks current grants, so revoking a grant under
+**Settings → Authorized apps** stops the app on its very next request. These
+settings remain available for reviewing and revoking existing grants while the
+provider is off, and scheduled OAuth token cleanup continues.
 
 ### Registering an app
 

apps/docs/content/docs/platform/self-hosting/environment-variables.mdx

@@ -127,7 +127,7 @@ Google, GitHub, and Microsoft sign-in, their callback URLs, and the `DISABLE_*_A
 
 | Variable | Description |
 | --- | --- |
-| `OAUTH_PROVIDER_ENABLED` | Set to `true` in a second rollout after the migration is applied and every older app instance is drained. Unset/false uses the CLI pairing-code handoff. `DISABLE_AUTH=true` always forces it off. See [Authentication](/platform/self-hosting/authentication#sign-in-with-sim) |
+| `OAUTH_PROVIDER_ENABLED` | Fallback for the global `oauth-provider` feature flag when AppConfig is disabled or no AppConfig document has been loaded. Set to `true` only after the migration is applied and every older app instance is drained. With AppConfig, use `"oauth-provider": { "enabled": true }` in the existing `feature-flags` document instead. `DISABLE_AUTH=true` always forces it off. See [Authentication](/platform/self-hosting/authentication#sign-in-with-sim) |
 
 ## Integration Credentials
 

apps/sim/app/(auth)/oauth/consent/page.tsx

@@ -2,7 +2,7 @@ import type { Metadata } from 'next'
 import { redirect } from 'next/navigation'
 import type { SearchParams } from 'nuqs/server'
 import { getSession } from '@/lib/auth'
-import { isOAuthProviderEnabled } from '@/lib/core/config/env-flags'
+import { isOAuthProviderEnabled } from '@/lib/auth/oauth-provider-feature'
 import { OAuthConsentView } from '@/app/(auth)/oauth/consent/consent-view'
 import { oauthConsentSearchParamsCache } from '@/app/(auth)/oauth/consent/search-params'
 
@@ -22,7 +22,7 @@ export default async function OAuthConsentPage({
 }: {
   searchParams: Promise<SearchParams>
 }) {
-  if (!isOAuthProviderEnabled) redirect('/')
+  if (!(await isOAuthProviderEnabled())) redirect('/')
 
   const [session, raw] = await Promise.all([getSession(), searchParams])
 

apps/sim/app/(auth)/oauth/sign-in/route.test.ts

@@ -13,14 +13,15 @@ const flags = vi.hoisted(() => ({
 
 vi.mock('@/lib/core/config/env-flags', () => ({
   ...envFlagsMock,
-  get isOAuthProviderEnabled() {
-    return flags.enabled
-  },
   get isRegistrationDisabled() {
     return flags.registrationDisabled
   },
 }))
 
+vi.mock('@/lib/auth/oauth-provider-feature', () => ({
+  isOAuthProviderEnabled: vi.fn(async () => flags.enabled),
+}))
+
 vi.mock('@/lib/core/config/env', () => {
   const mock = createEnvMock({ NEXT_PUBLIC_APP_URL: 'https://sim.test' })
   return {

apps/sim/app/(auth)/oauth/sign-in/route.ts

@@ -1,5 +1,6 @@
 import { type NextRequest, NextResponse } from 'next/server'
-import { isOAuthProviderEnabled, isRegistrationDisabled } from '@/lib/core/config/env-flags'
+import { isOAuthProviderEnabled } from '@/lib/auth/oauth-provider-feature'
+import { isRegistrationDisabled } from '@/lib/core/config/env-flags'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { buildAuthCrossLink } from '@/app/(auth)/auth-redirect'
@@ -39,7 +40,7 @@ function consumeInteractivePrompt(params: URLSearchParams): boolean {
  */
 export const GET = withRouteHandler(async (request: NextRequest) => {
   /** Avoid sending a newly signed-in user to a disabled provider's JSON 404. */
-  if (!isOAuthProviderEnabled) {
+  if (!(await isOAuthProviderEnabled())) {
     return NextResponse.redirect(new URL('/', getBaseUrl()), 302)
   }
 

apps/sim/app/api/auth/[...all]/route.test.ts

@@ -14,6 +14,7 @@ const handlerMocks = vi.hoisted(() => ({
     user: { id: 'anon' },
     session: { id: 'anon-session' },
   })),
+  oauthEnabled: vi.fn(),
 }))
 
 vi.mock('better-auth/next-js', () => ({
@@ -26,6 +27,9 @@ vi.mock('better-auth/next-js', () => ({
 vi.mock('@/lib/auth', () => ({
   auth: { handler: {} },
 }))
+vi.mock('@/lib/auth/oauth-provider-feature', () => ({
+  isOAuthProviderEnabled: handlerMocks.oauthEnabled,
+}))
 
 vi.mock('@/lib/auth/anonymous', () => ({
   ensureAnonymousUserExists: handlerMocks.ensureAnonymousUserExists,
@@ -63,6 +67,7 @@ vi.mock('@/app/api/credential-groups/oauth-callback', () => ({
 import { GET, POST } from '@/app/api/auth/[...all]/route'
 
 afterAll(resetEnvFlagsMock)
+beforeEach(() => handlerMocks.oauthEnabled.mockResolvedValue(true))
 
 describe('auth catch-all route managed OAuth callbacks', () => {
   beforeEach(() => {
@@ -97,21 +102,26 @@ describe('auth catch-all route managed OAuth callbacks', () => {
     expect(handlerMocks.betterAuthGET).not.toHaveBeenCalled()
   })
 
-  it('leaves ordinary connector callbacks with Better Auth', async () => {
-    handlerMocks.betterAuthGET.mockResolvedValueOnce(new Response(null, { status: 204 }))
-    const request = createMockRequest(
-      'GET',
-      undefined,
-      {},
-      'http://localhost:3000/api/auth/oauth2/callback/jira?state=better-auth-state&code=code-1'
-    )
+  it.each([true, false])(
+    'preserves connector callbacks when the provider is enabled=%s',
+    async (enabled) => {
+      handlerMocks.oauthEnabled.mockResolvedValue(enabled)
+      handlerMocks.betterAuthGET.mockResolvedValueOnce(new Response(null, { status: 204 }))
+      const request = createMockRequest(
+        'GET',
+        undefined,
+        {},
+        'http://localhost:3000/api/auth/oauth2/callback/jira?state=better-auth-state&code=code-1'
+      )
 
-    const response = await GET(request)
+      const response = await GET(request)
 
-    expect(response.status).toBe(204)
-    expect(handlerMocks.betterAuthGET).toHaveBeenCalledWith(request)
-    expect(handlerMocks.credentialGroupCallback).not.toHaveBeenCalled()
-  })
+      expect(response.status).toBe(204)
+      expect(handlerMocks.betterAuthGET).toHaveBeenCalledWith(request)
+      expect(handlerMocks.credentialGroupCallback).not.toHaveBeenCalled()
+      expect(handlerMocks.oauthEnabled).not.toHaveBeenCalled()
+    }
+  )
 
   it('rejects a managed state sent to an unsupported connector callback', async () => {
     const request = createMockRequest(
@@ -361,10 +371,46 @@ describe('OAuth provider client endpoints', () => {
     expect(handlerMocks.betterAuthPOST).toHaveBeenCalledTimes(1)
   })
 
+  it.each(['oauth2/consent', 'oauth2/continue', 'oauth2/public-client-prelogin'])(
+    'stops serving %s after the runtime flag changes',
+    async (path) => {
+      const request = () =>
+        createMockRequest('POST', {}, {}, `http://localhost:3000/api/auth/${path}`)
+      expect((await POST(request())).status).toBe(200)
+      handlerMocks.betterAuthPOST.mockClear()
+
+      handlerMocks.oauthEnabled.mockResolvedValue(false)
+      const disabled = await POST(request())
+      expect(disabled.status).toBe(404)
+      expect(disabled.headers.get('cache-control')).toBe('no-store')
+      expect(handlerMocks.betterAuthPOST).not.toHaveBeenCalled()
+
+      handlerMocks.oauthEnabled.mockResolvedValue(true)
+      expect((await POST(request())).status).toBe(200)
+      expect(handlerMocks.betterAuthPOST).toHaveBeenCalledOnce()
+    }
+  )
+
+  it.each([true, false])(
+    'preserves connector POST callbacks when the provider is enabled=%s',
+    async (enabled) => {
+      handlerMocks.oauthEnabled.mockResolvedValue(enabled)
+      const request = createMockRequest(
+        'POST',
+        {},
+        {},
+        'http://localhost:3000/api/auth/oauth2/callback/jira'
+      )
+      expect((await POST(request)).status).toBe(200)
+      expect(handlerMocks.betterAuthPOST).toHaveBeenCalledExactlyOnceWith(request)
+      expect(handlerMocks.oauthEnabled).not.toHaveBeenCalled()
+    }
+  )
+
   it.each([true, false])(
     'preserves authenticated connector linking when the OAuth provider is enabled=%s',
     async (enabled) => {
-      setEnvFlags({ isOAuthProviderEnabled: enabled })
+      handlerMocks.oauthEnabled.mockResolvedValue(enabled)
       const request = createMockRequest(
         'POST',
         { providerId: 'google-email', callbackURL: 'http://localhost:3000/workspace' },
@@ -376,6 +422,7 @@ describe('OAuth provider client endpoints', () => {
 
       expect(response.status).toBe(200)
       expect(handlerMocks.betterAuthPOST).toHaveBeenCalledExactlyOnceWith(request)
+      expect(handlerMocks.oauthEnabled).not.toHaveBeenCalled()
     }
   )
 })

apps/sim/app/api/auth/[...all]/route.ts

@@ -4,6 +4,7 @@ import { sharedCredentialGroupOAuthCallbackContract } from '@/lib/api/contracts/
 import { parseRequest } from '@/lib/api/server'
 import { auth } from '@/lib/auth'
 import { createAnonymousSession, ensureAnonymousUserExists } from '@/lib/auth/anonymous'
+import { isOAuthProviderEnabled } from '@/lib/auth/oauth-provider-feature'
 import { isAuthDisabled } from '@/lib/core/config/env-flags'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { isCredentialGroupOAuthState } from '@/lib/credential-groups/oauth-state'
@@ -186,5 +187,12 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     )
   }
 
+  if (OAUTH_PROVIDER_PROTOCOL_POST_PATHS.has(path) && !(await isOAuthProviderEnabled())) {
+    return NextResponse.json(
+      { error: 'OAuth provider is not enabled' },
+      { status: 404, headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' } }
+    )
+  }
+
   return betterAuthPOST(request)
 })