Đă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.
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 -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'{
"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ạngXXXX-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ẵnuser_code(tiện render QR).expires_in— 600 giây (10 phút) là hạn củadevice_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 -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_pending | Khách chưa duyệt xong — tiếp tục poll theo interval. |
slow_down | Poll quá nhanh — tăng interval thêm 5 giây rồi thử lại. |
access_denied | Khách từ chối — dừng và báo lỗi. |
expired_token | device_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)
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 | ...
}
}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.
user_code— mã dạngXXXX-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ẵnuser_code(tiện render QR).expires_in— 600 giây (10 phút) là hạn củadevice_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.
| Lỗi khi poll | Ý nghĩa & xử lý |
|---|---|
authorization_pending | Khách chưa duyệt xong — tiếp tục poll theo interval. |
slow_down | Poll quá nhanh — tăng interval thêm 5 giây rồi thử lại. |
access_denied | Khách từ chối — dừng và báo lỗi. |
expired_token | device_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)
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'{
"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
}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'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 | ...
}
}