Đăng nhập từ CLI / thiết bị (RFC 8628)

Device Authorization Grant (RFC 8628) cho CLI, thiết bị IoT và màn hình không nhập liệu được: lấy user_code, cho khách duyệt tại iam.hitechcloud.vn/oauth/device, rồi poll token endpoint.

Xem Markdown
Luồng thiết bị đang được hoàn thiện. Phần dưới mô tả hợp đồng dự kiến — hãy đối chiếu lại với bản triển khai cuối.

Dùng cho thiết bị khó nhập liệu (CLI, TV, IoT): thiết bị xin một mã ngắn, khách mở mã đó trên điện thoại/máy tính để đăng nhập, còn thiết bị thì poll cho tới khi được cấp token.

Bước 1 — Xin mã thiết bị

POST /api/v1/sso/oauth2/device_authorization với client_id và scope.

cURL — device_authorization
curl -X POST 'https://iam.hitechcloud.vn/api/v1/sso/oauth2/device_authorization' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=app_xxx' \
  --data-urlencode 'scope=openid profile offline_access'
Phản hồi
{
  "device_code": "dc_xxx",
  "user_code": "WXYZ-1234",
  "verification_uri": "https://iam.hitechcloud.vn/oauth/device",
  "verification_uri_complete": "https://iam.hitechcloud.vn/oauth/device?user_code=WXYZ-1234",
  "expires_in": 600,
  "interval": 5
}
  • user_code — mã dạng XXXX-XXXX để khách nhập.
  • verification_uri — địa chỉ khách mở để nhập mã (https://iam.hitechcloud.vn/oauth/device).
  • verification_uri_complete — địa chỉ đã kèm sẵn user_code (tiện render QR).
  • expires_in — 600 giây (10 phút) là hạn của device_code.
  • interval — 5 giây: khoảng tối thiểu giữa hai lần poll.

Hiển thị cho khách: “Mở https://iam.hitechcloud.vn/oauth/device và nhập mã WXYZ-1234”, hoặc render QR tới verification_uri_complete.

Bước 2 — Poll token endpoint

Thiết bị gọi token endpoint với grant_type=urn:ietf:params:oauth:grant-type:device_code mỗi interval giây cho tới khi khách duyệt xong.

cURL — poll
curl -X POST 'https://iam.hitechcloud.vn/api/v1/sso/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode 'device_code=dc_xxx' \
  --data-urlencode 'client_id=app_xxx'
Lỗi khi pollÝ nghĩa & xử lý
authorization_pendingKhách chưa duyệt xong — tiếp tục poll theo interval.
slow_downPoll quá nhanh — tăng interval thêm 5 giây rồi thử lại.
access_deniedKhách từ chối — dừng và báo lỗi.
expired_tokendevice_code đã hết hạn — bắt đầu lại từ bước 1.

Khi duyệt xong, token endpoint trả về bộ token như luồng Authorization Code (access_token, id_token, refresh_token nếu có offline_access).

Ví dụ poll (Node.js)

Node.js
async function pollToken(deviceCode, clientId, interval) {
  let wait = interval;
  for (;;) {
    await new Promise((r) => setTimeout(r, wait * 1000));
    const res = await fetch("https://iam.hitechcloud.vn/api/v1/sso/oauth2/token", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
        device_code: deviceCode,
        client_id: clientId,
      }),
    });
    const data = await res.json();
    if (res.ok) return data;                       // { access_token, id_token, ... }
    if (data.error === "authorization_pending") continue;
    if (data.error === "slow_down") { wait += 5; continue; }
    throw new Error(data.error);                    // access_denied | expired_token | ...
  }
}