Better Auth · Authentication · all subjects

social sign-on/oauth setup patterns

8 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

OAuth Popup plugin purpose and use cases

The OAuth Popup plugin enables popup-based OAuth sign-in where the OAuth flow runs in a popup and the completion page posts the session token back to the opener. This allows an app to sign in inside a cross-site iframe where its auth cookie is partitioned. For normal top-level apps, the redirect flow (signIn.social) is preferred; reach for the popup when a top-level redirect is not possible, such as in embedded or iframe scenarios.

OAuth Popup server setup with bearer plugin

To set up OAuth Popup on the server, import betterAuth, bearer, and oauthPopup from better-auth/plugins. Create an auth instance with oauthPopup() and bearer() plugins. The bearer plugin is required. Include trustedOrigins with the opener app origin(s) to specify which origins can receive the session token.

OAuth Popup client setup

To set up OAuth Popup on the client, import createAuthClient from better-auth/client and oauthPopupClient from better-auth/client/plugins. Create an auth client with baseURL pointing to the auth origin and include the oauthPopupClient() plugin.

OAuth Popup sign-in method

To initiate sign-in with the OAuth Popup plugin, use authClient.signIn.popup() with a provider parameter (such as 'github' for a standard provider or providerId for a genericOAuth provider) and a callbackURL parameter to specify the redirect destination after sign-in.

OAuth Popup bearer plugin requirement

The bearer plugin is required on the server. An embedded app authenticates with the handed-back token via Authorization: Bearer header, since its cookie is partitioned.

OAuth Popup trustedOrigins requirement

The trustedOrigins configuration must include the app (opener) origin. The popup only posts the token to a trusted origin.

OAuth Popup COOP headers requirement

The page that opens the popup must allow it with the header Cross-Origin-Opener-Policy: same-origin-allow-popups if it sets COOP at all. The auth API must not send a swap-triggering COOP on the callback, for example by disabling it in a security-headers middleware. COOP headers do not apply inside an iframe.

OAuth Popup session token security

The session token is posted to the opener via postMessage pinned to a trusted origin and stored in localStorage only when embedded. It should be treated like any bearer token: an XSS on the app origin can read it. Keep session lifetimes short and the app free of XSS vulnerabilities.

Give your agent this brain