TV, máy chơi game và công cụ dòng lệnh

TV khó hiển thị một trang đăng nhập, và một công cụ dòng lệnh không nên hỏi mật khẩu. Với luồng thiết bị, thiết bị hiển thị một mã ngắn, và người dùng nhập mã đó vào Lobby của môi trường trên điện thoại hoặc máy tính, nơi họ đã đăng nhập sẵn.

Đăng ký ứng dụng

Trong Usher Console, mở môi trường, rồi chọn Ứng dụng → Ứng dụng mới → TV hoặc dòng lệnh. Ứng dụng nhận một Client ID và không có client secret: thiết bị không thể giữ bí mật.

Luồng

Terminal

# 1. the device asks for a code
curl -s -X POST https://acme.usherid.com/api/auth/device/code \
  -d client_id=YOUR_CLIENT_ID -d scope='openid email offline_access'
# → { "device_code": "…", "user_code": "6L95PBQQ",
#     "verification_uri": "https://acme.usherid.com/device",
#     "verification_uri_complete": "https://acme.usherid.com/device?user_code=6L95PBQQ",
#     "expires_in": 600, "interval": 5 }

# 2. it shows the code (and a QR code of verification_uri_complete), then polls
curl -s -X POST https://acme.usherid.com/api/auth/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=… -d client_id=YOUR_CLIENT_ID
# → { "error": "authorization_pending" } until the person allows it,
#   then { "access_token": "…", "id_token": "…", "refresh_token": "…" }

Hỏi lại từ tốn. Chờ interval giây giữa các lần hỏi. Hỏi nhanh hơn sẽ nhận phản hồi slow_down.
Dừng khi được yêu cầu. access_denied nghĩa là người dùng đã từ chối; expired_token nghĩa là đã quá mười phút. Hãy yêu cầu mã mới.
Hiển thị cả địa chỉ. Không phải ai cũng quét được mã QR: hãy hiển thị verification_uri và mã, có khoảng cách như 6L95-PBQQ.

Tại /device, Lobby cho người dùng biết ứng dụng nào đang yêu cầu và yêu cầu những gì. Lobby nhắc họ chỉ tiếp tục nếu chính họ đã bắt đầu việc này và thiết bị của họ hiển thị đúng mã đó.

Gắn token với thiết bị (DPoP)

Một token bị sao chép khỏi thiết bị vẫn là một token. Với DPoP (RFC 9449), thiết bị giữ một khóa riêng tư và gửi kèm một bằng chứng mới có chữ ký trong mọi yêu cầu. Một token đã gắn với khóa đó sẽ vô dụng nếu thiếu khóa.

Yêu cầu token được gắn khóa: gửi header DPoP cùng các yêu cầu token, và Usher sẽ gắn những gì nó phát hành với khóa của bạn (token_type là DPoP).
Bắt buộc dùng: bật Yêu cầu DPoP khi bạn tạo ứng dụng. Khi đó Usher không phát hành token nào cho ứng dụng nếu không có bằng chứng.
Sử dụng với Authorization: DPoP <token>, kèm một bằng chứng cho yêu cầu đó.
Thư viện: hầu hết các thư viện OAuth hỗ trợ DPoP đều làm tất cả những việc này giúp bạn (ví dụ, tùy chọn DPoP của openid-client).