Account Linking

gau allows users to connect multiple OAuth providers (e.g., GitHub and Google) to a single user account. This provides a seamless experience, allowing them to sign in with any of their linked providers to access the same account.

This can be done in two ways:

• Automatic Linking: gau can automatically link accounts based on a shared, verified email address when a user signs in.
• Manual Linking: Authenticated users can manually link or unlink providers from their account settings page.

Automatic Account Linking

gau has an automatic account linking feature, configured via the autoLink option in createAuth.

When an existing user signs in with a new provider, gau can automatically associate this new sign-in with their existing account.

How It Works

1. Check for Existing Account: When a user signs in, gau first checks if an account already exists for that user with the specific OAuth provider. If so, it logs them in.

2. Check for Email to Link: If no account is found for that provider, gau looks at the email address returned by the new OAuth provider. It then checks if any user in your database already has that same email address.

3. Link or Create:

   • If a user with that email already exists, gau will link the new OAuth sign-in to that existing user record.
   • If no user with that email is found, a new user is created.

This means a user can sign in with GitHub, sign out, and then sign back in with Google, and they will be logged into the same account, as long as both services use the same verified email address.

Configuration

You can control this behavior with the autoLink option in createAuth.

• 'verifiedEmail' (Default): Links accounts only if the email from the new provider is verified.
• 'always': Links accounts if the emails match, even if the new provider doesn’t verify the email.
• false: Disables automatic linking entirely. A new user is created for each new provider sign-in.

Manual Account Linking

In addition to automatic linking, gau provides functions for users to manually manage their linked accounts, for example from a profile or settings page.

The useAuth hook (available in client integrations) exposes linkAccount and unlinkAccount functions.

Configuration

You can control manual linking behavior with the allowDifferentEmails and updateUserInfoOnLink options in createAuth.

linkAccount

This function initiates the OAuth flow to connect an additional provider to the currently logged-in user’s account.

SvelteKit

+page.svelte

<script>
  import { useAuth } from '@rttnd/gau/client/svelte'
  const auth = useAuth()
</script>

<button onclick={() => auth.linkAccount('google')}>
  Connect Google Account
</button>

SolidStart

LinkButton.tsx

import { useAuth } from '@rttnd/gau/client/solid'

export function LinkButton() {
  const { linkAccount } = useAuth()

  return (
    <button onClick={() => linkAccount('google')}>
      Connect Google Account
    </button>
  )
}

unlinkAccount

This function removes a linked provider from the user’s account.

SvelteKit

+page.svelte

<script>
  import { useAuth } from '@rttnd/gau/client/svelte'
  const auth = useAuth()
</script>

<button onclick={() => auth.unlinkAccount('google')}>
  Disconnect Google Account
</button>

SolidStart

UnlinkButton.tsx

import { useAuth } from '@rttnd/gau/client/solid'

export function UnlinkButton() {
  const { unlinkAccount } = useAuth()

  return (
    <button onClick={() => unlinkAccount('google')}>
      Disconnect Google Account
    </button>
  )
}

gau prevents users from unlinking their last remaining account.

Caution

Unlinking Behavior

By default, gau allows linking accounts even if they have different primary email addresses. You can enforce matching emails during manual linking with the allowDifferentEmails: false configuration. When an account is unlinked, gau will currently reset the user’s email to null and emailVerified to false.

Because of this, it’s a good practice to prompt the user to sign in again after unlinking an account. A new sign-in will automatically re-populate the user’s primary email from one of the remaining linked accounts.

This behavior will be better and configurable in a future update.