feat: support GOOSE_OAUTH_CALLBACK_PORT for stable OAuth redirect_uri (#9209)

Signed-off-by: Douwe Osinga <douwe@squareup.com>
Co-authored-by: Douwe Osinga <douwe@squareup.com>

crates/goose/src/oauth/mod.rs

@@ -76,7 +76,11 @@ pub async fn oauth_flow(
         .route("/oauth_callback", get(handler))
         .with_state(app_state);
 
-    let addr = SocketAddr::from(([127, 0, 0, 1], 0));
+    let port: u16 = std::env::var("GOOSE_OAUTH_CALLBACK_PORT")
+        .ok()
+        .and_then(|p| p.parse().ok())
+        .unwrap_or(0);
+    let addr = SocketAddr::from(([127, 0, 0, 1], port));
     let listener = tokio::net::TcpListener::bind(addr).await?;
     let used_addr = listener.local_addr()?;
     tokio::spawn(async move {

crates/goose/src/providers/oauth.rs

@@ -341,7 +341,10 @@ impl OAuthFlow {
 
         // If no port is specified (or port is explicitly 0), let the OS assign one
         // Otherwise, use the requested port
-        let bind_port = requested_port.unwrap_or(0);
+        let env_port: Option<u16> = std::env::var("GOOSE_OAUTH_CALLBACK_PORT")
+            .ok()
+            .and_then(|p| p.parse().ok());
+        let bind_port = requested_port.or(env_port).unwrap_or(0);
         let addr = SocketAddr::from(([127, 0, 0, 1], bind_port));
         let listener = tokio::net::TcpListener::bind(addr).await?;
 

documentation/docs/guides/environment-variables.md

@@ -456,6 +456,25 @@ Optional [macOS sandbox](/docs/guides/sandbox) for goose Desktop that restricts
 
 These variables configure network proxy settings for goose.
 
+### OAuth Callback Port
+
+By default, goose starts a temporary local server on a random port to receive OAuth callbacks. Enterprise identity providers that require exact `redirect_uri` matching (and forbid wildcard ports) will reject the callback. Set this variable to use a fixed port instead.
+
+| Variable | Purpose | Values | Default |
+|----------|---------|---------|---------|
+| `GOOSE_OAUTH_CALLBACK_PORT` | Fixed port for the local OAuth callback server | Port number (e.g., 8080, 9999) | Random (OS-assigned) |
+
+**Examples**
+
+```bash
+# Use a fixed port so your IdP's redirect_uri whitelist can match exactly
+export GOOSE_OAUTH_CALLBACK_PORT=8080
+```
+
+Then register the appropriate redirect URI in your identity provider:
+- For MCP server OAuth: `http://127.0.0.1:8080/oauth_callback`
+- For Databricks OAuth: `http://localhost:8080`
+
 ### HTTP Proxy
 
 goose supports standard HTTP proxy environment variables for users behind corporate firewalls or proxy servers.