SSO & Identity

app.mcv.network là Identity Provider trung tâm cho hệ sinh thái MCV. MatchingVietnam, mcv.network/WordPress, Zenify và các sản phẩm tiếp theo không tự quản lý profile riêng; họ dùng SSO handoff và profile contract từ Business OS.

Mục Tiêu

• Đăng nhập một lần tại app.mcv.network, sau đó sử dụng được ở MatchingVietnam, WordPress/mcv.network, Zenify và các hệ thống cùng domain trust.
• Profile cập nhật tại /profile trên Business OS là nguồn dữ liệu chuẩn cho toàn hệ thống.
• Các hệ thống vệ tinh chỉ giữ bản cache profile cần thiết, không trở thành source of truth.
• Business OS tự tạo hoặc cập nhật user/account dựa trên SSO payload từ hệ thống cũ trong giai đoạn chuyển đổi.
• Không truyền password, không dùng shared session/cookie giữa hai domain.

Role Chuẩn

Tầng identity chỉ còn ba nhóm:

Role	Ý nghĩa	Mapping nội bộ
merchant	Chủ doanh nghiệp/chủ merchant, có thể bán sản phẩm sau khi xác minh và mua dịch vụ trên MCV	Account có storefront hoặc năng lực bán
customer	Người mua/khách hàng/người tiêu dùng cuối	Account chỉ có quyền mua
admin	Quản trị viên hệ thống MCV	admin hoặc manager trong Business OS

Các capability chi tiết như bán sản phẩm, bán media inventory, bán dịch vụ, quản lý storefront vẫn nằm trong account.capabilities.

Luồng SSO Trung Tâm

sequenceDiagram
    participant User as User
    participant Client as Matching/WordPress/Zenify
    participant App as app.mcv.network

    User->>Client: Click Login / Dashboard
    Client-->>User: Redirect to /sso/launch/{client}
    User->>App: Login if needed
    App->>App: Build signed profile payload
    App-->>User: Redirect to client callback
    User->>Client: Submit payload + signature
    Client->>Client: Verify signature + TTL
    Client-->>User: Start local session

Endpoint Chuẩn

Endpoint	Vai trò
GET /sso/launch/{client}	Business OS phát hành signed SSO payload cho client đã cấu hình
GET /sso/profile	Trả profile chuẩn của user đang đăng nhập trên Business OS
GET /sso/matching/callback	Legacy inbound handoff từ MatchingVietnam về Business OS trong giai đoạn chuyển đổi
GET https://zenify.cx/sso/mcv/callback	WordPress marketing callback, verify payload và đồng bộ user profile vào WordPress local user
POST /integrations/zenify/signups	Zenify app đồng bộ signup/trial thành user, account và service contract trong Business OS

client hiện hỗ trợ: matchingvietnam, mcv_network, zenify.

Payload Chuẩn

Field	Ý nghĩa
iss, aud	Issuer và audience của client
iat, exp, nonce	Chống replay, giới hạn TTL
client	Client được cấp payload
profile.id, profile.email, profile.name	Danh tính user
profile.role	merchant, customer hoặc admin
profile.account.capabilities	Quyền chi tiết để client bật/tắt tính năng
profile.profile_updated_at	Mốc thời gian để client refresh cache

Env

Business OS:

MCV_IDENTITY_ISSUER=https://app.mcv.network
MCV_IDENTITY_SSO_SECRET=...
MCV_IDENTITY_SSO_TTL=300
MCV_SSO_MATCHING_CALLBACK_URL=https://matchingvietnam.com/sso/mcv/callback
MCV_SSO_WORDPRESS_CALLBACK_URL=https://mcv.network/sso/mcv/callback
MCV_SSO_ZENIFY_CALLBACK_URL=https://zenify.cx/sso/mcv/callback

MatchingVietnam legacy inbound:

MCV_MATCHING_SSO_SECRET=...
MCV_MATCHING_SSO_TTL=300

Client secret nên tách riêng theo từng client ở production. TTL mặc định 300 giây.

Yêu Cầu Cho Các Hệ Thống Vệ Tinh

• Login/Dashboard CTA trỏ về https://app.mcv.network/sso/launch/{client}.
• Trang profile local không cho sửa dữ liệu gốc, chỉ dẫn về https://app.mcv.network/profile.
• zenify.cx dùng WordPress cho marketing; web.zenify.cx giữ CRM app hiện tại.
• Signup từ web.zenify.cx phải gọi /integrations/zenify/signups để Business OS trở thành customer master data và Billing OS cho Zenify.
• Khi nhận payload, client phải verify HMAC signature, iss, aud, exp, nonce.
• Client cache profile ngắn hạn và refresh khi profile_updated_at thay đổi.

English Summary

app.mcv.network is the central Identity Provider. Satellite systems redirect users to Business OS for login, receive a short-lived HMAC-signed profile payload, and keep only a local session/cache. The identity role model is reduced to merchant, customer, and admin, while detailed product/service/storefront permissions remain account capabilities.