Guides

Sign in with Google & GitHub

Google and GitHub are built in. This guide covers registering your app, the two routes to write, and the mistakes that produce a redirect back with no session.

Yatta ships an OAuth subsystem with Google and GitHub pre-registered. You add credentials, write two routes, and identity linking, PKCE and state validation are handled for you.

What happens under the hood

State is a random token signed with HMAC. The provider returns it unchanged; a mismatch is rejected, which is what blocks CSRF on the callback.
PKCE is used for Google. A verifier is generated, hashed into a challenge, and checked when the code is exchanged.
Identity linking: if an account with the same email already exists, it is reused instead of creating a duplicate.
The session is issued by Yatta — the provider's token is never handed to your client.

Register your app

Two applications, one per provider.

Google — console.cloud.google.comtext

11. Google Cloud Console → Credentials → Create Credentials → OAuth client22. Application type: Web application33. Authorised redirect URIs:4     http://localhost:4000/auth/callback/google5     https://yourdomain.com/auth/callback/google64. Copy the Client ID and Client Secret

GitHub — github.com/settings/developerstext

11. Settings → Developer settings → OAuth Apps → New OAuth App22. Homepage URL: https://yourdomain.com33. Authorization callback URL:4     http://localhost:4000/auth/callback/github5     https://yourdomain.com/auth/callback/github64. Generate a client secret

Set the callback URL

The redirect URI must match exactly — scheme, host, path and trailing slash. Use localhost in development and your real domain in production.

Environmentbash

1APP_URL=http://localhost:4000        # development2APP_URL=https://yourdomain.com       # production3 4GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com5GOOGLE_CLIENT_SECRET=xxxxx6 7GITHUB_CLIENT_ID=Ov23li...8GITHUB_CLIENT_SECRET=xxxxx

Google

No code required — the provider is pre-registered and reads its credentials from the environment variables above.

yatta/func/auth.tsts

1export const auth = createAuth({2  secret: process.env.AUTH_SECRET!,3  store: new SQLiteAuthStore(),4  email: { mailer, appUrl: process.env.APP_URL! },5});   // google is registered automatically

GitHub

Also automatic, same environment variables:

yatta/func/auth.tsts

1// github is registered automatically too.2// The scaffolded schema already has an `identities` table for this.

The two routes you need

Start sends the browser to the provider; callback receives them back and issues a session.

yatta/backend/auth/[provider]/start.tsts

1import { API, createAPI } from "yatta/api";2import { auth } from "../../../func/auth";3 4const api = createAPI();5 6api.get(async (ctx) => {7  const provider = ctx.params.provider;          // "google" | "github"8  const redirectUri = `${process.env.APP_URL}/auth/callback/${provider}`;9 10  const { url, state, codeVerifier } =11    await auth.oauth.getAuthorizationUrl(provider, redirectUri);12 13  // Persist state (and PKCE verifier) for the callback to check.14  await Bun.write(`/tmp/oauth-${state}.json`, JSON.stringify({15    state,16    codeVerifier: codeVerifier ?? null,17  }));18 19  return Response.redirect(url, 302);20});21 22export default api;

yatta/backend/auth/callback/[provider].tsts

1import { API, createAPI } from "yatta/api";2import { auth } from "../../../func/auth";3 4const api = createAPI();5 6api.get(async (ctx) => {7  const provider = ctx.params.provider;8  const url = new URL(ctx.req.url);9 10  const code = url.searchParams.get("code")!;11  const state = url.searchParams.get("state")!;12 13  // Restore what we saved when the flow started.14  const saved = await Bun.file(`/tmp/oauth-${state}.json`).json().catch(() => null);15  if (!saved) return API.json({ error: "Unknown state" }, { status: 400 });16 17  const result = await auth.oauth.handleCallback({18    provider,19    code,20    expectedState: saved.state,21    redirectUri: `${process.env.APP_URL}/auth/callback/${provider}`,22    codeVerifier: saved.codeVerifier ?? undefined,23    req: ctx.req,24  });25 26  // Issues a Yatta session; the provider token stays server-side.27  return result.toResponse ?? API.json({ user: result.user });28});29 30export default api;

Warning

The saved state must survive the redirect. A file in /tmp works for a single process but not behind a load balancer. Use the cache store instead — see Cache.

Account linking

By default a matching email links to the existing user rather than creating a second account. Pass linkToUserId to attach an additional provider to a user who is already signed in.

link a second providerts

1const result = await auth.oauth.handleCallback({2  provider,3  code,4  expectedState,5  redirectUri,6  // The currently signed-in user7  linkToUserId: currentUserId,8});

yatta/backend/auth/link.tsts

1import { API, createAPI } from "yatta/api";2import { auth } from "../../func/auth";3 4const api = createAPI();5 6api.get(async (ctx) => {7  const provider = ctx.url.searchParams.get("provider") ?? "google";8  const session = await getSession(ctx);9 10  if (!session) return API.json({ error: "Unauthorized" }, { status: 401 });11 12  const redirectUri = `${process.env.APP_URL}/auth/callback/${provider}`;13  const { url, state, codeVerifier } =14    await auth.oauth.getAuthorizationUrl(provider, redirectUri);15 16  // Carry the user id through the round trip so the callback knows17  // which account to attach this provider to.18  const signed = `${state}.${await sign(state + session.user.id)}`;19  await saveOAuthState(state, { codeVerifier, userId: session.user.id });20 21  return Response.redirect(url.replace(/state=[^&]*/, `state=${signed}`), 302);22});23 24export default api;

Other providers

Anything speaking OAuth 2.0 can be added. Pass the endpoints and a mapper that normalises the profile.

Discordts

1auth.oauth.registerProvider({2  name: "discord",3  clientId: process.env.DISCORD_CLIENT_ID!,4  clientSecret: process.env.DISCORD_CLIENT_SECRET!,5  authorizeUrl: "https://discord.com/oauth2/authorize",6  tokenUrl: "https://discord.com/api/oauth2/token",7  userInfoUrl: "https://discord.com/api/users/@me",8  scopes: ["identify", "email"],9  mapProfile: (data) => ({10    id: String(data.id),11    email: String(data.email ?? ""),12    name: String(data.global_name ?? data.username),13  }),14});

Set usePkce: true for providers that support it. It is always safe to enable.

Common problems

redirect_uri_mismatch — the URI registered with the provider differs by even a trailing slash. Copy it exactly.
Invalid or forged OAuth state — the state you stored was not found on callback. This is the anti-CSRF check working; it usually means the saved state expired or was stored per-process while the callback landed on another.
Empty session after callback — return result.toResponse; it carries the session cookie.
Google consent screen not published — an app in “Testing” mode only allows accounts you list as test users.

See also Authentication for the surrounding APIs, and Protect a route for using the session.