Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(auth): answer the four most repeated SSR auth questions (#50289)

Miranda Limonczenkoe8547352c529
diff --git a/apps/docs/content/_partials/auth_methods.mdx b/apps/docs/content/_partials/auth_methods.mdx
index f8ab5ddbad6..5cc7dd123f8 100644
--- a/apps/docs/content/_partials/auth_methods.mdx
+++ b/apps/docs/content/_partials/auth_methods.mdx
@@ -2,7 +2,7 @@ The Supabase Auth SDK contains three different functions for authenticating user
### Summary of the methods
-- Use [`getClaims`](/docs/reference/javascript/auth-getclaims) to protect pages and user data. It reads the access token from storage and verifies it. Locally via the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) and a cached JWKS endpoint when the project uses asymmetric signing keys (the default for new projects), or by calling `getUser` solely to validate when symmetric keys are in use. The returned claims always come from decoding the JWT, not from a user lookup.
+- Use [`getClaims`](/docs/reference/javascript/auth-getclaims) to protect pages and user data. It reads the access token from storage and verifies it. Locally via the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) and a cached JWKS endpoint when the project uses asymmetric signing keys (the default for new projects), or by calling `getUser` solely to validate when symmetric keys are in use. The returned claims always come from decoding the JWT, not from a user lookup. When the access token is close to expiring, `getClaims` refreshes the session before it verifies, which is how a server-rendered session stays alive.
- [`getUser`](/docs/reference/javascript/auth-getuser) makes a network call to the project's Auth instance to get the user record, which includes the most up-to-date information about the user at the cost of a network call.
- [`getSession`](/docs/reference/javascript/auth-getsession) when you need the raw session (the access token, refresh token, and expiry). For example to forward the access token to another service. The session is loaded directly from local storage and isn't re-validated against the Auth server, so the embedded user object shouldn't be trusted on its own when storage is shared with the client (cookies, request headers). To verify identity, validate the access token with `getClaims`, or call `getUser` for a fresh, server-confirmed user record.
diff --git a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
index 95a20d859d0..8bcb4678e2f 100644
--- a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
+++ b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
@@ -209,10 +209,16 @@ To access Supabase from a Next.js app, you need 2 types of Supabase clients:
Since Next.js Server Components can't write cookies, you need a [Proxy](https://nextjs.org/docs/app/getting-started/proxy) to refresh expired Auth tokens and store them.
+<Admonition type="note">
+
+On Next.js 15 and earlier, a `proxy.ts` file is never called, so sessions never refresh and users get signed out. Next.js renamed this file in version 16. Before that, it's `middleware.ts` and the function is `export async function middleware`. The Supabase code inside it is the same either way.
+
+</Admonition>
+
The Proxy is responsible for:
1. Refreshing the Auth token by calling `supabase.auth.getClaims()`.
-2. Passing the refreshed Auth token to Server Components, so they don't attempt to refresh the same token themselves. This is accomplished with `request.cookies.set`.
+2. Passing the refreshed Auth token to Server Components, so they don't attempt to refresh the same token themselves. It is what keeps users signed in. This is accomplished with `request.cookies.set`.
3. Passing the refreshed Auth token to the browser, so it replaces the old token. This is accomplished with `response.cookies.set`.
<Accordion>
@@ -242,6 +248,19 @@ The Proxy is responsible for:
</AccordionItem>
+ <AccordionItem
+ header="Why does refreshing in two places sign users out?"
+ id="double-refresh"
+ >
+
+ A refresh token can generally be used only once, with two exceptions. Supabase allows a short window in which the same token can be presented again, which covers the normal SSR round trip. It also returns the active token when the parent of the active token is presented, which covers a client that never received the previous response. A reuse attempt that matches neither exception revokes the whole session.
+
+ This is hard to trace, because it looks like users being signed out at random rather than an error in your code.
+
+ See [refresh token reuse detection](/docs/guides/auth/sessions#what-is-refresh-token-reuse-detection-and-what-does-it-protect-from).
+
+ </AccordionItem>
+
</Accordion>
Create a `lib/supabase` folder at the root of your project, or inside the `./src` folder if you are using one, with a file for each type of client. Then copy the lib utility functions for each client type.
@@ -265,6 +284,20 @@ Create a `lib/supabase` folder at the root of your project, or inside the `./src
The code adds a [matcher](https://nextjs.org/docs/app/api-reference/file-conventions/proxy#matcher) so the Proxy doesn't run on routes that don't access Supabase.
+Return the `supabaseResponse` object that `setAll` last built. An earlier response doesn't carry the refreshed cookies, so the user is signed out on the next request.
+
+When you need to return a different response, copy the cookies and the cache headers onto it first:
+
+```ts
+const myNewResponse = NextResponse.next({ request })
+myNewResponse.cookies.setAll(supabaseResponse.cookies.getAll())
+for (const header of ['cache-control', 'expires', 'pragma']) {
+ const value = supabaseResponse.headers.get(header)
+ if (value) myNewResponse.headers.set(header, value)
+}
+return myNewResponse
+```
+
<Admonition type="danger">
Anyone can forge the session cookie, so trusting it without verification lets an attacker render another user's page. Always use `supabase.auth.getClaims()` to protect pages and user data.
diff --git a/examples/prompts/nextjs-supabase-auth.md b/examples/prompts/nextjs-supabase-auth.md
index ada3886c617..ae0cd72a835 100644
--- a/examples/prompts/nextjs-supabase-auth.md
+++ b/examples/prompts/nextjs-supabase-auth.md
@@ -121,7 +121,9 @@ export async function createClient() {
## CORRECT PROXY IMPLEMENTATION
-```typescript
+If the project uses `src/app` or `src/pages`, put this file in `src`, at the same level as the routing directory. Otherwise, put it at the project root, next to `package.json`. It must be named `proxy.ts`. On Next.js 15 and earlier, name it `middleware.ts` and export `middleware` instead of `proxy`.
+
+```typescript proxy.ts
import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'