oauth2-auth-code-pkce

A minimal example of OAuth2 authentication for CLI applications using the browser.

How It Works

sequenceDiagram
    participant CLI
    participant Browser
    participant OAuth Server

    CLI->>CLI: 1. Start local callback server
    CLI->>Browser: 2. Open browser to /authorize
    Browser->>OAuth Server: 3. User logs in
    OAuth Server->>Browser: 4. Redirect to localhost/callback<br/>with ?code=AUTH_CODE
    Browser->>CLI: 4. Callback received
    CLI->>OAuth Server: 5. Exchange code 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

Your browser opens automatically. Log in with any username and the flow completes.

Example Output

CLI OAuth2 Demo
========================================

1. Opening browser for authentication...
   URL: http://localhost:8080/default/authorize?client_id=cli-app&...

2. Waiting for authentication callback...
   Received authorization code: wPW2uEjQekhUNWQzNBxg...

3. Exchanging code for access token...
   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 Authorization Code flow with PKCE:

1. Generate PKCE pair: code_verifier (random secret) and code_challenge (SHA256 hash)
2. Generate state: random string to prevent CSRF attacks
3. Start local HTTP server: listens on localhost:8085 for the callback
4. Open browser: navigates to /authorize with client_id, redirect_uri, PKCE challenge, and state
5. User authenticates: logs in via the OAuth provider
6. Receive callback: server redirects to localhost:8085/callback?code=...&state=...
7. Validate state: ensures state matches to prevent CSRF
8. Exchange code for token: POST to /token with code and PKCE verifier
9. Make authenticated requests: use access token to call protected APIs

Security

• PKCE (RFC 7636): prevents authorization code interception attacks
• State parameter: prevents CSRF attacks
• Localhost callback: only accepts callbacks on 127.0.0.1

Tests

cd cli && pytest tests/ -v

Using with Real Providers

To use with Google, GitHub, Okta, Auth0, etc.:

1. Register your application with the provider
2. Set http://localhost:8085/callback as an allowed redirect URI
3. Update OAUTH_SERVER and CLIENT_ID in cli.py
4. Add any required scopes