Google OAuth Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• apps/api/src/module/auth/services/google-auth.service.ts
• apps/portal/pages/oauth.tsx
• apps/portal/pages/auth/google-auth.tsx
• apps/portal/hooks/useGoogleDriveAuth.ts
• apps/portal/pages/auth/index.tsx
• apps/portal/pages/authorize.tsx
• apps/api/package.json
• apps/portal/package.json

Google OAuth is a core component of the Ever Rec platform, providing a secure and streamlined way for users to authenticate. It is used for both primary user login and for authorizing access to Google services, such as Google Drive. This integration spans across the web portal, browser extensions, and the desktop application, leveraging Firebase Authentication on the backend.

The system uses Google's OAuth 2.0 protocol to obtain identity tokens for authentication and authorization codes for API access. The frontend portal utilizes the @react-oauth/google library to facilitate the login process, while the NestJS backend API handles token validation, user provisioning, and session management.

Initial Setup

Before the Google OAuth functionality can be used, it must be configured in the Google Cloud Console and within the project's environment variables.

Sources: README.md

Google Cloud Console Steps

1. Navigate to the API & Services > Credentials page in the Google Cloud Console.
2. Select the Firebase project associated with this application.
3. Create new "OAuth 2.0 Client IDs" credentials.
4. Configure the OAuth consent screen with the required application details.
5. Download the client ID and secret.

Sources: README.md

Environment Variables

The following environment variables must be set in the respective application's environment file (e.g., apps/api/.env.dev, apps/portal/.env.local).

Variable	Application	Description
GOOGLE_CLIENT_ID	All	The OAuth 2.0 Client ID from Google Cloud.
GOOGLE_CLIENT_SECRET	All	The OAuth 2.0 Client Secret from Google Cloud.

Sources: README.md

Backend Authentication Flow

The backend API, built with NestJS, is responsible for processing Google credentials, managing user accounts in Firebase, and issuing custom session tokens.

Sources: apps/api/src/module/auth/services/google-auth.service.ts

GoogleAuthService

This service contains the primary logic for handling Google sign-in. It orchestrates interactions between Firebase Authentication, the application's user service, and the Firebase Realtime Database.

The following diagram illustrates the sequence of events when a user logs in with Google.

This diagram shows the backend flow for processing a Google login.

Sources: apps/api/src/module/auth/services/google-auth.service.ts:25-117

Key Methods

• processGoogleLogin(credentials: string):
  1. Receives the Google ID token (credentials) from the client.
  2. Calls firebaseAuthService.exchangeGoogleIdTokenWithFirebase to validate the token with Firebase.
  3. Uses the localId from the decoded token to check if the user exists via userService.getUserById.
  4. If the user does not exist, it creates a new Firebase user account using userService.createUser with details from the Google token (email, name, photo).
  5. It ensures the user's profile is present in the Firebase Realtime Database by calling userService.addUserToDb.
  6. Generates a custom authentication token for the client using userService.generateCustomToken.
  7. Returns a comprehensive payload to the client, including the customToken, user profile information, and Firebase tokens (idToken, refreshToken).

Sources: apps/api/src/module/auth/services/google-auth.service.ts:25-117

Frontend Authentication Flow

The frontend portal, built with Next.js and React, uses the @react-oauth/google library to initiate the Google login flow and handle the response.

Sources: apps/portal/pages/auth/index.tsx, apps/portal/package.json

Login Page (/auth)

The main authentication page integrates a GoogleBtn component that triggers the Google sign-in popup.

This diagram shows the user login flow starting from the portal UI.

Sources: apps/portal/pages/auth/index.tsx:71-82

The googleSubmit function on the authentication page receives the CredentialResponse from the Google login button and sends it to the backend for processing.

Re-authentication (/auth/google-auth)

A dedicated page exists for handling re-authentication scenarios, for example, when the browser extension requires the user to confirm their identity. It compares the email from a new Google login attempt with the email from the existing session token to ensure they match.

Sources: apps/portal/pages/auth/google-auth.tsx:19-32

Google Drive Integration

The platform integrates with Google Drive, allowing users to save their recordings and screenshots. This uses a separate OAuth flow with a different scope.

Sources: apps/portal/hooks/useGoogleDriveAuth.ts, apps/portal/pages/oauth.tsx

useGoogleDriveAuth Hook

This React hook encapsulates the logic for initiating the Google Drive authorization flow.

• It uses useGoogleLogin from @react-oauth/google.
• It configures the flow with specific parameters:
  • flow: 'auth-code': To get an authorization code instead of an ID token.
  • scope: 'https://www.googleapis.com/auth/drive': Requests permission to access Google Drive.
  • ux_mode: 'redirect': Redirects the user to Google's consent screen.
  • redirect_uri: Points to the /oauth page on the portal.

Sources: apps/portal/hooks/useGoogleDriveAuth.ts:19-27

OAuth Callback Page (/oauth)

This page handles the redirect from Google after the user grants permission.

This diagram shows the authorization code flow for Google Drive integration.

The page extracts the code from the URL query, sends it to the backend API endpoint completeOAuth, and upon success, stores the new Drive credentials and redirects the user.

Sources: apps/portal/pages/oauth.tsx:14-27

Desktop App Authorization Flow

A special authorize.tsx page facilitates passing OAuth credentials from the web-based login flow to the desktop application using a custom URL protocol.

1. The desktop app opens a browser window to the web portal for authentication.
2. After the user logs in, the portal redirects to the /authorize page with the OAuth tokens in the URL hash (e.g., #access_token=...).
3. The AuthorizePage component parses these tokens.
4. It constructs a deeplink URL with the custom protocol ever-rec://.
5. It attempts an automatic redirect to this deeplink, which opens the desktop application and passes the tokens.
6. If the automatic redirect fails, a button is displayed for the user to manually open the desktop app.

Sources: apps/portal/pages/authorize.tsx:29-54