TTMT.ManageWebGUI/SSO-Frontend-Microsoft.md

Frontend Guide - Microsoft SSO (Entra ID)

1) Muc tieu

Tai lieu nay danh cho frontend de tich hop dang nhap Microsoft SSO voi backend TTMT.CompManageWeb.

2) Redirect URI da dang ky

Redirect URI cho Microsoft app:

https://comp.soict.io/api/auth/sso/callback

Luu y:

• Redirect URI trong Azure App Registration phai giong 100% (scheme, domain, path).
• Sai ky tu hoac sai slash cuoi co the gay loi redirect_uri mismatch.

3) Endpoint frontend can goi

Backend route SSO Microsoft (legacy route):

• GET /api/auth/sso/login?returnUrl={FRONTEND_RETURN_URL}
• POST /api/auth/sso/exchange

Route alias cung ho tro:

• GET /api/sso/login?returnUrl={FRONTEND_RETURN_URL}
• POST /api/sso/exchange

4) Login flow cho frontend

1. User bam nut "Login with Microsoft".
2. Frontend redirect browser den: /api/auth/sso/login?returnUrl={FRONTEND_RETURN_URL}
3. Backend redirect sang Microsoft login page.
4. Sau khi user xac thuc thanh cong, Microsoft goi ve redirect URI: https://comp.soict.io/api/auth/sso/callback
5. Backend tao one-time code va redirect user ve FRONTEND_RETURN_URL kem query: ?code={ONE_TIME_CODE}
6. Frontend doc code trong URL, goi API exchange de doi code lay JWT noi bo.
7. Frontend luu token va thong tin user, dieu huong vao app.

5) API exchange chi tiet

Method: POST Path: /api/auth/sso/exchange Content-Type: application/json

Request body: { "code": "" }

Success response (HTTP 200): { "token": "", "name": "Nguyen Van A", "username": "user@hust.edu.vn", "access": [1, 2, 3], "role": { "roleName": "Pending", "priority": 99 } }

6) Error handling goi y cho frontend

• 400 BadRequest: code thieu hoac token khong hop le.
• 401 Unauthorized: code het han / da dung / khong hop le.
• 404 NotFound: user khong ton tai sau khi exchange.

One-time code co han su dung ngan (khoang 2 phut) va chi dung 1 lan. Neu exchange that bai, can yeu cau user login lai.

7) Mau frontend pseudo-code

const returnUrl = window.location.origin + "/sso/complete"; window.location.href = /api/auth/sso/login?returnUrl=${encodeURIComponent(returnUrl)};

// tai /sso/complete const code = new URLSearchParams(window.location.search).get("code"); if (code) { const res = await fetch("/api/auth/sso/exchange", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ code }) });

if (!res.ok) { // hien thi thong bao loi va cho user thu lai } else { const data = await res.json(); // save data.token, data.username, data.role, data.access } }

8) Checklist truoc khi UAT

• Redirect URI trong Azure dung: https://comp.soict.io/api/auth/sso/callback
• Frontend returnUrl la URL FE hop le (vi du: https://comp.soict.io/sso/complete)
• Frontend parse duoc query code
• Frontend goi exchange ngay sau khi nhan code
• Frontend xu ly day du HTTP 400/401/404