Google Authentication

Overview Description

The Google Authentication feature provides OAuth-based authentication and registration for users with Google accounts. Users authenticate through Google OAuth on the client side, receive a Firebase ID token, then send this token to the API for verification and session creation. The system uses Firebase Authentication to securely verify tokens and manage users. This is the OAuth-based authentication method that does not involve traditional email/password registration.

API: Google Authentication API

Activity Diagram

flowchart TD
    A[User initiates Google auth] --> B[Google OAuth Flow on Client]
    B --> C[Client receives Firebase ID Token]
    C --> D{Send token to API?}
    D -->|Yes| E[Verify token with Firebase]
    D -->|No| F[Wait for user action]
    F --> D
    
    E --> G{Token valid?}
    G -->|No| H[Return token error]
    G -->|Yes| I[Find user by Google UID]
    
    I --> J{User exists?}
    J -->|No| K[Google Registration Flow]
    J -->|Yes| L[Google Login Flow]
    
    K --> M[Create new user account]
    M --> N[Assign default roles]
    N --> O[Create session & cookies]
    
    L --> P[Check user status]
    P --> Q{User active?}
    Q -->|No| R[Return inactive error]
    Q -->|Yes| S[Create session & cookies]
    
    O --> T[Return success response]
    S --> T
    H --> U[Return auth error]
    
    style A fill:#e1f5fe
    style T fill:#c8e6c9
    style H fill:#ffcdd2
    style R fill:#ffcdd2
    style U fill:#ffcdd2
    style B fill:#fff3cd
    style C fill:#fff3cd

Sequence Diagram

Google Registration Flow

sequenceDiagram
    participant Client
    participant GoogleOAuth as Google OAuth Client
    participant GoogleController
    participant AuthService
    participant Firebase
    participant Database
    
    Note over Client,Database: Google OAuth Registration Flow
    
    rect rgb(255, 243, 205)
    Note right of Client: Client-Side OAuth Flow
    Client->>GoogleOAuth: Initialize Google Sign-In
    GoogleOAuth->>GoogleOAuth: Process OAuth flow
    GoogleOAuth-->>Client: Return Firebase ID Token
    end
    
    rect rgb(200, 255, 200)
    Note right of Client: API Registration Flow
    
    Client->>GoogleController: POST /api/v1/general/auth/google/register
    Note over Client,GoogleController: {email, name, companyName} + firebase-token header
    
    rect rgb(200, 230, 255)
    Note right of GoogleController: Input Validation
    GoogleController->>GoogleController: Validate request data
    end
    
    rect rgb(200, 255, 255)
    Note right of GoogleController: Business Logic
    GoogleController->>AuthService: registerByGoogle(email, name, companyName, token)
    
    AuthService->>Firebase: verifyIdToken(token)
    Firebase-->>AuthService: Token verified + user info
    
    AuthService->>Database: Check if user exists
    Database-->>AuthService: User not found
    
    AuthService->>Database: Create user from Google data
    Database-->>AuthService: User created
    
    AuthService->>Database: Assign default group role
    Database-->>AuthService: Role assigned
    end
    
    rect rgb(230, 200, 255)
    Note right of AuthService: Session Creation
    AuthService->>AuthService: createAuthCookieByUser()
    AuthService-->>GoogleController: User data + cookies
    end
    
    GoogleController->>Client: 201 Created + Set-Cookie headers
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: Error Handling
    rect rgb(255, 230, 230)
    alt Validation Error
        GoogleController->>Client: 422 Validation Error
    else Email Already Exists
        Database-->>AuthService: Email exists
        AuthService-->>GoogleController: Email conflict
        GoogleController->>Client: 409 Conflict
    else Invalid Google Token
        Firebase-->>AuthService: Token verification failed
        AuthService-->>GoogleController: Authentication error
        GoogleController->>Client: 401 Unauthorized
    end
    end
    end

Steps

Google Registration Process

Step 1: Client-Side Google OAuth

• Description: User authenticates with Google on the client side
• Action:
  • Client initializes Google Sign-In
  • Google processes OAuth flow
  • Client receives Firebase ID Token
  • No POST to Firebase - only receive token

Step 2: Submit Registration Data

• Description: User submits registration with Google credentials
• Request: POST /api/v1/general/auth/google/register
• Headers: firebase-token: {google_id_token}
• Data: email, name, companyName from Google account
• Validation: Required fields and format

Step 3: Verify Google Token

• Description: Authenticate user through Google OAuth
• Action:
  • Verify Google ID token with Firebase
  • Extract verified user information
  • Ensure token authenticity

Step 4: Check User Existence

• Description: Verify user is not already registered
• Action:
  • Query database for existing email
  • Return error if user already exists
  • Proceed with registration if new user

Step 5: Create User Account

• Description: Create new user from Google data
• Action:
  • Store user information from Google
  • Generate Firebase UID mapping
  • Set account status to active

Step 6: Assign Default Roles

• Description: Set up user's initial group membership
• Action:
  • Create group membership record
  • Assign default group role
  • Establish user permissions

Step 7: Create Session

• Description: Automatically log in the new user
• Action:
  • Generate authentication cookies
  • Create logged-in state
  • Return user data with session

Error Handling

Additional Notes

• Client-Side OAuth: Google OAuth flow occurs entirely on the client side
• Firebase Token: Client receives Firebase ID token from Google OAuth, does not create token
• Token Verification: API only verifies token with Firebase, does not create new tokens
• No POST to Firebase: System does not send POST requests to Firebase to create tokens
• Security: Token is verified with Firebase to ensure authenticity
• Flow: Client OAuth → Receive Token → Send Token to API → Verify → Create Session