Xác Thực Google

Mô Tả Tổng Quan

Tính năng Xác thực Google cung cấp xác thực và đăng ký dựa trên OAuth cho người dùng có tài khoản Google. Người dùng xác thực thông qua Google OAuth ở phía client, nhận được Firebase ID token, sau đó gửi token này đến API để xác minh và tạo phiên đăng nhập. Hệ thống sử dụng Firebase Authentication để xác minh token an toàn và quản lý người dùng. Đây là phương thức xác thực dựa trên OAuth không liên quan đến đăng ký email/mật khẩu truyền thống.

API: Google Authentication API

Biểu Đồ Hoạt Động

flowchart TD
    A[Người dùng khởi tạo xác thực Google] --> B[Google OAuth Flow ở Client]
    B --> C[Client nhận Firebase ID Token]
    C --> D{Gửi token đến API?}
    D -->|Có| E[Xác minh token với Firebase]
    D -->|Không| F[Chờ user action]
    F --> D
    
    E --> G{Token có hợp lệ?}
    G -->|Không| H[Trả về lỗi token]
    G -->|Có| I[Tìm người dùng theo Google UID]
    
    I --> J{Người dùng có tồn tại?}
    J -->|Không| K[Luồng Đăng Ký Google]
    J -->|Có| L[Luồng Đăng Nhập Google]
    
    K --> M[Tạo tài khoản người dùng mới]
    M --> N[Gán vai trò mặc định]
    N --> O[Tạo phiên và cookie]
    
    L --> P[Kiểm tra trạng thái người dùng]
    P --> Q{Người dùng có hoạt động?}
    Q -->|Không| R[Trả về lỗi không hoạt động]
    Q -->|Có| S[Tạo phiên và cookie]
    
    O --> T[Trả về phản hồi thành công]
    S --> T
    H --> U[Trả về lỗi xác thực]
    
    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

Biểu Đồ Tuần Tự

Luồng Đăng Ký Google

sequenceDiagram
    participant Client
    participant GoogleOAuth as Google OAuth Client
    participant GoogleController
    participant AuthService
    participant Firebase
    participant Database
    
    Note over Client,Database: Luồng Đăng Ký Google OAuth
    
    rect rgb(255, 243, 205)
    Note right of Client: Client-Side OAuth Flow
    Client->>GoogleOAuth: Khởi tạo Google Sign-In
    GoogleOAuth->>GoogleOAuth: Xử lý OAuth flow
    GoogleOAuth-->>Client: Trả về 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: Xác Thực Đầu Vào
    GoogleController->>GoogleController: Xác thực dữ liệu yêu cầu
    end
    
    rect rgb(200, 255, 255)
    Note right of GoogleController: Logic Nghiệp Vụ
    GoogleController->>AuthService: registerByGoogle(email, name, companyName, token)
    
    AuthService->>Firebase: verifyIdToken(token)
    Firebase-->>AuthService: Token đã xác minh + thông tin người dùng
    
    AuthService->>Database: Kiểm tra người dùng có tồn tại
    Database-->>AuthService: Người dùng không tìm thấy
    
    AuthService->>Database: Tạo người dùng từ dữ liệu Google
    Database-->>AuthService: Người dùng đã tạo
    
    AuthService->>Database: Gán vai trò nhóm mặc định
    Database-->>AuthService: Vai trò đã gán
    end
    
    rect rgb(230, 200, 255)
    Note right of AuthService: Tạo Phiên
    AuthService->>AuthService: createAuthCookieByUser()
    AuthService-->>GoogleController: Dữ liệu người dùng + cookie
    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 Lỗi Xác Thực
        GoogleController->>Client: 422 Validation Error
    else Email Đã Tồn Tại
        Database-->>AuthService: Email tồn tại
        AuthService-->>GoogleController: Email conflict
        GoogleController->>Client: 409 Conflict
    else Token Google Không Hợp Lệ
        Firebase-->>AuthService: Token verification failed
        AuthService-->>GoogleController: Authentication error
        GoogleController->>Client: 401 Unauthorized
    end
    end
    end

Các Bước

Quy Trình Đăng Ký Google

Bước 1: Client-Side Google OAuth

• Mô tả: Người dùng xác thực với Google ở phía client
• Hành động:
  • Client khởi tạo Google Sign-In
  • Google xử lý OAuth flow
  • Client nhận Firebase ID Token
  • Không có POST đến Firebase - chỉ nhận token

Bước 2: Gửi Dữ Liệu Đăng Ký

• Mô tả: Người dùng gửi đăng ký với thông tin xác thực Google
• Yêu cầu: POST /api/v1/general/auth/google/register
• Headers: firebase-token: {google_id_token}
• Dữ liệu: email, name, companyName từ tài khoản Google
• Xác thực: Các trường bắt buộc và định dạng

Bước 3: Xác Minh Token Google

• Mô tả: Xác thực người dùng thông qua Google OAuth
• Hành động:
  • Xác minh Google ID token với Firebase
  • Trích xuất thông tin người dùng đã xác minh
  • Đảm bảo tính xác thực của token

Bước 4: Kiểm Tra Sự Tồn Tại Của Người Dùng

• Mô tả: Xác minh người dùng chưa được đăng ký
• Hành động:
  • Truy vấn cơ sở dữ liệu cho email hiện có
  • Trả về lỗi nếu người dùng đã tồn tại
  • Tiếp tục đăng ký nếu là người dùng mới

Bước 5: Tạo Tài Khoản Người Dùng

• Mô tả: Tạo người dùng mới từ dữ liệu Google
• Hành động:
  • Lưu thông tin người dùng từ Google
  • Tạo ánh xạ Firebase UID
  • Đặt trạng thái tài khoản thành hoạt động

Bước 6: Gán Vai Trò Mặc Định

• Mô tả: Thiết lập thành viên nhóm ban đầu của người dùng
• Hành động:
  • Tạo bản ghi thành viên nhóm
  • Gán vai trò nhóm mặc định
  • Thiết lập quyền người dùng

Bước 7: Tạo Phiên

• Mô tả: Tự động đăng nhập người dùng mới
• Hành động:
  • Tạo cookie xác thực
  • Tạo trạng thái đã đăng nhập
  • Trả về dữ liệu người dùng với phiên

Xử Lý Lỗi

Ghi Chú Bổ Sung

• Client-Side OAuth: Google OAuth flow xảy ra hoàn toàn ở phía client
• Firebase Token: Client nhận Firebase ID token từ Google OAuth, không tạo token
• Token Verification: API chỉ xác minh token với Firebase, không tạo token mới
• No POST to Firebase: Hệ thống không gửi POST request đến Firebase để tạo token
• Security: Token được xác minh với Firebase để đảm bảo tính xác thực
• Flow: Client OAuth → Nhận Token → Gửi Token đến API → Xác minh → Tạo Session