Google

Instructions

Follow these instructions to configure Convex Auth to use Google OAuth in a development environment.

The instructions expect that you have a Google developer account. If you don't have one yet, be sure to do that first. Visit Google for Developers (opens in a new tab) to ensure that your developer account is ready to go.

Additionally, the instructions cover the full configuration of Google Auth for a Google Cloud project. If you are working with an existing project, it's possible that some of the steps below won't apply.

Create or open a Google Cloud project

Open the Google Auth Platform (opens in a new tab) overview and select or create a project.

Configure Google Auth for your project

Once you have a project created or selected, click the GET STARTED button on the Overview page.

Provide the App name which will be shown to users.

Select a User support email.

Click NEXT.

Choose whether you're creating an app for an Internal or External audience. If you're making a public application, choose External.

Click NEXT.

Enter email addresses for Contact Information.

Click NEXT.

Review the User Data Policy and check the box if you agree.

Click CONTINUE.

Click CREATE.

Configure audience for external app

If you chose an external app, click Audience in the left menu and add some email accounts of test users that you want to use to test your integration.

Configure an OAuth client

Click the Clients option in the left menu.

Click Create client

Select "Web Application" as the client type.

Choose a name - this won't be shown to users, it's just for your organizational purposes.

For Authorized JavaScript origins enter http://localhost:5173 (or whatever local address your development server uses)..

For the Authorized redirect URIs, first find the HTTP Actions URL for your Convex deployment. You can find that in the Convex dashboard (opens in a new tab) under Settings -> URL & Deploy Key -> Show development credentials.

Your HTTP Actions URL will match your Deployment URL, except it will end in .site instead of .cloud.

The full Authorized redirect URI will be your actions URL plus api/auth/callback/google. So if your actions URL is https://fast-horse-123.convex.site then your callback URL will be:

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

Click CREATE.

If you follow the steps above exactly, Google will render the text fast-horse-123.convex.site in their OAuth consent screen. If you're signed up for a Convex Pro account, you can configure Convex Auth in your production deployment to show a custom domain in that screen instead.

Set Convex environment variables for Google OAuth

Reopen the client configuration.

Open a terminal to your Convex application directory.

Environment variables can also be configured in the Convex dashboard (opens in a new tab) under Settings -> Environment variables.

Copy the Client ID value from the configuration page and supply it as the last argument to the following command (run in your terminal):

npx convex env set AUTH_GOOGLE_ID <yourgoogleclientid>

Then copy the Client secret value from the configuration page and supply it as the last argument to the following command (run in your terminal):

npx convex env set AUTH_GOOGLE_SECRET <yourgooglesecret>

Provider configuration in auth.ts

Add the provider config to the providers array in convex/auth.ts. The Google provider will read the client ID and secret that you supplied in the environment variables above.

convex/auth.ts

import Google from "@auth/core/providers/google";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [Google],
});

App integration

See the general OAuth instructions for how to add a sign-in button in your application.

GitHub Apple