feat: auth login --no-browser via OAuth2 device authorization grant

drewr · drewr · commit e14d689032eb · 2026-06-08T22:37:43.000Z
The existing `auth login` uses an authorization-code-with-PKCE flow that
binds a localhost HTTP server to receive the OIDC redirect. On a remote
machine over SSH, in CI, or in a container, that pattern is unreachable
— the browser running on the operator's laptop can't reach a port bound
on the remote box without a separate SSH port-forward. The standard
escape hatch is RFC 8628 OAuth2 device authorization, which is what
datumctl's own `login --no-browser` uses.

Mirror that here:

  - StatelessClient::login_device_code() — fetches the OIDC discovery
    JSON directly (openidconnect's CoreProviderMetadata doesn't surface
    device_authorization_endpoint), rebuilds the OIDC client with
    set_device_authorization_url(), starts the grant, hands the
    DeviceCodeInfo (verification URL + user code + expiry) to a caller-
    supplied display callback, and polls exchange_device_access_token
    via tokio::time::sleep. Token-response parsing reuses the existing
    parse_token_response with a nonce verifier that allows missing-nonce
    (device flow doesn't bind one).
  - AuthClient::login_device_code() — always performs a fresh login;
    callers wanting refresh-eligible token reuse should use the normal
    login() instead.
  - DatumCloudClient::login_device_code() — top-level entry point.
  - DeviceCodeInfo re-exported from lib::datum_cloud so the CLI doesn't
    take a direct dep on openidconnect's Core types.

CLI side, AuthCommands::Login and AuthCommands::Switch both gain a
--no-browser flag that routes to the new method. The display callback
prints the verification URL + user code prominently to stderr so it
doesn't tangle with structured stdout (relevant for future plugin
modes).

