中文
devexamples
← Recipes

阅读中文版本

Add OAuth Device Authorization for CLI Clients

Use the device authorization grant so a command-line tool can authenticate through the browser without a local callback and without embedding secrets.

~45 minoauthcliauthentication

Task

Let a terminal app obtain a token via the OAuth 2.0 device authorization flow.

When to use this

A CLI cannot open a localhost callback reliably in remote shells, and shipping a client secret in a binary leaks credentials.

Prerequisites

  • An OAuth provider that supports the device grant
  • A terminal app that can display a code and poll

Steps

1. Request a device code and user code from the authorization server.

Expected output: The CLI receives a code to display and a polling interval.

2. Instruct the user to visit the verification URI and enter the user code.

Expected output: The user authenticates in a real browser.

3. Poll the token endpoint at the given interval until the device is authorized.

Expected output: The CLI obtains an access token without a callback.

4. Handle slow_down and access_denied responses and never log the token.

curl -d "client_id=$ID&device_code=$CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code" https://auth.example.com/token

Expected output: Polling respects the server and failures are clean.

Troubleshooting

Problem

Polling too fast

Solution

Honor the interval and back off on slow_down; aggressive polling can get the client throttled.

Problem

Device code phished

Solution

Display the code clearly and warn users never to enter it on sites they do not trust.

Limitations

  • The device flow requires a browser-capable user and is unsuitable for fully headless automation.
  • It is not for confidential clients that can keep a secret; use the authorization code flow there.

Context

Let a terminal app obtain a token via the OAuth 2.0 device authorization flow. A CLI cannot open a localhost callback reliably in remote shells, and shipping a client secret in a binary leaks credentials.

Steps

  1. Request a device code and user code from the authorization server. Expected: The CLI receives a code to display and a polling interval.
  2. Instruct the user to visit the verification URI and enter the user code. Expected: The user authenticates in a real browser.
  3. Poll the token endpoint at the given interval until the device is authorized. Expected: The CLI obtains an access token without a callback.
  4. Handle slow_down and access_denied responses and never log the token. Expected: Polling respects the server and failures are clean.
# 1. start
curl -s -d "client_id=$ID&scope=openid" https://auth.example.com/device_authorization
# 2. user visits https://auth.example.com/device and enters user_code
# 3. poll
curl -s -d "client_id=$ID&device_code=$CODE&grant_type=urn:ietf:params:oauth:grant-type:device_code" https://auth.example.com/token

Verify

  • The CLI receives a code to display and a polling interval.
  • The user authenticates in a real browser.
  • The CLI obtains an access token without a callback.
  • Polling respects the server and failures are clean.

Limits

  • The device flow requires a browser-capable user and is unsuitable for fully headless automation.
  • It is not for confidential clients that can keep a secret; use the authorization code flow there.