# OAuth Sign-In

> Sign in with Google and other OAuth providers: credentials, redirect URIs, adding a provider, account linking and errors.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/oauth*

---

Users click "Continue with Google" on `/auth/sign-in` or `/auth/sign-up`, approve at Google, and come back signed in to `next` (or the app home). A new email gets an account on that first sign-in. The kit ships Google; any provider Better Auth supports takes one config entry.

## Turn On Google

A provider is on when both of its keys are set; there's no separate switch.

1. In the [Google Cloud console](https://console.cloud.google.com/apis/credentials), create an **OAuth client ID** of type **Web application**.
2. Add the **Authorized redirect URIs**, one per address the app runs on:
   - `http://localhost:5173/api/auth/callback/google` (`pnpm dev`)
   - `http://localhost:4173/api/auth/callback/google` (`pnpm preview`)
   - `https://app.example.com/api/auth/callback/google` (your `SITE_URL`)
3. Locally, put the keys in `apps/web/.env`:

   ```bash {% title="apps/web/.env" %}
   AUTH_GOOGLE_CLIENT_ID=1234.apps.googleusercontent.com
   AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
   ```

4. Deployed, set both as Worker secrets:

   ```bash
   pnpm --filter web exec void secret put AUTH_GOOGLE_CLIENT_ID
   pnpm --filter web exec void secret put AUTH_GOOGLE_CLIENT_SECRET
   ```

Sign-in with an ID token posted from the browser (Google One Tap and similar) is off (`disableIdTokenSignIn: true`); set `disableIdTokenSignIn: false` in an entry to use it.

Only one of the two set is a mistake, and it fails loudly: every request (every page, not only sign-in) answers 500 with `OAuth provider "google" needs AUTH_GOOGLE_CLIENT_SECRET` (or `_CLIENT_ID`) in the logs until both are set or both removed. The browser only learns which providers are on (`config.auth.providers.oAuth`, e.g. `[{ id: 'google' }]`); the keys stay on the server.

## Add a Provider

Any of Better Auth's [social providers](https://www.better-auth.com/docs/concepts/oauth) works. Adding one touches only your app's files, so kit updates never conflict with it. E.g. Discord:

1. Add its keys to `apps/web/env.ts` (your file, not `kit-env.ts`):

   ```ts {% title="apps/web/env.ts" %}
   import { defineEnv, string } from 'void/env';

   export default defineEnv({
     ...kitEnv,
     AUTH_DISCORD_CLIENT_ID: string().optional(),
     AUTH_DISCORD_CLIENT_SECRET: string().optional(),
   });
   ```

2. Add the entry in `apps/web/config/auth.config.server.ts` → `oAuthEntries`. The key is Better Auth's provider id:

   ```ts {% title="apps/web/config/auth.config.server.ts" %}
   const oAuthEntries: OAuthProviderEntries = {
     google: { … },
     discord: {
       clientId: env.AUTH_DISCORD_CLIENT_ID,
       clientSecret: env.AUTH_DISCORD_CLIENT_SECRET,
       name: 'Discord',
       logo: '/images/oauth/discord.svg',
     },
   };
   ```

3. Put the logo in `apps/web/public/images/oauth/` (SVG or WebP, square, about 36×36 px or larger; an SVG with `width` and `height` on its `<svg>`, not only a `viewBox`).

4. Register `https://<your SITE_URL>/api/auth/callback/discord` at the provider, and set the keys.

The button appears by itself, with the entry's `name` and `logo`. Provider options (scopes, Google's `hd` domain restriction, Microsoft's `tenantId`) go in the same entry; see Better Auth's page for the provider. The browser only gets each button's id, name and logo (`config.auth.providers.oAuth`), never the keys.

### Names and Logos

- **Shipped providers** need neither: Google, GitHub, Microsoft, Apple, Facebook and X (`twitter`) have a name and logo in the kit (`packages/auth/src/oauth-provider-display.ts`). Set `name` or `logo` in their entry to change them; don't edit the kit file.
- **No name:** the button shows the id, capitalized (`discord` → "Discord").
- **No logo, or one that fails to load:** the button shows a generic sign-in icon, never a broken image.
- **Dark mode:** a black logo (GitHub, Apple, X) disappears on a dark background. Give it two images, `logo: { light: '/images/oauth/acme.svg', dark: '/images/oauth/acme-dark.svg' }`, and the page shows the one for the current theme. Most brand marks (colored, like Google or Discord) read on both and need only one. For the dark variant, use the provider's official white mark from its brand assets; for a single-color SVG, a copy with `fill="#fff"` does it.

A new account needs an email the provider has verified: one it reports as unverified gets no account (`email_not_verified`), since whoever holds that provider account could otherwise keep a way into the address's account after its owner verifies it. Google, GitHub, Microsoft, Apple, Discord and X report it; Facebook usually doesn't, so its new users are refused. To trust such a provider anyway, set `emailVerified: true` in its entry's `mapProfileToUser`, knowing the risk above.

## Account Linking

When the provider's email already has an account, Better Auth's defaults decide:

| Existing account | Provider says the email is verified | Result |
|---|---|---|
| verified | yes | The provider is linked to it, the user is signed in and the owner gets "A sign-in method was added" |
| verified | no | Refused (`account_not_linked`) |
| never verified | either | Refused (`account_not_linked`) |
| linked before | either | Signed in |

Signed-in users link a provider from Settings → Security instead ([Security](../account/security#linked-accounts)): that flow allows a different email (`allowDifferentEmails`) because the signed-in session, fresh, is the proof of ownership. The option is not read when signing in.

The kit trusts no provider by name (`trustedProviders` is empty), so linking always needs both sides verified. An unverified account could belong to someone who registered the address in advance; linking would hand them the real owner's sign-in. The owner sees "An account with this email already exists…", and can sign in with email, or sign up again to replace the unverified account (see [Overview](./overview)).

Provider tokens are stored encrypted with `BETTER_AUTH_SECRET` (`account.encryptOAuthTokens`).

## Errors

A failed or cancelled sign-in returns to `/auth/sign-in?next=…&error=<code>`, and the page shows a translated message (`auth.oauth.*` in `packages/i18n/src/messages/en/auth.json`):

| Code | Message |
|---|---|
| `access_denied` | The user cancelled at the provider |
| `account_not_linked` | The email has an account that can't be linked (above) |
| `email_not_found` | The provider didn't share an email |
| `email_not_verified` | The provider hasn't verified the email, so no account is created |
| `state_not_found`, `state_mismatch`, … | The sign-in session expired or came from another browser: start again |
| anything else | The generic error |

The code table is `callbackErrorKey` in `packages/auth/src/errors.ts`. The provider's `error_description` is never shown: the provider (or whoever crafts the link) controls its text. A callback that fails before Better Auth knows the page to return to (no state) lands on `/auth/sign-in` too, not on Better Auth's own `/api/auth/error`.

`/sign-in/social` is limited to 10 a minute per IP.

## Testing

Unit tests in `packages/better-auth/src/__tests__/oauth.test.ts` run the whole callback against a mocked Google token endpoint: a new user, an unverified email, linking, both linking refusals, cancel and a forged callback. E2E runs with fake Google keys (`SIGN_IN_METHOD_ENV` in `tooling/scripts/src/preview-env.mjs`) and stops at Google: it checks the buttons, the redirect (client id, callback, state) and the cancelled callback. A real sign-in needs real keys; try it with `pnpm dev` and your own Google client.
