Đă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.

Xem Markdown

Đâ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.

Node.js — sinh PKCE + state + nonce
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ộcMô tả
response_typeCócode
client_idCóMã client của ứng dụng
redirect_uriCóPhải khớp chính xác một URI đã đăng ký
scopeCóDanh sách phân tách bằng khoảng trắng; phải chứa openid để nhận id_token
stateNênGiá trị ngẫu nhiên; so khớp khi callback để chống CSRF
code_challengeCóChuỗi PKCE tính ở bước 0
code_challenge_methodCóS256
nonceNênRàng buộc vào id_token để chống phát lại
promptTuỳ chọnlogin (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)
URL authorize (đã xuống dòng cho dễ đọc)
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=NONCE
Để nhậ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ộcMô tả
grant_typeCóauthorization_code
codeCóMã nhận được ở callback
redirect_uriCóĐúng URI đã dùng ở bước 1
client_idCóMã client
client_secretChỉ confidentialĐặt trong THÂN form — KHÔNG dùng Authorization: Basic
code_verifierCócode_verifier PKCE đã lưu ở bước 0
cURL — confidential client
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.

Phản hồi thành công
{
  "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ủa access_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 scope offline_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