OAuth Authentication Flow#

Better Auth routes all social/OAuth provider responses through a single callback endpoint — /callback/:id — that handles both GET and POST requests. POST requests are immediately redirected to GET to ensure cookies are set 1.

Every callback follows these steps before branching:

1. Parse state — extracts callbackURL, link, errorURL, newUserURL, requestSignUp, and idTokenNonce from the signed state cookie 2. State is parsed before provider errors are checked, so the stored errorURL is always available for redirects.
2. Exchange code for tokens — calls provider.validateAuthorizationCode() 3.
3. Fetch user profile — calls provider.getUserInfo() 4.
4. Branch: explicit linking (if link flag is set in state) vs. sign-in/registration.

Flow Diagram#

OAuth Provider → /callback/:id
                      │
              ┌───────┴────────┐
        link flag? No link
              │ │
   [linkOAuthAccount()] [handleOAuthUserInfo()]
    No session created │
                    ┌───────────┴───────────┐
             accountOwner found? No user found
                    │ │
          ┌─────────┴──────────┐ disableSignUp?
    account linked? email match? │ │
          │ │ [Error] [Register]
    [Sign-In] [Implicit Link]
                      (or blocked)

Path 1: Explicit Account Linking (link flag)#

When the state carries a link payload (set by authClient.linkSocial()), linkOAuthAccount() is called:

• Validates that the provider is trusted or the IdP email is verified 5
• Validates that emails match, unless account.accountLinking.allowDifferentEmails is true 6
• If the account row already exists, updates its tokens; otherwise creates a new account row via internalAdapter.createAccount() 7
• Optionally syncs provider profile to the user via applyUpdateUserInfoOnLink() when accountLinking.updateUserInfoOnLink is true
• Redirects to callbackURL — no session is created 8

Path 2 & 3: Sign-In / Registration via handleOAuthUserInfo()#

For non-link callbacks, handleOAuthUserInfo() drives the remaining branching.

User Lookup#

The function first calls internalAdapter.findAccountOwnerByKey({ providerId, accountId }) 9:

• owned — account row found; returns the linked user directly 10
• orphaned — account row exists but user row is missing; returns an error immediately 11
• No account match — falls back to email lookup via findUserByEmail() 12
• Nothing found → isRegister = true 13

Sign-In Path (account already linked)#

When the account is already linked (linkedAccount is set), the handler:

• Calls assertValidUserInfo() with action: "sign-in" — allowing plugins to reject sign-ins 14
• Refreshes tokens on the account row unless account.updateAccountOnSignIn is false; note: scope is intentionally not updated on sign-in 15
• Promotes emailVerified: true from the IdP to the local row if the local row was unverified 16
• If overrideUserInfoOnSignIn is set on the provider, overwrites name, image, and mapped profile fields — but never rebinds email or emailVerified identity 17

Implicit Linking Path (email match, no account row)#

When a user is found by email but no account row exists for the (providerId, accountId) pair, implicit linking runs — or is blocked 18:

When blocked, the handler returns { error: "account not linked" } and the callback redirects with ?error=account_not_linked. When all conditions pass, internalAdapter.linkAccount() creates the account row 19, and applyUpdateUserInfoOnLink() optionally copies profile fields if updateUserInfoOnLink: true 20.

Registration Path (isRegister = true)#

If disableSignUp is true (from provider.options.disableSignUp or provider.disableImplicitSignUp && !requestSignUp), returns { error: "signup disabled" } 21 22.

Otherwise, both the user row and account row are created atomically inside a transaction via runWithTransaction 23. If emailVerification.sendOnSignUp is enabled and the new user's email is unverified, a verification email is dispatched in the background 24.

Hook Execution Differences#

Database hooks (databaseHooks) fire at different points depending on the path. All .after hooks run post-transaction via queueAfterTransactionHook 25 26.

create.before returns false to abort (returning null) or { data } to merge additional fields 27.

Session Creation and Redirect#

After handleOAuthUserInfo() returns successfully, a session is created via internalAdapter.createSession(user.id) 28 and the session cookie is set 29. Redirect destination depends on isRegister 30:

• New user → newUserURL (if configured), else callbackURL
• Returning user → callbackURL

Explicit linking skips session creation entirely and redirects immediately to callbackURL 8.

Generic OAuth Plugin#

The genericOAuth plugin registers custom OAuth/OIDC providers as first-class social providers by prepending them to ctx.socialProviders during init 31. This means they share the same /callback/:id core endpoint — no plugin-specific routes are needed. The plugin supports OIDC discovery (discoveryUrl), custom token exchange (getToken), PKCE, and multiple tokenEndpointAuth methods (client_secret_post, client_secret_basic, private_key_jwt, none) 32.

Key Source Files#