どんな端末のためのflowか

TV、ゲーム機、CLIのように、長いURLやpasswordを安全に入力しにくいClientでは、通常のBrowser redirectが使いにくいことがあります。RFC 8628は、Client端末と認可に使うBrowserを分けます。

Device Authorizationの二端末protocol flow

CLIはDevice Authorization endpointへclient_id、scope、resourceを送り、次を受け取ります。

device_code: CLIだけが保持する長いcredential
user_code: 利用者が短く入力するcode
verification_uri: Browserで開くAS画面
verification_uri_complete: user code込みURL
expires_inとinterval

user_codeはTokenではない

短いuser_codeは推測されやすいため、それだけでTokenを受け取れません。Browser側でResource OwnerがASへログインし、表示されたClientとscopeを確認してapproveします。

CLIはdevice_codeをToken endpointへpollします。

grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=...&
client_id=...

Better Auth Device Codeの状態遷移とDB

polling errorを状態として扱う

authorization_pending: まだ判断されていない。interval後に再試行
slow_down: pollingが速すぎる。intervalへ5秒加える
access_denied: 利用者が拒否した。終了
expired_token: 期限切れ。最初からやり直す

authorization_pendingを例外stackとして毎回logへ出すのではなく、正常な待機状態として扱います。slow_downを無視して固定intervalで叩き続ける実装も仕様違反です。

Better Auth pluginを追加する

Device FlowはoauthProvider()のoptionへgrant文字列を足すだけではありません。

plugins: [
  oauthProvider(providerOptions),
  oauthDeviceAuthorization({ verificationUri: '/device' })
]

このpluginによりdevice_code tableのOAuth Client/resource field、Device endpoint、approve/deny API、discovery metadataが追加されます。schemaを再生成せずpluginだけ加えるとruntimeでcolumn不足になります。

phishing境界

Device画面はClient名、要求scope、user codeを表示します。利用者へ「別サイトへcodeを入力して」と誘導する攻撃があるため、verification domainを確認できるUIにします。CLI側からAS passwordを要求してはいけません。

次章では4つのgrantを「できること」ではなくprincipalとcredential ownershipで比較します。