Đăng nhập bằng HiTechCloud ID (Authorization Code + PKCE)
Luồng chuẩn để người dùng đăng nhập bằng HiTechCloud ID: chuyển hướng tới endpoint authorize với PKCE S256, nhận mã code rồi đổi lấy access_token và id_token tại token endpoint.
Đây là luồng đăng nhập duy nhất qua trình duyệt. Hai bước: (1) chuyển khách tới trang đăng nhập của HiTechCloud ID để lấy code, (2) đổi code lấy token ở phía máy chủ (hoặc kèm code_verifier với public client).
Bước 0 — Tạo PKCE
Trước khi chuyển hướng, sinh một code_verifier ngẫu nhiên (43–128 ký tự an toàn URL) và tính code_challenge = BASE64URL(SHA256(code_verifier)). Giữ code_verifier trong phiên của bạn để dùng lại ở bước đổi token.
import crypto from "node:crypto";
const b64url = (buf) =>
buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const codeVerifier = b64url(crypto.randomBytes(32)); // lưu vào session
const codeChallenge = b64url(crypto.createHash("sha256").update(codeVerifier).digest());
const state = b64url(crypto.randomBytes(16)); // chống CSRF
const nonce = b64url(crypto.randomBytes(16)); // ràng buộc id_token
// Lưu codeVerifier + state + nonce vào session trước khi redirect.Bước 1 — Chuyển hướng tới authorize
Chuyển trình duyệt của khách tới endpoint authorize kèm các tham số dưới đây. Khách đăng nhập, chọn tài khoản (account chooser) và đồng ý (consent) ngay trên iam.hitechcloud.vn, rồi được chuyển về redirect_uri của bạn kèm code và state.
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
response_type | Có | code |
client_id | Có | Mã client của ứng dụng |
redirect_uri | Có | Phải khớp chính xác một URI đã đăng ký |
scope | Có | Danh sách phân tách bằng khoảng trắng; phải chứa openid để nhận id_token |
state | Nên | Giá trị ngẫu nhiên; so khớp khi callback để chống CSRF |
code_challenge | Có | Chuỗi PKCE tính ở bước 0 |
code_challenge_method | Có | S256 |
nonce | Nên | Ràng buộc vào id_token để chống phát lại |
prompt | Tuỳ chọn | login (bắt đăng nhập lại), consent (bắt hỏi đồng ý), none (không hiện UI), select_account (hiện bộ chọn tài khoản) |
https://iam.hitechcloud.vn/api/v1/sso/oauth2/authorize
?response_type=code
&client_id=app_xxx
&redirect_uri=https%3A%2F%2Fapp.example.vn%2Fcallback
&scope=openid%20profile%20email%20offline_access
&state=STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
&nonce=NONCErefresh_token, thêm scope offline_access. Trang đồng ý (consent) và bộ chọn tài khoản là màn hình của HiTechCloud ID — ứng dụng của bạn không cần tự dựng.Bước 2 — Đổi code lấy token
Khi khách quay về redirect_uri, hãy kiểm tra state khớp, rồi gọi token endpoint bằng POST với Content-Type: application/x-www-form-urlencoded.
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
grant_type | Có | authorization_code |
code | Có | Mã nhận được ở callback |
redirect_uri | Có | Đúng URI đã dùng ở bước 1 |
client_id | Có | Mã client |
client_secret | Chỉ confidential | Đặt trong THÂN form — KHÔNG dùng Authorization: Basic |
code_verifier | Có | code_verifier PKCE đã lưu ở bước 0 |
curl -X POST 'https://iam.hitechcloud.vn/api/v1/sso/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=AUTH_CODE' \
--data-urlencode 'redirect_uri=https://app.example.vn/callback' \
--data-urlencode 'client_id=app_xxx' \
--data-urlencode 'client_secret=secret_xxx' \
--data-urlencode 'code_verifier=CODE_VERIFIER'Public client bỏ client_secret và chỉ gửi code_verifier.
{
"access_token": "at_opaque_xxx",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid profile email offline_access",
"id_token": "eyJhbGciOiJSUzI1Ni␣...",
"refresh_token": "rt_xxx"
}access_token— chuỗi opaque (không phải JWT): dùng để gọi API thay khách, đừng cố giải mã nội dung.token_type— luôn làBearer.expires_in— số giây còn sống củaaccess_token.id_token— JWT ký RS256: xác minh và đọc danh tính khách (xem ID token & UserInfo).refresh_token— chỉ xuất hiện khi bạn xin scopeoffline_access.
code chỉ dùng được một lần và sống rất ngắn. Đổi token ngay ở phía máy chủ; nếu gửi lại một code đã dùng, máy chủ trả invalid_grant.Đọc tiếp
- ID token & UserInfo — xác minh
id_tokenvà lấy hồ sơ. - Làm mới & thu hồi token — giữ phiên lâu dài an toàn.
- Gọi API thay khách — dùng
access_tokenqua gateway.
Đây là luồng đăng nhập duy nhất qua trình duyệt. Hai bước: (1) chuyển khách tới trang đăng nhập của HiTechCloud ID để lấy code, (2) đổi code lấy token ở phía máy chủ (hoặc kèm code_verifier với public client).
Bước 0 — Tạo PKCE
Trước khi chuyển hướng, sinh một code_verifier ngẫu nhiên (43–128 ký tự an toàn URL) và tính code_challenge = BASE64URL(SHA256(code_verifier)). Giữ code_verifier trong phiên của bạn để dùng lại ở bước đổi token.
Bước 1 — Chuyển hướng tới authorize
Chuyển trình duyệt của khách tới endpoint authorize kèm các tham số dưới đây. Khách đăng nhập, chọn tài khoản (account chooser) và đồng ý (consent) ngay trên iam.hitechcloud.vn, rồi được chuyển về redirect_uri của bạn kèm code và state.
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
response_type | Có | code |
client_id | Có | Mã client của ứng dụng |
redirect_uri | Có | Phải khớp chính xác một URI đã đăng ký |
scope | Có | Danh sách phân tách bằng khoảng trắng; phải chứa openid để nhận id_token |
state | Nên | Giá trị ngẫu nhiên; so khớp khi callback để chống CSRF |
code_challenge | Có | Chuỗi PKCE tính ở bước 0 |
code_challenge_method | Có | S256 |
nonce | Nên | Ràng buộc vào id_token để chống phát lại |
prompt | Tuỳ chọn | login (bắt đăng nhập lại), consent (bắt hỏi đồng ý), none (không hiện UI), select_account (hiện bộ chọn tài khoản) |
refresh_token, thêm scope offline_access. Trang đồng ý (consent) và bộ chọn tài khoản là màn hình của HiTechCloud ID — ứng dụng của bạn không cần tự dựng.Bước 2 — Đổi code lấy token
Khi khách quay về redirect_uri, hãy kiểm tra state khớp, rồi gọi token endpoint bằng POST với Content-Type: application/x-www-form-urlencoded.
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
grant_type | Có | authorization_code |
code | Có | Mã nhận được ở callback |
redirect_uri | Có | Đúng URI đã dùng ở bước 1 |
client_id | Có | Mã client |
client_secret | Chỉ confidential | Đặt trong THÂN form — KHÔNG dùng Authorization: Basic |
code_verifier | Có | code_verifier PKCE đã lưu ở bước 0 |
Public client bỏ client_secret và chỉ gửi code_verifier.
access_token— chuỗi opaque (không phải JWT): dùng để gọi API thay khách, đừng cố giải mã nội dung.token_type— luôn làBearer.expires_in— số giây còn sống củaaccess_token.id_token— JWT ký RS256: xác minh và đọc danh tính khách (xem ID token & UserInfo).refresh_token— chỉ xuất hiện khi bạn xin scopeoffline_access.
code chỉ dùng được một lần và sống rất ngắn. Đổi token ngay ở phía máy chủ; nếu gửi lại một code đã dùng, máy chủ trả invalid_grant.Đọc tiếp
- ID token & UserInfo — xác minh
id_tokenvà lấy hồ sơ. - Làm mới & thu hồi token — giữ phiên lâu dài an toàn.
- Gọi API thay khách — dùng
access_tokenqua gateway.
import crypto from "node:crypto";
const b64url = (buf) =>
buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const codeVerifier = b64url(crypto.randomBytes(32)); // lưu vào session
const codeChallenge = b64url(crypto.createHash("sha256").update(codeVerifier).digest());
const state = b64url(crypto.randomBytes(16)); // chống CSRF
const nonce = b64url(crypto.randomBytes(16)); // ràng buộc id_token
// Lưu codeVerifier + state + nonce vào session trước khi redirect.https://iam.hitechcloud.vn/api/v1/sso/oauth2/authorize
?response_type=code
&client_id=app_xxx
&redirect_uri=https%3A%2F%2Fapp.example.vn%2Fcallback
&scope=openid%20profile%20email%20offline_access
&state=STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
&nonce=NONCEcurl -X POST 'https://iam.hitechcloud.vn/api/v1/sso/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=AUTH_CODE' \
--data-urlencode 'redirect_uri=https://app.example.vn/callback' \
--data-urlencode 'client_id=app_xxx' \
--data-urlencode 'client_secret=secret_xxx' \
--data-urlencode 'code_verifier=CODE_VERIFIER'{
"access_token": "at_opaque_xxx",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid profile email offline_access",
"id_token": "eyJhbGciOiJSUzI1Ni␣...",
"refresh_token": "rt_xxx"
}