fix: let deployments advertise offline_access so MCP sessions can refresh

MCP clients were being kicked back to an interactive login on a short
cycle, reporting "requires re-authorization (token expired)".

Cause: /.well-known/oauth-protected-resource advertised only
openid/profile/email plus the audience scope. A client requests exactly
the scopes it finds there, and Authentik issues a refresh token only when
offline_access is among them — so the client received an access token
with nothing to renew it with. Once that token aged out, re-authenticating
by hand was the only path forward.

This is the same trap the audience scope already documents one comment
further up: a scope missing from this document is a scope the client will
never ask for, however the IdP is configured.

Adds OIDC_OFFLINE_ACCESS (default false). Enabling it appends
offline_access to the advertised scopes.

Left opt-in rather than always-on because it is only half the fix — the
IdP also needs an offline_access scope mapping on the provider, and
advertising a scope the IdP doesn't offer risks an invalid_scope
rejection that would break authentication outright. A deployment turns
this on after configuring its IdP; README documents both halves and how
to verify each.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/web/app/.well-known/oauth-protected-resource/route.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+/**
+ * The resource metadata document is the ONLY way an MCP client learns which
+ * scopes to request. Authentik evaluates a scope mapping only when the client
+ * asks for that scope by name — so a scope missing from this document is a
+ * scope the client will never request, no matter how the IdP is configured.
+ *
+ * That is exactly how `offline_access` came to be missing: without it the IdP
+ * issues an access token and no refresh token, so the client cannot renew
+ * silently and the user is forced to re-authenticate every time the access
+ * token expires.
+ */
+
+async function fetchMetadata(): Promise<{ scopes_supported: string[] }> {
+  vi.resetModules();
+  const { GET } = await import("@/app/.well-known/oauth-protected-resource/route");
+  return (await GET().json()) as { scopes_supported: string[] };
+}
+
+afterEach(() => {
+  delete process.env.OIDC_OFFLINE_ACCESS;
+  delete process.env.OIDC_AUDIENCE_SCOPE;
+});
+
+describe("oauth-protected-resource metadata", () => {
+  test("omits offline_access by default, so deployments without the IdP mapping are unaffected", async () => {
+    const body = await fetchMetadata();
+
+    expect(body.scopes_supported).not.toContain("offline_access");
+  });
+
+  test("advertises offline_access when the deployment opts in", async () => {
+    process.env.OIDC_OFFLINE_ACCESS = "true";
+
+    const body = await fetchMetadata();
+
+    expect(body.scopes_supported).toContain("offline_access");
+  });
+
+  test("still advertises the audience scope when offline_access is enabled", async () => {
+    // Regression guard: the audience scope is what makes `aud` appear on the
+    // token at all. Dropping it would break authentication outright.
+    process.env.OIDC_OFFLINE_ACCESS = "true";
+
+    const body = await fetchMetadata();
+
+    expect(body.scopes_supported).toContain("aud-test-audience");
+    expect(body.scopes_supported).toEqual(
+      expect.arrayContaining(["openid", "profile", "email"]),
+    );
+  });
+
+  test("honours an explicit audience scope name alongside offline_access", async () => {
+    process.env.OIDC_OFFLINE_ACCESS = "true";
+    process.env.OIDC_AUDIENCE_SCOPE = "custom-aud-scope";
+
+    const body = await fetchMetadata();
+
+    expect(body.scopes_supported).toContain("custom-aud-scope");
+    expect(body.scopes_supported).toContain("offline_access");
+  });
+});

apps/web/app/.well-known/oauth-protected-resource/route.ts

@@ -21,13 +21,24 @@ export function GET() {
   const audienceScope =
     env().OIDC_AUDIENCE_SCOPE ?? `aud-${env().OIDC_AUDIENCE}`;
 
+  // Same mechanism as the audience scope, different consequence: a client
+  // only requests `offline_access` if it sees the name here, and without
+  // that request the IdP returns no refresh token — so the client cannot
+  // renew and the user gets kicked back to an interactive login whenever
+  // the access token expires.
+  //
+  // Opt-in, because the IdP needs a matching scope mapping; advertising one
+  // it doesn't offer can fail the whole authorization request.
+  const scopes = ["openid", "profile", "email", audienceScope];
+  if (env().OIDC_OFFLINE_ACCESS) scopes.push("offline_access");
+
   return NextResponse.json({
     resource,
     // The MCP application's issuer, which is not necessarily the Web UI's —
     // see mcpIssuer(). Advertising the wrong one sends clients to a discovery
     // document whose tokens this endpoint will then reject on `iss`.
     authorization_servers: [mcpIssuer()],  // as configured, slash and all
-    scopes_supported: ["openid", "profile", "email", audienceScope],
+    scopes_supported: scopes,
     bearer_methods_supported: ["header"],
     resource_documentation: `${resource}/`,
   });