Tasco Framework

Giao diện

Cấu hình IAM ​

Route BFF (/auth/login, /auth/session…) là hợp đồng cố định. Phần thay đổi theo nhà cung cấp nằm hết trong runtimeConfig.auth — nghĩa là đổi backend xác thực chỉ là đổi biến môi trường, không sửa code client.

Mặc định đã khớp IAM Tasco, nên phần lớn dự án chỉ cần một dòng:

bash
NUXT_AUTH_BASE_URL=https://example.com/cop

Bốn endpoint ​

baseURL bọc cả /iam và /auth; các đường dẫn dưới đây là tương đối so với nó.

BiếnMặc địnhCách gọi
NUXT_AUTH_ENDPOINTS_LOGIN/auth/auth/login-v1POST, body gồm username, password, clientId, otp, authenMethod và các field thiết bị
NUXT_AUTH_ENDPOINTS_USER_INFO/iam/user/userInfoPOST, header authorization: <token> — không có tiền tố Bearer, body rỗng
NUXT_AUTH_ENDPOINTS_CLIENTS/iam/client/findAll?status=1GET, dùng cho dropdown chọn ứng dụng
NUXT_AUTH_ENDPOINTS_OTP_SEND/auth/auth/login/requestPOST; để rỗng thì tắt tính năng gửi OTP

Mọi lời gọi ra IAM đều có timeout 10 giây.

Envelope ​

IAM Tasco trả { code, message, body } kèm HTTP 200 ngay cả khi nghiệp vụ thất bại. BFF coi code !== 'API000' là thất bại và ném 401 kèm message gốc — đó chính là dòng chữ người dùng thấy trên form khi sai mật khẩu hoặc sai OTP.

Backend không dùng envelope kiểu này thì bỏ qua: không có field code thì không có kiểm tra nào chạy, thất bại thể hiện bằng mã HTTP như bình thường.

Mapping: bóc dữ liệu từ response ​

Mỗi khoá mapping.* là một dot-path tính từ gốc JSON của response.

Response login của IAM Tasco:

json
{
  "code": "API000",
  "body": {
    "tokenData": { "access_token": "eyJ…", "expires_in": 86400 },
    "userId": "1234",
    "fullName": "Đỗ Xuân Thành",
    "email": "thanhdx@tasco.vn",
    "listRole": [{ "code": "AIWSP_ADMIN", "name": "Quản trị" }],
    "authorization": [
      { "uri": "/attendance-summary/search", "type": "web" },
      { "uri": "/attendance-summary/update", "type": "web" },
      { "uri": "/internal/job/run", "type": "job" }
    ]
  }
}

tương ứng với mặc định:

bash
NUXT_AUTH_MAPPING_TOKEN=body.tokenData.access_token
NUXT_AUTH_MAPPING_EXPIRES_IN=body.tokenData.expires_in
NUXT_AUTH_MAPPING_ID=body.userId
NUXT_AUTH_MAPPING_NAME=body.fullName
NUXT_AUTH_MAPPING_EMAIL=body.email
NUXT_AUTH_MAPPING_ROLES=body.listRole
NUXT_AUTH_MAPPING_PERMISSIONS=body.authorization

Khi roles/permissions là mảng object ​

Cần nói rõ lấy field nào làm mã, và lọc theo loại nào:

bash
NUXT_AUTH_MAPPING_ROLE_KEY=code             # listRole[].code  → 'AIWSP_ADMIN'
NUXT_AUTH_MAPPING_PERMISSION_KEY=uri        # authorization[].uri → '/attendance-summary/search'
NUXT_AUTH_MAPPING_PERMISSION_TYPE=web       # chỉ giữ quyền dùng cho giao diện
NUXT_AUTH_MAPPING_PERMISSION_TYPE_KEY=type

Với ví dụ trên, người dùng nhận đúng hai quyền web; quyền type: 'job' bị bỏ qua.

Mảng chuỗi thuần (["ADMIN", "USER"]) thì *_KEY không có tác dụng, giá trị được dùng nguyên. Để NUXT_AUTH_MAPPING_PERMISSION_TYPE= rỗng nếu backend không phân loại quyền.

Cắm vào một IAM khác ​

  1. Xem response thật trước khi đoán đường dẫn:

    bash
    curl -sS -X POST https://example.com/cop/auth/auth/login-v1 \
  -H 'content-type: application/json' \
  -d '{"username":"…","password":"…","clientId":"WP_HRM"}' | jq

  2. Điền .env: NUXT_AUTH_BASE_URL, bốn endpoint, rồi các MAPPING_* theo đúng dot-path đọc được ở bước 1.

  3. Thử đăng nhập và mở GET /auth/session trong tab Network: user.roles và user.permissions phải có dữ liệu. Rỗng nghĩa là mapping roles/permissions sai.

  4. Kiểm tra quyền khớp với URI mà dự án khai trong definePageMeta và v-can.

Lỗi thường gặp ​

Thông báo / hiện tượngNguyên nhân
500 auth.baseURL chưa cấu hình (NUXT_AUTH_BASE_URL).Thiếu biến, hoặc đặt nhầm tên
IAM không trả accessToken (kiểm tra auth.mapping.token).MAPPING_TOKEN trỏ sai path
401 kèm thông báo lạ của IAMEnvelope báo lỗi nghiệp vụ — sai mật khẩu, sai OTP, sai mã ứng dụng
Đăng nhập được nhưng permissions rỗngSai MAPPING_PERMISSIONS, sai PERMISSION_KEY, hoặc lọc nhầm PERMISSION_TYPE
Đăng nhập được nhưng mọi trang trả 403Quyền lấy về không cùng dạng URI với quyền khai ở trang
400 Chưa cấu hình gửi OTP (auth.endpoints.otpSend).Form bật phương thức Telegram trong khi endpoint để rỗng

Liên quan ​