Skip to content

Route BFF ​

Route Nitro mà @tasco-fe/nuxt-layer-base mang theo. Trình duyệt chỉ gọi các route này, không gọi thẳng IAM hay backend. Luồng tổng thể: BFF: /api/** đi đâu và Phiên đăng nhập.

MethodĐường dẫnFile trong layerViệc
Mọi method/api/**server/api/[...].tsChuyển tiếp tới backend, gắn token của phiên
POST/auth/loginserver/routes/auth/login.post.tsĐổi tài khoản lấy token, tạo phiên
GET/auth/sessionserver/routes/auth/session.get.tsNgười dùng của phiên hiện tại
GET/auth/clientsserver/routes/auth/clients.get.tsDanh sách ứng dụng cho form đăng nhập
POST/auth/otp/sendserver/routes/auth/otp/send.post.tsGửi OTP qua Telegram
GET/auth/logoutserver/routes/auth/logout.get.tsXoá phiên rồi chuyển hướng

GET /auth/login không phải route server mà là trang Vue app/pages/auth/login.vue — cùng đường dẫn, khác method.

Lỗi do chính các route này ném ra có dạng lỗi của h3: mã HTTP ở statusCode, thông báo tiếng Việt ở statusMessage. Phía client đọc qua AppError (status, message) — xem AppError & phân loại.

Chống CSRF ​

Middleware server/middleware/csrf.ts chặn request ghi (mọi method trừ GET, HEAD, OPTIONS) vào /api/** và /auth/** khi chúng đến từ trang khác. Cookie SameSite=lax không đủ: "site" tính theo tên miền gốc, nên một subdomain khác cùng site vẫn gửi được request kèm cookie phiên.

RequestKết quả
Sec-Fetch-Site: same-origin (hoặc none)Qua — không phụ thuộc host sau reverse proxy
Origin trùng host của app (xét cả X-Forwarded-Host) hoặc nằm trong NUXT_CSRF_ALLOWED_ORIGINSQua
Không có cả Origin lẫn Sec-Fetch-Site (client không phải trình duyệt: server gọi server, curl)Qua
Còn lại (subdomain khác, site khác, Origin: null)403 Yêu cầu bị chặn vì đến từ trang khác (CSRF)…

App khác origin cần gọi BFF thì khai origin đó trong NUXT_CSRF_ALLOWED_ORIGINS. Tắt hẳn bằng NUXT_CSRF_ENABLED=false chỉ khi đã có lớp chống CSRF khác phía trước.

/api/** ​

Request: giữ nguyên method, query, body và header, trừ:

PhầnXử lý
Đường dẫnBỏ tiền tố /api, nối vào apiProxyTarget (bỏ / thừa ở cuối target): /api/orders?page=1 → <target>/orders?page=1
authorizationHeader client gửi bị xoá. Phiên có token còn hạn → Authorization: Bearer <token>
cookieLuôn bị xoá — cookie trình duyệt, kể cả tasco_session, không sang backend

Response: nguyên trạng status, header và body của backend.

Tình huốngKết quả
Chưa đặt NUXT_API_PROXY_TARGET500 apiProxyTarget chưa cấu hình.
Chưa đăng nhập, hoặc token đã hết hạn (expiresAt)Chuyển tiếp không kèm Authorization — backend tự trả 401
Đường dẫn chứa .. sau khi giải mã hết (%2e%2e, %252e, %2f, \, Tomcat ..;), hoặc mã hoá hỏng400 Đường dẫn API không hợp lệ (chứa "..").
Backend không trả header trong 30 giây, hoặc không kết nối được502 Bad Gateway. Đã có header thì body (tải file, stream) không bị giới hạn thời gian

Route cụ thể trong server/api/ của dự án (vd server/api/orders/summary.get.ts) thắng catch-all này.

POST /auth/login ​

Body (LoginCredentials):

FieldKiểuBắt buộcÝ nghĩa
usernamestringCóCắt khoảng trắng hai đầu
passwordstringCó
clientIdstringKhôngMã ứng dụng (AuthClientOption.code)
method'google' | 'telegram'KhôngPhương thức OTP; đổi sang mã auth.authenMethod.* khi gửi IAM
otpstringKhôngMã OTP
transactionIdstringKhôngTrả về từ POST /auth/otp/send

Response 200: { user: AuthUser } — người dùng đầy đủ roles và permissions lấy từ userInfo. Đồng thời đặt cookie tasco_session.

LỗiKhi
400 Thiếu tên đăng nhập hoặc mật khẩu.Thiếu username (sau khi cắt khoảng trắng) hoặc password
401 kèm thông báo của IAMIAM trả code khác API000 — sai mật khẩu, sai OTP…
401 Đăng nhập thất bại.IAM trả HTTP 401/403
502 Hệ thống đăng nhập đang lỗi, thử lại sau.IAM lỗi 5xx, timeout, mất kết nối. Chi tiết (URL, body IAM) chỉ ghi log server, không trả về client
500 NUXT_AUTH_MOCK bị cấm ở production…Bản build production mà bật mock
500 auth.baseURL chưa cấu hình (NUXT_AUTH_BASE_URL).Chưa cấu hình IAM và không bật mock
500IAM không trả access token ở auth.mapping.token

Mock (NUXT_AUTH_MOCK=true, chỉ ở dev): không gọi IAM, nhận mọi tài khoản và trả:

json
{
  "user": {
    "id": "mock-user",
    "name": "Người dùng <username>",
    "email": "<username>@example.com",
    "roles": ["admin"],
    "permissions": ["/orders/search", "/orders/create", "/orders/update"]
  }
}

Gọi IAM có timeout 10 giây. BFF tự sinh các field thiết bị IAM yêu cầu (deviceId, deviceUuid…).

GET /auth/session ​

Response 200: { user: AuthUser | null }. Route không ném lỗi xác thực — mọi trường hợp không có phiên hợp lệ đều trả user: null. Riêng IAM không phản hồi (sập, timeout, lỗi 5xx) thì trả 502: plugin 02.auth để lỗi nổi lên trang lỗi thay vì coi người dùng là chưa đăng nhập.

Tình huốnguser
Không có cookie, cookie sai hoặc bị sửanull
Phiên có tokenGọi lại userInfo bằng token → người dùng đầy đủ quyền
Token đã quá expiresAtnull, không gọi IAM
userInfo bị IAM từ chối (401/403)null
IAM sập, timeout, 5xxLỗi 502
Mock, hoặc phiên không có tokenNgười dùng lưu trong cookie

Plugin 02.auth gọi route này một lần khi app khởi động để nạp useState('tasco:auth:user').

GET /auth/clients ​

Response 200: { clients: AuthClientOption[] } — chỉ giữ ứng dụng có đủ id, code, name.

Tình huốngclients
auth.endpoints.clients rỗng[]
MockHai ứng dụng mẫu OAP_OCM, OAP_CUS

Không yêu cầu đăng nhập (form đăng nhập gọi route này). IAM lỗi 5xx, timeout hay mất kết nối thì trả 502 Hệ thống đăng nhập đang lỗi, thử lại sau.

POST /auth/otp/send ​

Body: { username: string, password: string, clientId?: string }.

Response 200: { transactionId?: string } — gửi kèm POST /auth/login. Chỉ Telegram cần bước này; Google Authenticator thì nhập mã thẳng.

LỗiKhi
400 Thiếu tên đăng nhập hoặc mật khẩu.Thiếu username hoặc password
400 Chưa cấu hình gửi OTP (auth.endpoints.otpSend).Endpoint gửi OTP để rỗng
502 Hệ thống đăng nhập đang lỗi, thử lại sau.IAM lỗi 5xx, timeout, mất kết nối
401 kèm thông báo của IAMIAM từ chối

Mock trả { transactionId: 'mock-transaction' }.

GET /auth/logout ​

Query: redirect — đường dẫn quay về sau khi đăng xuất, mặc định /.

Xoá cookie tasco_session rồi trả 302. redirect chỉ nhận đường dẫn nội bộ: phải bắt đầu bằng đúng một /; //evil.com, /\evil.com hay URL tuyệt đối đều thành / (chống open redirect). Đây là điều hướng của trình duyệt, không gọi bằng $fetch — useAuth().logout() làm việc đó.

Thuộc tínhGiá trị
Nội dung{ user, accessToken?, expiresAt? }. Đăng nhập thật: user chỉ giữ id, name, email, roles và permissions lấy tươi ở /auth/session. Mock: cả người dùng giả, không có token
Định dạngv1.<iv>.<ciphertext>.<tag> (base64url), mã hoá và ký AES-256-GCM bằng khoá suy từ NUXT_SESSION_SECRET
CờHttpOnly, SameSite=Lax, Path=/, Secure (trừ khi chạy dev)
Thời hạn8 giờ; không có refresh token — hết hạn thì đăng nhập lại

Cookie giới hạn 4KB và access token IAM đã khoảng 2,4KB, nên không thêm dữ liệu vào phiên.

Liên quan ​