BE-5: Implement Google OAuth Authentication and User Management

[tecnodeveloper]

BE-5: Implement Google OAuth Authentication and User Management

Description

Implement Google OAuth authentication using Supabase Authentication to allow users to securely sign in to the Multi-Turn AI Chatbot. Configure the complete authentication flow, including Google login, session management, protected API access, user profile creation, and logout functionality.

This issue establishes the application's authentication layer. After successful login, authenticated users should have their profile created (or retrieved) in the database and be able to access protected chatbot features in subsequent development tasks.

---

User Story

Given that a user wants to access the chatbot

When the user signs in using their Google account

Then the application should authenticate the user, create or retrieve their profile, establish a secure session, and allow access to protected chatbot functionality.

---

Tasks

1. Configure Google OAuth

• Create a Google Cloud project
• Configure OAuth Consent Screen
• Create OAuth Client Credentials
• Configure Authorized Redirect URIs
• Configure Authorized JavaScript Origins
• Obtain Client ID and Client Secret

---

2. Configure Supabase Authentication

• Enable Google Authentication Provider
• Add Google Client ID
• Add Google Client Secret
• Configure Redirect URL
• Verify authentication provider settings

---

3. Configure Environment Variables

Add authentication-related configuration.

• Configure Supabase URL
• Configure Supabase API Keys
• Configure Google OAuth credentials
• Configure application callback URL
• Validate authentication configuration

Example

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

NEXT_PUBLIC_SITE_URL=http://localhost:3000

---

4. Create Authentication Service

Create a reusable authentication service.

Tasks

• Create login function
• Create logout function
• Create session retrieval function
• Create current user function
• Create authentication helper utilities

Example

services/
    auth.service.ts

---

5. Implement Google Login

Develop Google Sign-In functionality.

• Redirect user to Google authentication
• Handle OAuth callback
• Retrieve authenticated user
• Handle authentication errors
• Verify successful login

---

6. Create User Profile Management

After successful authentication:

• Check whether the user already exists
• Create a new user if not found
• Update user information on subsequent logins
• Store profile in the Users table

Fields

• Google ID
• Name
• Email
• Profile Image
• Last Login Timestamp

---

7. Session Management

Configure authentication sessions.

• Retrieve active session
• Maintain authenticated session
• Handle expired sessions
• Refresh session automatically
• Destroy session during logout

---

8. Protect Backend API Routes

Ensure only authenticated users can access protected APIs.

• Create authentication middleware
• Validate user session
• Reject unauthorized requests
• Return appropriate HTTP status codes

Example response

{
    "success": false,
    "message": "Unauthorized"
}

---

9. Create Authentication API Endpoints

Prepare authentication-related endpoints.

Examples

GET /api/auth/session

POST /api/auth/logout

GET /api/auth/user

Tasks

• Return authenticated session
• Return current user
• Handle logout requests
• Handle authentication errors

---

10. Handle Authentication Errors

Implement proper error handling.

• Login cancelled
• Invalid OAuth response
• Session expired
• Unauthorized access
• Network failures
• Invalid callback

---

11. Verify User Persistence

Ensure authenticated users are correctly stored.

• Verify first login creates user
• Verify repeated login does not duplicate user
• Verify user profile updates
• Verify database consistency

---

12. Security Validation

• Verify secure authentication flow
• Verify protected routes
• Verify session security
• Verify unauthorized users cannot access APIs
• Verify logout invalidates session

---

13. Documentation

• Document Google OAuth configuration
• Document Supabase Authentication setup
• Document environment variables
• Document authentication flow
• Document protected routes
• Document troubleshooting steps

---

Acceptance Criteria

• Google OAuth is successfully configured.
• Users can sign in using Google.
• User profiles are automatically created or retrieved.
• Authentication sessions are maintained correctly.
• Logout functionality works correctly.
• Protected backend APIs require authentication.
• Duplicate users are not created.
• Authentication errors are handled gracefully.
• Documentation is completed.

---

Testing Steps

1. Configure Google OAuth credentials.
2. Configure Supabase Authentication.
3. Start the Next.js application.
4. Click "Sign in with Google."
5. Authenticate with a Google account.
6. Verify successful redirection.
7. Verify a user record is created in Supabase.
8. Sign out.
9. Verify the session is removed.
10. Attempt to access a protected API without authentication.
11. Verify an Unauthorized response is returned.
12. Sign in again and verify the existing user profile is reused.
13. Confirm no duplicate user records are created.

---

Definition of Done

• Google OAuth authentication is fully implemented.
• Supabase Authentication is configured.
• User profiles are stored in the database.
• Authentication sessions are managed securely.
• Protected API routes are enforced.
• Login and logout functionality operate correctly.
• Authentication flow has been tested successfully.
• Documentation is complete.