MiniApp đăng nhập sử dụng tài khoản V-App

Khi người dùng truy xất vào 1 MiniApp sẽ phát sinh nhu cầu xác thực với hệ thống Backend của MiniApp thông qua ID của nền tảng V-App. Tài liệu này mô tả luồng đăng nhập và yêu cầu nghiệp vụ để thực hiện việc đó:

Tổng quan

Mô Tả Luồng

Hệ thống đăng nhập tuân theo trình tự sau (khớp với sơ đồ trên):

1. Người dùng vào MiniApp: Người dùng mở/ truy cập MiniApp.
2. Kiểm tra session: MiniApp kiểm tra session hiện tại.
   • Nếu đã có session: Người dùng tiếp tục sử dụng, không cần bước đăng nhập tiếp theo.
   • Nếu chưa có session: Thực hiện đăng nhập yên lặng (các bước 3–9, và nếu cần thì 3b–8b).
3. Lấy mã ủy quyền (đăng nhập yên lặng): MiniApp gọi getAuthCode({ scopes: ['auth'] }) không bật consent để lấy authCode. Scope auth cho phép xác thực mà không cần người dùng bấm đồng ý.
4. Gửi authCode lên Backend: MiniApp gửi authCode lên MiniApp Backend.
5. Đổi authCode lấy Access Token: MiniApp Backend gọi POST /oauth2/token/exchange tới Open APIs, nhận Access Token.
6. Lấy thông tin user cơ bản: MiniApp Backend lấy thông tin người dùng bằng Access Token.
7. Nhận V-App user_id: Open APIs trả về user_id (định danh người dùng trên V-App).
8. Xử lý theo trạng thái user:
   • Nếu V-App user_id đã tồn tại trong hệ thống: MiniApp Backend load thông tin đã lưu (bỏ qua bước 3b–8b).
   • Nếu V-App user_id chưa tồn tại (user mới):
     • 3b. MiniApp gọi getAuthCode({ scopes: ['profile', 'phone', 'email'] }) bật consent để người dùng đồng ý cấp thông tin chi tiết.
     • 4b. MiniApp gửi authCode mới lên MiniApp Backend.
     • 5b. Backend gọi POST /oauth2/token/exchange lấy Access Token mới.
     • 6b. Backend lấy thông tin chi tiết user (tên, SĐT, email).
     • 7b. Open APIs trả về user info chi tiết (user_id, name, phone, email).
     • 8b. MiniApp Backend tạo user mới và lưu thông tin.
9. Thiết lập session: MiniApp Backend đặt session / cookie đăng nhập và trả về cho MiniApp.
10. Sau khi đăng nhập: Người dùng thao tác trong MiniApp; MiniApp gửi yêu cầu nghiệp vụ kèm session, Backend truy vấn trạng thái và trả dữ liệu, MiniApp xử lý logic nghiệp vụ.

Các Thành Phần Chính

• MiniApp: Ứng dụng frontend mà người dùng tương tác
• MiniApp Backend: Ứng dụng phía server xử lý xác thực và logic nghiệp vụ
• Open APIs: Nền tảng API do V-App cung cấp

Các loại token

Mô tả các loại token xuất hiện trong luồng và vai trò của chúng:

• authCode (mã ủy quyền):

  • Nguồn: tạo bởi SDK trên MiniApp (getAuthCode()).
  • Mục đích: mã ngắn hạn mà MiniApp gửi cho MiniApp Backend để đổi lấy token truy cập tài nguyên.
  • Thời hạn: rất ngắn (one-time use). Không lưu trữ lâu trên client.
  • Lưu trữ: chỉ truyền qua kết nối TLS từ MiniApp tới Backend và dùng ngay trên server.

• Access Token (access_token):

  • Nguồn: trả về từ Open APIs sau khi Backend gọi POST /oauth2/token/exchange kèm authCode.
  • Mục đích: đại diện cho quyền truy cập tài nguyên của người dùng để Backend gọi OpenAPIs.
  • Thời hạn: ngắn đến vừa (tùy cấu hình Open APIs). Có thể kèm refresh mechanism.
  • Lưu trữ: chỉ lưu an toàn trên MiniApp Backend (server-side). Không gửi trực tiếp tới client.

• session cookie / session id / Token riêng của MiniApp Backend (cookie phiên đăng nhập):

  • Nguồn: do MiniApp Backend tạo và gửi về MiniApp sau khi đổi authCode và khởi tạo trạng thái đăng nhập.
  • Mục đích: duy trì phiên làm việc giữa MiniApp (browser/webview) và MiniApp Backend; xác thực các yêu cầu nghiệp vụ tiếp theo.
  • Thời hạn: tuỳ cấu hình backend (session TTL).
  • Lưu trữ: cookie an toàn (HttpOnly, Secure, SameSite phù hợp). Không chứa token nhạy cảm ở dạng plain text.