oauth2-device-flow

A minimal example of OAuth2 authentication for CLI applications in headless environments (e.g., over SSH).

How It Works

sequenceDiagram
    participant CLI
    participant User
    participant OAuth Server

    CLI->>OAuth Server: 1. Request device code
    OAuth Server->>CLI: 2. Return device_code + user_code
    CLI->>User: 3. Display URL and code
    User->>OAuth Server: 4. Open URL, enter code, authorize
    CLI->>OAuth Server: 5. Poll for token
    OAuth Server->>CLI: 6. Return access_token
    CLI->>OAuth Server: 7. Make authenticated API requests

Loading

Prerequisites

• Docker
• Python 3.8+

Quick Start

# Start the mock OAuth2 server
docker compose up -d

# Run the CLI
cd cli
pip install -r requirements.txt
python cli.py

Open the displayed URL on any device with a browser, enter the code, and authorize.

Example Output

CLI OAuth2 Demo (Device Flow)
========================================

1. Requesting device code...

2. Open this URL in any browser:
   http://localhost:8080/default/device
   Enter code: ABCD-1234
   (Expires in 600 seconds)

3. Waiting for authorization.....
   Received access token: eyJraWQiOiJkZWZhdWx0...

4. Fetching user info with access token...

========================================
Authentication successful!
========================================

User Info:
  sub: demouser
  azp: cli-app
  iss: http://localhost:8080/default

The Code

The CLI (cli/cli.py) implements OAuth2 Device Authorization Grant (RFC 8628):

1. Request device code: POST to /device/authorize with client_id and scope
2. Display instructions: show verification URL and user code to enter
3. Poll for token: repeatedly POST to /token until user completes authorization
4. Handle polling responses: authorization_pending (keep waiting), slow_down (increase interval), access_denied (user denied), expired_token (timed out)
5. Make authenticated requests: use access token to call protected APIs

Security

• No redirect URI: no local server needed, can't be intercepted
• Short user codes: easy to type, time-limited
• Polling-based: device never exposes any ports
• User verification: user must actively enter code on trusted device

Tests

cd cli && pytest tests/ -v

Using with Real Providers

Providers supporting Device Authorization Grant:

Provider	Documentation
Google	Limited Input Device
Microsoft	Device Code Flow
GitHub	Device Flow

To use with a real provider:

1. Register your application with the provider
2. Update OAUTH_SERVER and CLIENT_ID in cli.py
3. Add any required scopes