methods/google/server

The google sign-in method, exported at @convex-dev/auth/methods/google/server.

Type Aliases

GoogleOptions

type GoogleOptions = object;

App-defined config for setting up the google method.

Properties

Property	Type	Description
allowedRedirectOrigins	string[]	Origins redirectTo may point at, e.g. ["https://app.example.com"] for open-redirect prevention.
component	ComponentApi	The Google oauth component instance, i.e. components.authGoogle.

---

GoogleProfile

type GoogleProfile = Infer<typeof vGoogleProfile>;

Variables

vGoogleProfile

const vGoogleProfile: VObject<{
  email?: string;
  emailVerified: boolean;
  id: string;
  name?: string;
  picture?: string;
}, {
  email: VString<string | undefined, "optional">;
  emailVerified: VBoolean<boolean, "required">;
  id: VString<string, "required">;
  name: VString<string | undefined, "optional">;
  picture: VString<string | undefined, "optional">;
}, "required", "id" | "email" | "name" | "emailVerified" | "picture">;

The account profile that the google method produces. Google is OIDC, so identity comes from validated id_token claims. This is the exact shape the mapping emits, so the app can validate against it precisely.

Functions

normalizeGoogleProfile()

function normalizeGoogleProfile(claims): object;

Map validated Google id_token claims to GoogleProfile. Google returns an id_token, so claims is always present here. A missing one is a bug.

Parameters

Parameter	Type
claims	OidcClaims | undefined

Returns

object

email?

optional email?: string;

emailVerified

emailVerified: boolean;

id

id: string;

name?

optional name?: string;

picture?

optional picture?: string;

---

setupGoogle()

function setupGoogle<UsersTable>(core, options): object;

Built-in sign-in method for Google. Wire it up with the Google oauth component:

const auth = setupConvexAuth({ component: components.auth });
export const { signOut, refreshSession, isAuthenticated } = auth;

export const { startSignInWithGoogle, completeSignInWithGoogle } = setupGoogle(auth, {
  component: components.authGoogle,
  allowedRedirectOrigins: ["https://app.example.com", "http://localhost:5173"],
}).attachUserCallbacks({ createUser: internal.users.createUserGoogle });

Setup:

1. Install the component in convex.config.ts under httpPrefix: "/oauth/google", binding Google's CLIENT_ID and CLIENT_SECRET.
2. Register <site-url>/oauth/google/callback as the redirect URI with Google.

The httpPrefix alone determines the callback URL.

Type Parameters

Type Parameter
UsersTable extends string

Parameters

Parameter	Type
core	AuthCore<UsersTable>
options	GoogleOptions

Returns

attachUserCallbacks()

attachUserCallbacks(callbacks): object;

Supply the app's user callbacks (see UserCallbacks for how their args must be declared) and get the functions of this method to export.

Parameters

Parameter	Type
callbacks	UserCallbacks<"google", { email?: string; emailVerified: boolean; id: string; name?: string; picture?: string; }, UsersTable>

Returns

object

completeSignInWithGoogle

completeSignInWithGoogle: RegisteredMutation<"public", {
  code: string;
  state: string;
}, Promise<
  | {
  status: "complete";
  tokens: {
     accessToken: string;
     refreshToken: string;
     refreshTokenExpiresAt: number;
     userId: string;
  };
}
  | {
  status: "error";
  userError: {
     error: "INVALID_CODE";
  };
}>> = completeSignIn;

startSignInWithGoogle

startSignInWithGoogle: RegisteredMutation<"public", {
  redirectTo: string;
}, Promise<{
  redirect: string;
  state: string;
}>> = startSignIn;