94 lines
2.8 KiB
Markdown
94 lines
2.8 KiB
Markdown
# 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": "<one-time-code>"
|
|
}
|
|
|
|
Success response (HTTP 200):
|
|
{
|
|
"token": "<jwt>",
|
|
"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
|