BNA

BNA UI
...

Google Sign-In

PreviousNext

Step-by-step guide to configuring Google as an OAuth provider for the Convex Auth starter — the Cloud project, the consent screen, the OAuth client, the .site callback URL, and what to do when the browser comes back to nothing.

The starter's Google button works as soon as the provider is configured on your Convex deployment. No code changes — it shares the browser flow with Apple.

Before you start

  • A Google account. Any account works; you do not need a paid plan or a verified domain to sign in during development.
  • A Convex deployment, so you have an HTTP Actions URL to point Google at. npx convex dev --once is enough — see the auth installation guide.

Create the OAuth client

Create or select a Google Cloud project

  1. Open the Google Cloud console and click Select a project in the top bar.
  2. Click New project in the dialog.
  3. Give the project a name. This one is internal — your users never see it.
  4. Click Create and wait for it to finish provisioning.
  5. Click Select a project again.
  6. Pick the project you just created.
Google Cloud console welcome page with the Select a project button highlightedSelect a project dialog with the New project button highlightedNew Project form with the project name filled in and the Create button highlightedBack on the welcome page, opening the project picker againSelecting the newly created project from the Recent tab

Open the Google Auth Platform

  1. From Quick access, click APIs & Services.
  2. In the left navigation, click OAuth consent screen.
  3. Click Get started.
Project dashboard with the APIs and Services quick-access card highlightedAPIs and Services with OAuth consent screen highlighted in the left navigationGoogle Auth Platform not configured yet, with the Get started button highlighted

Fill in the app information

  1. App name — this one is shown to users on the consent screen.
  2. User support email — pick one from the dropdown.
  3. Click Next.
Project configuration step 1, App Information, with app name and support email

Choose the audience

  1. Pick External unless this is a Workspace-only app. Internal is limited to accounts in your organization.
  2. Click Next.
Project configuration step 2, Audience, with External selected

Add contact information and create the configuration

  1. Enter one or more email addresses. Google uses these to notify you about project changes.
  2. Click Next.
  3. Check I agree to the Google API Services: User Data Policy.
  4. Click Continue.
  5. Click Create.
Project configuration step 3, Contact Information, with an email address enteredProject configuration step 4, Finish, with the policy agreement checked and Create highlighted

Create the OAuth client

  1. In the left navigation, click Clients.
  2. Click Create client.
  3. Set Application type to Web application. Web, not Android or iOS: the browser flow authenticates against Convex's HTTP Actions endpoint, which is a web endpoint.
  4. Give the client a name. This one is only used to identify it in the console.
OAuth Overview after configuration, with Clients highlighted in the left navigationEmpty Clients list with the Create client button highlightedCreate OAuth client ID form with Web application selected and a name entered

Find your Convex HTTP Actions URL

Leave that tab open and switch to the Convex dashboard.

  1. Open Settings.
  2. Open URL & Deploy Key.
  3. Copy the HTTP Actions URL. It ends in .site.
Convex deployment settings showing the HTTP Actions URL ending in .site

Add the authorized redirect URI

Back in the Google console:

  1. Under Authorized redirect URIs, click Add URI.
  2. Paste the HTTP Actions URL and append /api/auth/callback/google.
  3. Click Create.
{HTTP_ACTIONS_URL}/api/auth/callback/google

For example, if your HTTP Actions URL is https://fast-horse-123.convex.site:

https://fast-horse-123.convex.site/api/auth/callback/google

Authorized JavaScript origins can stay empty. The starter's flow never calls Google from a browser origin you control — it hands off to Convex's .site endpoint, which is already covered by the redirect URI.

Authorized redirect URIs with the Convex callback URL pasted in

Copy the client ID and secret

  1. Copy the Client ID from the confirmation dialog, then click OK.
  2. Back on the Clients list, click the client you just made.
  3. Under Client secrets, use the existing secret or click Add secret.
  4. Copy the Client secret.

Google no longer lets you view a secret after you leave the page, so copy it now — if you lose it, add a new one and delete the old.

OAuth client created dialog showing the Client IDOAuth 2.0 Client IDs list with the new client listedClient detail page with the Client secrets panel and Add secret button

Set the environment variables

From your project directory:

pnpm dlx convex env set AUTH_GOOGLE_ID your_client_id
npx convex env set AUTH_GOOGLE_SECRET your_client_secret
  1. Or paste them into the Convex dashboard under Settings → Environment Variables and click Save All.
Convex Environment Variables panel with AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET

The deep-link scheme

One more variable, and the one people forget: EXPO_URL is your app's deep-link scheme, and it is what lets Convex redirect back into the app after Google hands the browser back. It has to match the scheme in your app.json.

pnpm dlx convex env set EXPO_URL my-app://
Convex Environment Variables panel with EXPO_URL set to the app scheme

Without it the browser sheet closes and nothing happens — see the redirect allow-list.

Test it

pnpm dlx expo start

Tap Login with Google. A browser sheet opens, you pick an account, and it closes; the session lands and you're routed into the app.

What the starter does

components/auth/google.tsx
const redirectTo = makeRedirectUri();
 
const { redirect } = await signIn('google', { redirectTo });
 
if (Platform.OS === 'web') return;
 
const result = await openAuthSessionAsync(redirect!.toString(), redirectTo);
 
if (result.type === 'success') {
  const code = new URL(result.url).searchParams.get('code')!;
  await signIn('google', { code });
}

signIn('google', { redirectTo }) kicks off the flow and hands back the URL to open; the second signIn call, with the code Google returned, is what actually completes it. See authentication for how Apple reuses the same shape.

When it does not work

What you seeUsually
redirect_uri_mismatchThe .cloud URL was used instead of .site, or the path has a typo
Browser closes, nothing happensEXPO_URL/SITE_URL don't cover the redirect Convex sent back — see the redirect allow-list
"Access blocked: app not verified"Consent screen still in Testing and this account isn't a test user
Works after npx convex env set, still failsThe deployment needs a moment to pick up new env vars — retry once
Nothing changed after editing the OAuth clientGoogle warns it can take 5 minutes to a few hours for client settings to propagate

Next

ActionsApple Sign-In