github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-08-31 12:32:52 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

[PR #8481] docs: rewrite browser extension guide with OAuth strategies #16249

New Issue
Open
opened 2026-04-13 10:27:56 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-13 10:27:56 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/better-auth/better-auth/pull/8481
Author: @Marve10s
Created: 3/7/2026
Status: 🔄 Open

Base: main ← Head: docs/browser-extension-oauth-guide

📝 Commits (1)

  • cda990e docs: rewrite browser extension guide with OAuth strategies

📊 Changes

1 file changed (+588 additions, -149 deletions)

View changed files

📝 docs/content/docs/guides/browser-extension-guide.mdx (+588 -149)

📄 Description

Summary

Rewrites the browser extension guide to cover social OAuth sign-in, which is the primary pain point for extension developers using Better Auth.

  • Keeps and improves the existing basic setup section (auth client, manifest, trustedOrigins)
  • Adds two OAuth strategies for extensions:
    • Strategy 1: chrome.identity.launchWebAuthFlow — for providers that support the implicit flow (Google, GitHub, Microsoft). Uses ID token exchange via signIn.social({ idToken }).
    • Strategy 2: Website Bridge — for providers that require response_mode=form_post (Apple). Opens a tab on the developer's website, runs standard OAuth there, and messages the session back via chrome.runtime.sendMessage.
  • Adds sections on service worker keep-alive, cookie SameSite configuration, content script authentication, and troubleshooting common issues
  • Framework-agnostic — works with WXT, Plasmo, CRXJS, or vanilla MV3

Details

The previous guide was Plasmo-specific and only covered basic session auth (email/password). It did not address social OAuth, which fails in extensions because popup redirects destroy the extension context and chrome-extension:// is not a valid OAuth redirect URI.

This rewrite documents two battle-tested patterns for solving this, with complete code examples for the service worker, popup, manifest configuration, and server setup.

Summary by cubic

Rewrites the Browser Extension Guide to add MV3‑safe OAuth for Chrome and Firefox. Covers Google/Microsoft via chrome.identity.launchWebAuthFlow and a Website Bridge for Apple and others, with clear setup, security, and troubleshooting.

  • New Features
    • Setup essentials: install better-auth; add host_permissions; set server trustedOrigins with the exact extension ID; add identity; pin the extension ID via manifest key; register the redirect URI (trailing slash); CSP connect-src; use a Web application OAuth client.
    • Strategy 1 (Google/Microsoft): chrome.identity.launchWebAuthFlow + OIDC ID token exchange via signIn.social({ idToken, disableRedirect, requestSignUp }) with state/nonce; persist session in chrome.storage.local; use Bearer tokens (server Bearer plugin).
    • Strategy 2 (Apple/GitHub): Website Bridge using externally_connectable, start/callback pages, strict sender origin/extensionId/message validation, runtime messaging, tab cleanup, and a 3‑minute timeout.
    • Best practices: service worker keep‑alive with a long‑lived port; prefer Bearer over cookies (if cookies, set SameSite=None; Secure); proxy content script requests via the service worker; Firefox notes (browser.identity, extensions.allizom.org); fixes for redirect_uri_mismatch, prod cookie issues, and SW lifetime; works with WXT/Plasmo/CRXJS.

Written for commit cda990e3d5. Summary will update on new commits.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/better-auth/better-auth/pull/8481 **Author:** [@Marve10s](https://github.com/Marve10s) **Created:** 3/7/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/browser-extension-oauth-guide` --- ### 📝 Commits (1) - [`cda990e`](https://github.com/better-auth/better-auth/commit/cda990e3d5e61326369a8a9f629344db27c9fbb8) docs: rewrite browser extension guide with OAuth strategies ### 📊 Changes **1 file changed** (+588 additions, -149 deletions) <details> <summary>View changed files</summary> 📝 `docs/content/docs/guides/browser-extension-guide.mdx` (+588 -149) </details> ### 📄 Description ## Summary Rewrites the browser extension guide to cover social OAuth sign-in, which is the primary pain point for extension developers using Better Auth. - Keeps and improves the existing basic setup section (auth client, manifest, trustedOrigins) - Adds two OAuth strategies for extensions: - **Strategy 1: `chrome.identity.launchWebAuthFlow`** — for providers that support the implicit flow (Google, GitHub, Microsoft). Uses ID token exchange via `signIn.social({ idToken })`. - **Strategy 2: Website Bridge** — for providers that require `response_mode=form_post` (Apple). Opens a tab on the developer's website, runs standard OAuth there, and messages the session back via `chrome.runtime.sendMessage`. - Adds sections on service worker keep-alive, cookie `SameSite` configuration, content script authentication, and troubleshooting common issues - Framework-agnostic — works with WXT, Plasmo, CRXJS, or vanilla MV3 ## Details The previous guide was Plasmo-specific and only covered basic session auth (email/password). It did not address social OAuth, which fails in extensions because popup redirects destroy the extension context and `chrome-extension://` is not a valid OAuth redirect URI. This rewrite documents two battle-tested patterns for solving this, with complete code examples for the service worker, popup, manifest configuration, and server setup. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Rewrites the Browser Extension Guide to add MV3‑safe OAuth for Chrome and Firefox. Covers Google/Microsoft via `chrome.identity.launchWebAuthFlow` and a Website Bridge for Apple and others, with clear setup, security, and troubleshooting. - **New Features** - Setup essentials: install `better-auth`; add `host_permissions`; set server `trustedOrigins` with the exact extension ID; add `identity`; pin the extension ID via manifest `key`; register the redirect URI (trailing slash); CSP `connect-src`; use a Web application OAuth client. - Strategy 1 (Google/Microsoft): `chrome.identity.launchWebAuthFlow` + OIDC ID token exchange via `signIn.social({ idToken, disableRedirect, requestSignUp })` with state/nonce; persist session in `chrome.storage.local`; use Bearer tokens (server `Bearer` plugin). - Strategy 2 (Apple/GitHub): Website Bridge using `externally_connectable`, start/callback pages, strict sender origin/`extensionId`/message validation, runtime messaging, tab cleanup, and a 3‑minute timeout. - Best practices: service worker keep‑alive with a long‑lived port; prefer Bearer over cookies (if cookies, set `SameSite=None; Secure`); proxy content script requests via the service worker; Firefox notes (`browser.identity`, `extensions.allizom.org`); fixes for `redirect_uri_mismatch`, prod cookie issues, and SW lifetime; works with WXT/Plasmo/CRXJS. <sup>Written for commit cda990e3d5e61326369a8a9f629344db27c9fbb8. Summary will update on new commits.</sup> <!-- End of auto-generated description by cubic. --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-13 10:27:56 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No labels pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
GiteaMirror ninjasurge (Kaehlen Rog)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#16249