refactor: add debug logging to device flow, improve auth UX and README

- Add auth:device debug namespace for tracing device flow login
- Improve fallback message: "Your SSO provider requires device-based
  login" instead of confusing OAuth jargon
- Rewrite README auth section with scannable table showing three
  login methods and when each is used
- Add "Credential resolution order" subsection
- Note that API tokens are scoped to individual user accounts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: steve-calvert-glean

README.md

@@ -19,8 +19,8 @@ Search across your company's knowledge, chat with Glean Assistant, manage the fu
   - [Quick Start](#quick-start)
   - [Why Glean CLI?](#why-glean-cli)
   - [Authentication](#authentication)
-    - [OAuth (recommended)](#oauth-recommended)
     - [API Token (CI/CD)](#api-token-cicd)
+    - [Credential resolution order](#credential-resolution-order)
   - [Interactive TUI](#interactive-tui)
     - [Keyboard Shortcuts](#keyboard-shortcuts)
     - [Slash Commands](#slash-commands)
@@ -95,28 +95,36 @@ glean search "engineering docs" --output ndjson | jq .title
 
 ## Authentication
 
-### OAuth (recommended)
-
 ```bash snippet=readme/snippet-04.sh
-glean auth login    # browser PKCE flow, or device flow for SSO/Okta
+glean auth login    # interactive login (detects the best method automatically)
 glean auth status   # verify credentials, host, and token expiry
 glean auth logout   # remove all stored credentials
 ```
 
-OAuth uses PKCE with Dynamic Client Registration when available. For SSO configurations where DCR is unavailable (e.g. Okta), `auth login` falls back to the Device Authorization Grant (RFC 8628) — you'll approve the login on a verification page instead. Tokens are stored securely in the system keyring and refreshed automatically.
+`glean auth login` detects the right authentication method for your environment automatically:
+
+| Method | When it's used | What happens |
+| --- | --- | --- |
+| **Browser login** | Default for most Glean instances | Opens your browser, you approve, done |
+| **Device code login** | Organizations using an external IdP (e.g. Okta) | Prints a URL and code — open the URL, enter the code |
+| **API token** | Instances without OAuth support | Prompts you to paste a token from Glean Admin |
 
-For instances that don't support OAuth at all, `auth login` falls back to prompting for an API token.
+You don't need to choose — `auth login` tries each method in order and uses the first one that works. Tokens are stored securely in the system keyring and refreshed automatically.
 
 ### API Token (CI/CD)
 
-Set credentials via environment variables — no interactive login needed:
+For non-interactive environments, set credentials via environment variables:
 
 ```bash snippet=readme/snippet-05.sh
 export GLEAN_API_TOKEN=your-token
 export GLEAN_HOST=your-company-be.glean.com
 glean search "test"
 ```
 
+API tokens are scoped to an individual user account. Generate one from **Glean Admin → Settings → API Tokens**.
+
+### Credential resolution order
+
 Credentials are resolved in this order: environment variables → system keyring → `~/.glean/config.json`.
 
 ## Interactive TUI

internal/auth/auth.go

@@ -31,6 +31,7 @@ var (
 	dcrLog       = debug.New("auth:dcr")
 	tokenLog     = debug.New("auth:token")
 	emailLog     = debug.New("auth:email")
+	deviceLog    = debug.New("auth:device")
 )
 
 //go:embed success.html
@@ -66,18 +67,21 @@ func Login(ctx context.Context) error {
 	loginLog.Log("OAuth discovery succeeded: auth=%s token=%s registration=%s", disc.Endpoint.AuthURL, disc.Endpoint.TokenURL, disc.RegistrationEndpoint)
 
 	// Try DCR / static client first (standard authorization code flow).
+	loginLog.Log("attempting authorization code + PKCE flow")
 	authCodeErr := tryAuthCodeLogin(ctx, host, disc)
 	if authCodeErr == nil {
 		return nil
 	}
+	loginLog.Log("auth code flow failed: %v", authCodeErr)
 
 	// Only fall back to device flow when the auth code flow failed because no
 	// OAuth client could be obtained (DCR unsupported + no static client).
 	// Transient failures (network, user closing browser, port conflicts) should
 	// not silently switch to a different grant type.
 	canDeviceFlow := disc.DeviceFlowClientID != "" && disc.DeviceAuthEndpoint != ""
 	if errors.Is(authCodeErr, errNoOAuthClient) && canDeviceFlow {
-		fmt.Fprintf(os.Stderr, "Note: no OAuth client available, trying device flow…\n")
+		loginLog.Log("falling back to device authorization grant (client_id=%s)", disc.DeviceFlowClientID)
+		fmt.Fprintf(os.Stderr, "\nYour SSO provider requires device-based login.\n")
 		return deviceFlowLogin(ctx, host, disc)
 	}
 

internal/auth/device.go

@@ -40,11 +40,13 @@ type deviceTokenError struct {
 // deviceFlowLogin performs the OAuth 2.0 Device Authorization Grant (RFC 8628).
 func deviceFlowLogin(ctx context.Context, host string, disc *discoveryResult) error {
 	scopes := resolveScopes(disc.Provider)
+	deviceLog.Log("requesting device code from %s (client_id=%s)", disc.DeviceAuthEndpoint, disc.DeviceFlowClientID)
 
 	authResp, err := requestDeviceCode(ctx, disc.DeviceAuthEndpoint, disc.DeviceFlowClientID, scopes)
 	if err != nil {
 		return fmt.Errorf("device authorization request failed: %w", err)
 	}
+	deviceLog.Log("device code received: user_code=%s verification_uri=%s expires_in=%d", authResp.UserCode, authResp.VerificationURI, authResp.ExpiresIn)
 
 	verificationURL := authResp.VerificationURIComplete
 	if verificationURL == "" {
@@ -69,10 +71,13 @@ func deviceFlowLogin(ctx context.Context, host string, disc *discoveryResult) er
 
 	_ = browser.OpenURL(verificationURL)
 
+	deviceLog.Log("polling token endpoint %s (interval=%ds)", disc.Endpoint.TokenURL, authResp.Interval)
 	token, err := pollForToken(ctx, disc.Endpoint.TokenURL, disc.DeviceFlowClientID, authResp)
 	if err != nil {
+		deviceLog.Log("device flow failed: %v", err)
 		return fmt.Errorf("device flow login failed: %w", err)
 	}
+	deviceLog.Log("device flow token received")
 
 	return saveAndPrintToken(ctx, host, disc, disc.DeviceFlowClientID, token)
 }
@@ -105,6 +110,7 @@ func requestDeviceCode(ctx context.Context, endpoint, clientID string, scopes []
 			desc = errResp.Error
 		}
 		if errResp.Error == "unauthorized_client" {
+			deviceLog.Log("IdP rejected device code grant for client %s: %s", clientID, desc)
 			return nil, fmt.Errorf("%s\n\nAsk your IdP administrator to add the device_code grant type\nto OAuth app %s", desc, clientID)
 		}
 		if desc != "" {

snippets/readme/snippet-04.sh

@@ -1,3 +1,3 @@
-glean auth login    # browser PKCE flow, or device flow for SSO/Okta
+glean auth login    # interactive login (detects the best method automatically)
 glean auth status   # verify credentials, host, and token expiry
 glean auth logout   # remove all stored credentials