A production guide to user impersonation with Neon Auth (Better Auth) and Next.js, including the __Secure- cookie…
In-depth Next.js guides covering App Router, RSC, ISR, and deployment. Get code examples, optimization checklists, and prompts to accelerate development.
No spam. Unsubscribe anytime.
I was adding a "log in as this user" button to a multi-tenant Next.js app so a superadmin could see exactly what a customer sees. The impersonation call itself worked on the first try. The trouble started right after: I was signed in as the customer on one page, and one click later the app was showing me my own account again. It took a look at the raw cookies in the browser to find out why, and the cause was a one-line mistake that no type checker or test would ever have caught. This guide walks through the full implementation with Neon Auth (Better Auth under the hood), including that bug, so you can ship impersonation without losing an afternoon to it.
Neon Auth exposes an /admin/impersonate-user endpoint, but it only answers to a signed-in session whose user has the Neon role admin. In my app the roles that matter (organisation admin, driver, superadmin) live in my own Prisma User table, and every Neon user keeps the plain user role. If I gave superadmins the Neon admin role, that would be a second, parallel permission system to keep in sync, so I did not.
Instead the server signs in as a dedicated service account that does have the Neon admin role, caches that account's session cookie in memory, and uses it for every admin call (the same pattern detailed in our Neon Managed Better Auth in Next.js on Vercel setup guide and Stack Auth to Neon Auth migration). The impersonation step is one of those calls. Everything else in this guide is about what to do with the result.
The first piece is a small server-only function that asks Neon to create a session for a target user and hands back the session token. The subtle part is reading the response correctly, because Neon sends more than one Set-Cookie header.
impersonateAuthUser = (: ): <> => {
{ response } = (, {
: ,
: { userId },
});
token = response.
.()
.( header.()[])
.( cookie.()[].())
.( cookie.().().())
.();
(!token) {
();
}
token;
};
adminRequest is the helper that attaches the service account's cached session cookie and retries once if that session has expired. The response to the impersonation call first expires the service account's own session_token (an empty value) and then sets the new one for the impersonated user. My first version took the first session_token it saw, which is the empty one, and the impersonation silently produced a blank session. Taking the last non-empty value fixes that.
With a token in hand, the next question is where it goes in the browser without destroying your own session.
Impersonating means the browser must carry the target's session while you keep your own session safe somewhere, so you can come back. I park the superadmin's token in a separate cookie and put the impersonated token where the SDK expects to find it.
= ;
= ;
= ;
= * ;
cookieOptions = {
: ,
: ,
: ,
: ,
} ;
The SDK does not export its cookie names, so I mirror them by hand. The impersonation lifetime matches Neon's default of one hour, which also caps how long a forgotten impersonation can stay open. Now the action that starts it:
(): <<>> {
context = ();
(!(context) || context.) {
();
}
target = prisma..({
: { : userId, : },
: {
: ,
: ,
: ,
: ,
: ,
: ,
},
});
(!target || !target.) {
();
}
(target. === context.) {
();
}
(target. !== .) {
();
}
cookieStore = ();
ownToken = cookieStore.()?.;
(!ownToken) {
();
}
: ;
{
impersonatedToken = (target.);
} (error) {
.(, error);
(
error
? error.
: ,
);
}
cookieStore.(, ownToken, {
...cookieOptions,
: ,
});
cookieStore.(, impersonatedToken, {
...cookieOptions,
: ,
});
(cookieStore, );
.(, {
: context.,
: target.,
: target.,
: target.,
: target.,
});
(, , {
:
target. === .
?
: target. === .
?
: ,
});
}
The checks at the top do the security work. Only a superadmin may start, and only when not already impersonating, so sessions cannot be chained. The target must exist in your own table, be active, and not be yourself. Impersonating another superadmin is allowed because it grants nothing you do not already have. The write happens only after Neon has issued the new token, so a failed impersonation leaves your session untouched. The last call, expireCookie, removes the SDK's cached session data. That line looks harmless, and it is where the bug lives, so I will come back to it in Step 6.
Notice that the action returns a URL instead of calling redirect(). That is deliberate and also explained in Step 6. Before that, the rest of the app needs to know an impersonation is in progress.
Neon marks an impersonated session with an impersonatedBy field holding the id of the admin behind it. I read it in the same place the app already reads the current user and pass it into the auth context, so every layout and server action can see it.
// File: src/lib/auth/session.ts
const session = data.session as { impersonatedBy?: string | null } | undefined;
return {
id: user.id,
email: user.email,
name: user.name ?? null,
impersonatedBy: session?. ?? ,
};
One more place needs to respect it. My app activates invited users on their first login, which is a state change. An impersonating admin visiting an invite-pending account must not trigger that, so the activation is skipped when impersonatedBy is set:
// File: src/lib/auth/session.ts
// Impersonation must not change the target's state.
if (
prismaUser.status === UserStatus.INVITE_PENDING &&
!authUser.impersonatedBy
) {
// activate the user
}
With the flag available everywhere, the user interface can make the situation impossible to miss.
While impersonating, every page needs a persistent notice and a button to end it. I render a banner from a server component that returns nothing unless the session is impersonated, and mount it in each layout through the shell's banner slot.
() {
(!context.) {
;
}
user = prisma..({
: { : context. },
: { : , : , : },
});
name =
[user?., user?.].().() || user?.;
(
);
}
The banner must be mounted in every layout an impersonated user can reach. I mounted it in the admin and driver layouts first and forgot the superadmin layout, which mattered as soon as I allowed impersonating other superadmins: the session looked normal and had no way out. The button that ends the session is a small client component.
// File: src/components/impersonation/stop-impersonation-button.tsx
const handleStop = () => {
startTransition(async () => {
const result = ();
(result. && result.) {
..(result..);
;
}
toast.(result. ?? );
});
};
The button calls the stop action, which is the mirror image of the start action.
Stopping has three jobs: revoke the impersonated session on Neon, put the superadmin's own token back, and clear the impersonation cookies.
(): <
<>
> {
cookieStore = ();
ownToken = cookieStore.()?.;
(!ownToken) {
();
}
context = ().( );
impersonatedToken = cookieStore.()?.;
(impersonatedToken && context?.) {
(, {
: ,
: {
: ,
: ,
: (()).,
},
: ,
: ,
}).( {
.(, error);
});
}
cookieStore.(, ownToken, {
...cookieOptions,
: ,
});
(cookieStore, );
(cookieStore, );
.(, {
: context?. ?? ,
: context?. ?? ,
});
(, , {
: context
?
: ,
});
}
If there is no impersonator cookie the action returns an error without touching anything, and that behaviour is useful. It lets the ordinary sign-out button call the stop action first and fall back to a real sign-out, so pressing "Odjava" while impersonating ends the impersonation instead of logging the superadmin out entirely:
// File: src/lib/auth/sign-out.ts
export const signOutOrStopImpersonation = (): <> => {
stopResult = ().( );
(stopResult?. && stopResult.) {
..(stopResult..);
;
}
authClient.();
;
};
This is the complete flow, and on paper it is done. In practice it had one bug left, and both the start and stop actions contain the line responsible.
After starting an impersonation I landed on the impersonated user's dashboard with the banner showing. Then I clicked a link to another section, and the app was showing my own superadmin account. Reloading did not help. The banner was correct on one page and wrong on the next.
My first theory was the client router cache, because the sidebar prefetches links before you switch accounts. That is a real problem in general, and it is why the actions return a URL and the callers use window.location.assign instead of a server-side redirect(): a full page load discards everything the router cached for the previous session. It was not the cause here, though. The behaviour survived the change.
The answer was in the browser's cookie list. Next to the impersonated session_token there was a __Secure-neon-auth.local.session_data cookie, and decoding its JWT payload showed my own user with impersonatedBy: null. Neon Auth's server SDK caches the session in that signed cookie, and when it is valid and a session token is present, getSession returns the cached payload without asking Neon anything. So any request that carried the stale cache resolved to my own account, even though the token next to it belonged to someone else.
My code was already trying to delete that cache. The problem is how it deleted it:
// File: src/lib/auth/impersonation.ts (before)
cookieStore.delete(SESSION_DATA_COOKIE);
cookieStore.delete() sends a Set-Cookie header with an expiry in the past, but it does not include the Secure attribute. Browsers refuse to modify a cookie whose name starts with __Secure- unless the header that does it is also marked Secure. The delete was therefore ignored without any error, and the cache stayed. The fix is to expire the cookie with a normal set call that carries the same attributes it was created with:
// File: src/lib/auth/impersonation.ts
// `cookieStore.delete()` omits `Secure`, which browsers reject for `__Secure-`
// cookies, so the cookie would survive. Expire it explicitly instead.
const expireCookie = (
cookieStore: Awaited<ReturnType<typeof cookies>>,
name: string,
) => cookieStore.set(name, "", { ...cookieOptions, maxAge: 0 });
I use this helper for the session cache on both start and stop, and for the impersonator cookie on stop. The stop path had the same flaw in reverse: without it, ending an impersonation could leave the impersonated user's cached session behind and sign the superadmin in as the wrong person.
The lesson is broader than this app. Any cookie with a __Secure- or __Host- prefix has to be written and cleared with Secure set, and Next.js delete() will not do that for you.
I set out to add impersonation to a Next.js app on Neon Auth and hit an odd failure where the app flipped back to my own account. The implementation is a service account that asks Neon for an impersonated session, a server action that parks your own token in a separate cookie and installs the impersonated one, an impersonatedBy flag that drives a banner in every layout, and a stop action that restores your session. The bug that cost me the most time came from the SDK's cached session cookie surviving a cookieStore.delete() that browsers ignore for __Secure- cookies, and it is fixed by expiring such cookies with Secure and .
You can now build a safe "log in as user" feature on Neon Auth and avoid the stale-session trap. Let me know in the comments if you have questions, and subscribe for more practical development guides.
Thanks, Matija
maxAge: 0