Verified against the production auth server's OIDC discovery (Datum's
Zitadel exposes device_authorization_endpoint and lists
urn:ietf:params:oauth:grant-type:device_code in grant_types_supported).
diff --git a/cli/src/main.rs b/cli/src/main.rs
@@ -9,7 +9,7 @@ use rustls::crypto::ring as rustls_ring;
 use lib::{
     Advertisment, AdvertismentTicket, ConnectNode, DiscoveryMode, HeartbeatAgent, ListenNode,
     ProgressStepKind, ProxyState, Repo, SelectedContext, StepStatus, TcpProxyData, TunnelService,
-    datum_cloud::{ApiEnv, DatumCloudClient, LoginState},
+    datum_cloud::{ApiEnv, DatumCloudClient, DeviceCodeInfo, LoginState},
 };
 use n0_error::StdResultExt;
 use std::{
@@ -221,7 +221,16 @@ pub enum AuthCommands {
     Status,
 
     /// Log in to Datum Cloud (opens browser for OAuth).
-    Login,
+    Login {
+        /// Skip the localhost-redirect flow and use the OAuth2 device
+        /// authorization grant instead. Required when running on a
+        /// remote machine over SSH, in CI, or in a container — anywhere
+        /// the localhost-redirect can't reach a browser. The CLI prints
+        /// a verification URL + user code; complete authorization on
+        /// another device.
+        #[clap(long)]
+        no_browser: bool,
+    },
 
     /// Log out and clear stored credentials.
     Logout,
@@ -230,7 +239,12 @@ pub enum AuthCommands {
     List,
 
     /// Switch to a different authenticated user (clears current and prompts for new login).
-    Switch,
+    Switch {
+        /// Same as `auth login --no-browser`: use the OAuth2 device
+        /// authorization grant for the fresh login after logout.
+        #[clap(long)]
+        no_browser: bool,
+    },
 }
 
 #[derive(Parser, Debug)]
@@ -394,8 +408,12 @@ async fn main() -> n0_error::Result<()> {
                         println!("Not authenticated");
                     }
                 }
-                AuthCommands::Login => {
-                    datum.login().await?;
+                AuthCommands::Login { no_browser } => {
+                    if no_browser {
+                        datum.login_device_code(display_device_code).await?;
+                    } else {
+                        datum.login().await?;
+                    }
                     if let Ok(state) = datum.auth_state().get() {
                         println!(
                             "Logged in as {} ({})",
@@ -425,10 +443,14 @@ async fn main() -> n0_error::Result<()> {
                     println!();
                     println!("Note: Multi-user storage not yet implemented. Use 'auth switch' to log in as a different user.");
                 }
-                AuthCommands::Switch => {
+                AuthCommands::Switch { no_browser } => {
                     datum.logout().await?;
                     println!("Switching users...");
-                    datum.login().await?;
+                    if no_browser {
+                        datum.login_device_code(display_device_code).await?;
+                    } else {
+                        datum.login().await?;
+                    }
                     if let Ok(state) = datum.auth_state().get() {
                         println!(
                             "Switched to {} ({})",
@@ -1088,6 +1110,35 @@ fn resolve_project_context(
     None
 }
 
+/// Renders an OAuth2 device authorization grant prompt for `auth login
+/// --no-browser` / `auth switch --no-browser`. Prints the verification
+/// URL + user code prominently to stderr (so it doesn't get tangled
+/// with the structured-output JSON future plugin modes may emit to
+/// stdout), then returns so the polling loop in lib can proceed.
+async fn display_device_code(info: DeviceCodeInfo) {
+    eprintln!();
+    eprintln!("================================================================");
+    eprintln!("  Open this URL on another device to authorize:");
+    eprintln!();
+    eprintln!("      {}", info.verification_uri);
+    eprintln!();
+    eprintln!("  Enter this code when prompted:");
+    eprintln!();
+    eprintln!("      {}", info.user_code);
+    if let Some(complete) = &info.verification_uri_complete {
+        eprintln!();
+        eprintln!("  (Or open this pre-filled URL to skip the code step:");
+        eprintln!("   {})", complete);
+    }
+    eprintln!();
+    eprintln!(
+        "  Code expires in {} seconds. Waiting for authorization…",
+        info.expires_in.as_secs(),
+    );
+    eprintln!("================================================================");
+    eprintln!();
+}
+
 /// Result of streaming the tunnel-setup progress to stdout. All conditions
 /// reached `Ready` (or we bailed before that for a terminal failure).
 struct SetupResult {
diff --git a/lib/src/datum_cloud.rs b/lib/src/datum_cloud.rs
@@ -14,7 +14,7 @@ use crate::http_user_agent::datum_http_user_agent;
 use crate::{ProjectControlPlaneClient, Repo, SelectedContext};
 
 pub use self::{
-    auth::{AuthClient, AuthState, LoginState, MaybeAuth, UserProfile},
+    auth::{AuthClient, AuthState, DeviceCodeInfo, LoginState, MaybeAuth, UserProfile},
     env::ApiEnv,
 };
 
@@ -105,6 +105,18 @@ impl DatumCloudClient {
         self.auth.login().await
     }
 
+    /// `--no-browser` login via the OAuth2 device authorization grant.
+    /// The CLI's `auth login --no-browser` flag routes here; the `display`
+    /// callback shows the verification URL + user code to the operator
+    /// who completes authorization on another device.
+    pub async fn login_device_code<F, Fut>(&self, display: F) -> Result<()>
+    where
+        F: FnOnce(DeviceCodeInfo) -> Fut,
+        Fut: std::future::Future<Output = ()>,
+    {
+        self.auth.login_device_code(display).await
+    }
+
     pub async fn logout(&self) -> Result<()> {
         self.auth.logout().await
     }
diff --git a/lib/src/datum_cloud/auth.rs b/lib/src/datum_cloud/auth.rs
@@ -11,10 +11,12 @@ use arc_swap::ArcSwap;
 use chrono::Utc;
 use n0_error::{Result, StackResultExt, StdResultExt, anyerr, stack_error};
 use openidconnect::{
-    AccessToken, AccessTokenHash, AuthorizationCode, ClientId, ClientSecret, CsrfToken, IssuerUrl,
-    Nonce, NonceVerifier, OAuth2TokenResponse, PkceCodeChallenge, RefreshToken, Scope,
-    TokenResponse,
-    core::{CoreAuthenticationFlow, CoreClient, CoreProviderMetadata},
+    AccessToken, AccessTokenHash, AuthorizationCode, ClientId, ClientSecret, CsrfToken,
+    DeviceAuthorizationUrl, IssuerUrl, Nonce, NonceVerifier, OAuth2TokenResponse,
+    PkceCodeChallenge, RefreshToken, Scope, TokenResponse,
+    core::{
+        CoreAuthenticationFlow, CoreClient, CoreDeviceAuthorizationResponse, CoreProviderMetadata,
+    },
 };
 use serde::{Deserialize, Serialize};
 use tokio::sync::watch;
@@ -31,6 +33,25 @@ const LOGIN_TIMEOUT: Duration = Duration::from_secs(60);
 /// Refresh auth or relogin if access token is valid for less than 30min
 const REFRESH_AUTH_WHEN: Duration = Duration::from_secs(60 * 30);
 
+/// Surface of an in-flight OAuth2 device authorization grant. The
+/// `display` callback passed to [`StatelessClient::login_device_code`]
+/// receives one of these and is responsible for showing the verification
+/// URL + user code to the operator.
+#[derive(Debug, Clone)]
+pub struct DeviceCodeInfo {
+    /// URL the user opens on their other device to authorize.
+    pub verification_uri: String,
+    /// Short code the user enters at `verification_uri`.
+    pub user_code: String,
+    /// Optional URL that pre-fills the user code, so the user only has
+    /// to follow one link.
+    pub verification_uri_complete: Option<String>,
+    /// How long the user has before the device code expires.
+    pub expires_in: Duration,
+    /// Operator-side polling interval recommended by the auth server.
+    pub interval: Duration,
+}
+
 pub struct AuthProvider {
     pub issuer_url: String,
     pub client_id: String,
@@ -241,6 +262,107 @@ impl StatelessClient {
         Ok(state)
     }
 
+    /// OAuth2 Device Authorization grant (RFC 8628). Used by `datum-connect
+    /// auth login --no-browser` and any other headless context where the
+    /// localhost-redirect flow can't reach back to a browser (SSH, CI,
+    /// containers). The caller receives a `DeviceCodeInfo` via the
+    /// `display` callback and is responsible for showing the verification
+    /// URL + user code to the operator; this method then polls the token
+    /// endpoint until the user completes authorization.
+    pub async fn login_device_code<F, Fut>(&self, display: F) -> Result<AuthState>
+    where
+        F: FnOnce(DeviceCodeInfo) -> Fut,
+        Fut: Future<Output = ()>,
+    {
+        // `openidconnect::CoreProviderMetadata` doesn't surface the
+        // `device_authorization_endpoint` from discovery, so refetch the
+        // raw JSON to find it.
+        let discovery_url = format!(
+            "{}/.well-known/openid-configuration",
+            self.env.auth_provider().issuer_url.trim_end_matches('/'),
+        );
+        #[derive(Deserialize)]
+        struct DiscoveryDoc {
+            device_authorization_endpoint: Option<String>,
+        }
+        let discovery: DiscoveryDoc = self
+            .http
+            .get(&discovery_url)
+            .send()
+            .await
+            .std_context("Failed to fetch OIDC discovery document")?
+            .error_for_status()
+            .std_context("OIDC discovery returned a non-success status")?
+            .json()
+            .await
+            .std_context("Failed to parse OIDC discovery document")?;
+        let device_endpoint = discovery.device_authorization_endpoint.context(
+            "Auth server does not advertise a device_authorization_endpoint; \
+             --no-browser is unsupported against this provider",
+        )?;
+
+        // Rebuild a CoreClient with the device URL set. The crate's
+        // typestate prevents mutating the cached `self.oidc` in place,
+        // and the discovery the constructor performs is cheap enough to
+        // accept the duplication.
+        let provider = self.env.auth_provider();
+        let issuer = IssuerUrl::new(provider.issuer_url.clone())
+            .std_context("Invalid OIDC provider issuer URL")?;
+        let metadata = CoreProviderMetadata::discover_async(issuer, &self.http)
+            .await
+            .std_context("Failed to discover OIDC provider metadata")?;
+        let oidc = CoreClient::from_provider_metadata(
+            metadata,
+            ClientId::new(provider.client_id),
+            provider.client_secret.clone().map(ClientSecret::new),
+        )
+        .set_device_authorization_url(
+            DeviceAuthorizationUrl::new(device_endpoint).std_context(
+                "Invalid device_authorization_endpoint in OIDC discovery",
+            )?,
+        );
+
+        let details: CoreDeviceAuthorizationResponse = oidc
+            .exchange_device_code()
+            .add_scope(Scope::new("openid".to_string()))
+            .add_scope(Scope::new("profile".to_string()))
+            .add_scope(Scope::new("email".to_string()))
+            .add_scope(Scope::new("offline_access".to_string()))
+            .request_async(&self.http)
+            .await
+            .std_context("Failed to start device authorization")?;
+
+        let info = DeviceCodeInfo {
+            verification_uri: details.verification_uri().to_string(),
+            user_code: details.user_code().secret().to_string(),
+            verification_uri_complete: details
+                .verification_uri_complete()
+                .map(|u| u.secret().to_string()),
+            expires_in: Duration::from_secs(details.expires_in().as_secs()),
+            interval: Duration::from_secs(details.interval().as_secs()),
+        };
+        display(info).await;
+
+        let tokens = oidc
+            .exchange_device_access_token(&details)
+            .std_context("Device-flow client misconfigured")?
+            .request_async(&self.http, tokio::time::sleep, None)
+            .await
+            .std_context("Failed to exchange device access token")?;
+
+        // Device flow doesn't bind a nonce (no user-agent round-trip carrying
+        // one), so accept an absent nonce in the ID token.
+        let nonce_verifier =
+            |_received: Option<&Nonce>| -> std::result::Result<(), String> { Ok(()) };
+        let state = self.parse_token_response(tokens, nonce_verifier, None).await?;
+        info!(
+            email=%state.profile.email,
+            expires_at=%state.tokens.expires_at(),
+            "device-code login successful"
+        );
+        Ok(state)
+    }
+
     pub async fn refresh(
         &self,
         tokens: &AuthTokens,
@@ -808,6 +930,24 @@ impl AuthClient {
         Ok(())
     }
 
+    /// `--no-browser` analog of [`AuthClient::login`]. Skips the auth-code
+    /// localhost-redirect flow (which doesn't work over SSH because the
+    /// remote machine's bound port can't be reached by a browser running
+    /// on the operator's laptop) and uses the OAuth2 device authorization
+    /// grant instead. Always performs a fresh login — if a refresh-eligible
+    /// token exists the caller can use [`AuthClient::login`] without
+    /// `--no-browser` to use it.
+    pub async fn login_device_code<F, Fut>(&self, display: F) -> Result<()>
+    where
+        F: FnOnce(DeviceCodeInfo) -> Fut,
+        Fut: Future<Output = ()>,
+    {
+        let client = self.ensure_fresh_client().await?;
+        let auth = client.login_device_code(display).await?;
+        self.state.set(Some(auth)).await?;
+        Ok(())
+    }
+
     pub async fn refresh(&self) -> Result<()> {
         let auth = self.state.load();
         let auth = auth.get()?;
