OAuth

Make sure you're done with setup before configuring authentication methods

This authentication method has two steps:

The user clicks on a button to sign-in with a third-party (GitHub, Google, Apple etc.)
The user authenticates on the third-party website and is redirected back to your app and signed in

Convex Auth ensures a secure exchange of secrets between the third-party provider and your backend.

Providers

Convex Auth implements configuration via Auth.js (opens in a new tab) "provider" configs. These JS objects define how the library interfaces with an OAuth provider.

You can use any of the 80 OAuth providers preconfigured by Auth.js, including GitHub, Google, Apple, Facebook, etc.

You can find the list of available providers and more details about each configuration in the sidebar of Auth.js docs (opens in a new tab).

Choose an OAuth provider (for example GitHub) and follow the guide below.

Ignore the "database provider" configuration in Auth.js docs. Your Convex backend is your database!

Are you setting up OAuth for the first time? We recommend using GitHub.

Github has better-than-most configuration DX, even if it is not a very good choice for apps targeting the general population.

Google, which is very popular among users, unfortunately has a somewhat complicated OAuth setup and documentation. Apple is even worse.

Setup

Callback URL

After you sign up as a developer with the provider you usually create an "app" (or similar) to store your OAuth configuration.

Among other things you might need to configure you will usually need to specify a "callback" URL, and potentially other URLs/domains.

The origin (domain) of the callback URL for Convex Auth is your backend's HTTP Actions URL, which you can find on your Convex dashboard (opens in a new tab). It matches your CONVEX_URL except for the the top-level domain being .site instead of .cloud.

For example, if your deployment name was fast-horse-123, then your HTTP Actions URL would be https://fast-horse-123.convex.site and your callback URL for GitHub would be:

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

Environment variables

Configure the relevant environment variables for a given OAuth provider, as per Auth.js docs (opens in a new tab), on your Convex backend.

Setting environment variables Convex docs (opens in a new tab).

For example for GitHub you can run (with your own values):

npx convex env set AUTH_GITHUB_ID yourgithubclientid
npx convex env set AUTH_GITHUB_SECRET yourgithubsecret

Also check that the SITE_URL variable has the correct port number configured.

Provider configuration

Add the provider config to the providers array in convex/auth.ts.

Import Auth.js providers from @auth/core/providers. For example for GitHub:

convex/auth.ts

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

Add sign-in button

Now you can trigger the OAuth sign-in flow from a button click via the Convex Auth signIn function.

The first argument to the function is the provider ID, which unless customized is a lowercase version of the provider name. For example for GitHub:

src/SignIn.tsx

import { useAuthActions } from "@convex-dev/auth/react";
 
export function SignIn() {
  const { signIn } = useAuthActions();
  return (
    <button onClick={() => void signIn("github")}>Sign in with GitHub</button>
  );
}

Check out the example repo (opens in a new tab) for a more polished UI.

You can control which page the user will be redirected to after the sign-in by passing a redirectTo param to the signIn function. See redirect callback.

When you're done configuring your chosen authentication methods, learn how to use authentication in your frontend and backend in Authorization.

Production setup

It's usually not possible to share the same OAuth provider "app", the entity configured on the third-party dashboard, between your development and production environments.

In development your app is usually running on localhost, while in production it will be hosted on a public server and have a proper assigned URL.

Therefore you will have to create a separate "app" on the third-party dashboard for each environment, and configure the callback URL and environment variables accordingly.

Don't forget to also configure your SITE_URL.

Retrieving other profile information

By default, only name, email and image sourced from the OAuth profile are saved in the users table.

You can find the logic for sourcing these fields here (opens in a new tab).

You can customize this logic via the profile method on the OAuth provider config:

convex/auth.ts

import GitHub from "@auth/core/providers/github";
import { convexAuth } from "@convex-dev/auth/server";
 
export const { auth, signIn, signOut, store } = convexAuth({
  providers: [
    GitHub({
      profile(githubProfile, tokens) {
        return {
          id: githubProfile.id,
          name: githubProfile.name,
          email: githubProfile.email,
          image: githubProfile.picture,
          githubId: githubProfile.id,
        };
      },
    }),
  ],
});

The example above adds a githubId field. You must customize your schema to include this field.

To implement the profile method correctly you must understand the profile information the particular OAuth provider returns. Consult their documentation.

The method must return an id field with a unique ID, which is used to identify the account.

Configuration Magic Links