Setting Up Google OAuth 2.0 Credentials

Hello! Welcome to your first lesson on mastering TanStack Start.

This lesson marks the beginning of Module 5: OAuth 2.0 Integration with Google. Over the next few lessons, we'll implement a complete "Sign in with Google" feature in our server-rendered application.

Today, we'll tackle the foundational first step. The learning outcome for this lesson is to configure Google OAuth 2.0 client credentials and redirect URIs in the application's environment. This involves setting up a project in the Google Cloud Console, generating a unique Client ID and Client Secret for our application, and securely storing them as environment variables.

Let's get started.

1. The OAuth 2.0 Flow: A Quick Overview

Before we jump into the Google Cloud Console, it's helpful to understand the basic concept of OAuth 2.0. At its core, OAuth 2.0 is a protocol that allows a user to grant a third-party application (like ours) limited access to their data on another service (like Google) without sharing their password.

The main actors in this process are:

• Resource Owner: The end-user who owns the data.
• Client: Our web application that wants to access the user's data.
• Authorization Server: Google's server that authenticates the user and issues access tokens.
• Resource Server: Google's server that hosts the user's data (e.g., Google Profile API).

Our goal in this module is to have our Client (the TanStack Start app) get an access token from Google's Authorization Server so it can fetch profile information from the Resource Server on behalf of the Resource Owner (the user).

Today, we are registering our Client with the Authorization Server.

2. Creating Google OAuth Credentials

The first practical step is to navigate the Google Cloud Console to create the necessary credentials. This process involves creating a project, configuring a consent screen that users will see, and finally generating the Client ID and Secret.

The following video provides a clear, concise walkthrough of this entire process. We will go through it step-by-step.

Now, let's break down the key steps shown in the video and what they mean for our application.

Step 1: Create a Project and Configure the OAuth Consent Screen

As shown from the start of the video until 01:24, you need to:

1. Go to console.cloud.google.com and create a new project.
2. Navigate to the "OAuth consent screen" section.
3. Choose External for the user type. This allows any user with a Google account to use your app. The "Internal" option is only available for Google Workspace accounts and restricts access to users within your organization.
4. Fill in the required app information (app name, user support email, developer contact).
5. During development, you can add specific Google accounts as Test users (as shown at 01:24). This means only these users can go through the OAuth flow until your app is verified and published by Google. This is a critical step for testing.

Step 2: Create the OAuth 2.0 Client ID

This is the most important part of the process, covered from 01:48 in the video. Here, you are telling Google about your specific application.

When you create the credentials, you'll need to configure two important fields:

1. Authorized JavaScript origins: This field specifies the domains from which your application can initiate requests to Google's OAuth server. For our local development environment using TanStack Start (which typically runs on Vite), this will be your local server's address.

   • Example: http://localhost:5173

2. Authorized redirect URIs: This is a critical security feature. It's a whitelist of URLs to which Google is allowed to redirect the user after they have authenticated. If the redirect_uri in the request doesn't exactly match one of the URLs on this list, Google will show an error.

   • For our server-side flow, this URI will point to an API route on our server that will handle the response from Google. We will build this route in the next lesson.
   • For now, let's define it as: http://localhost:5173/api/auth/google/callback

It's crucial that these URIs are configured correctly. Google enforces strict validation rules for them.

After clicking "Create", you will be presented with your Client ID and Client Secret.

• Client ID: A public identifier for your application.
• Client Secret: A confidential value that must be kept secure. Never expose this in your client-side code or commit it to version control.

3. Configuring Your TanStack Start Environment

Now that you have your credentials, you need to make them available to your application in a secure way. The standard practice is to use environment variables.

In your TanStack Start project's root directory, create a file named .env if it doesn't already exist. Add your credentials to this file. It's also a good practice to store the redirect URI here so it can be easily changed for different environments (development vs. production).

.env

# Google OAuth Credentials
GOOGLE_CLIENT_ID="YOUR_CLIENT_ID_FROM_GOOGLE_CONSOLE"
GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET_FROM_GOOGLE_CONSOLE"
GOOGLE_REDIRECT_URI="http://localhost:5173/api/auth/google/callback"

Make sure to add .env to your .gitignore file to prevent these secrets from being committed.

TanStack Start, using Vinxi, automatically loads these variables and makes them available to your server-side code (like server functions and route loaders) via process.env. We will use process.env.GOOGLE_CLIENT_ID and process.env.GOOGLE_CLIENT_SECRET in the upcoming lessons to interact with Google's APIs.

Conclusion

In this lesson, we completed the essential setup for integrating Google OAuth.

Key Takeaways:

• Every application using Google OAuth needs a project in the Google Cloud Console.
• The OAuth consent screen is what users see when your app requests permission to access their data. During development, you must add test users to be able to use the flow.
• You need to create OAuth 2.0 client credentials for a "Web application", which provides a Client ID and a Client Secret.
• The Authorized redirect URI is a crucial security measure that whitelists the endpoints Google can send users back to after authentication. It must exactly match the URI you use in your code.
• Sensitive credentials like the Client Secret must be stored securely using environment variables (.env file) and should never be committed to your repository.

You are now fully prepared for the next step. In the next lesson, we will use these credentials to implement the server-side logic to initiate the OAuth authorization code flow with PKCE. We'll create the "Sign in with Google" button and the server route that redirects the user to Google's login page.