feat: support implicit OAuth in VS Code remote environments (Codespaces)

Add openBrowser and redirectUri options to ImplicitOAuthConfig,
AuthCredentials, and CreateOAuthOptions so callers can customize the
browser opener and redirect URI for implicit auth flows.

The VS Code extension now uses vscode.env.openExternal (opens browser
on the client) and vscode.env.asExternalUri (resolves localhost to the
Codespaces forwarded port URL) so implicit OAuth works in remote
environments where the `open` package cannot reach the user's browser.

Author: clavery

.changeset/implicit-auth-vscode-browser.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-tooling-sdk': minor
+'b2c-vs-extension': patch
+---
+
+Add `openBrowser` and `redirectUri` options to OAuth strategy creation, allowing callers to customize how the browser is opened and which redirect URI is used during implicit auth. The VS Code extension now uses `vscode.env.openExternal` and `vscode.env.asExternalUri` so implicit OAuth works in Codespaces and other remote environments.

packages/b2c-tooling-sdk/src/auth/oauth-implicit.ts

@@ -41,6 +41,12 @@ export interface ImplicitOAuthConfig {
    * The local server still listens on localPort regardless of this setting.
    */
   redirectUri?: string;
+  /**
+   * Custom browser opener. Receives the authorization URL and should open it
+   * in the user's browser. Useful in environments where the default `open` package
+   * doesn't work (e.g., VS Code remote/Codespaces where `vscode.env.openExternal` is needed).
+   */
+  openBrowser?: (url: string) => Promise<void>;
 }
 
 /**
@@ -70,7 +76,7 @@ function getOauth2RedirectHTML(redirectUri: string): string {
  * Opens the system default browser to the specified URL.
  * Dynamically imports 'open' package to handle the browser opening.
  */
-async function openBrowser(url: string): Promise<void> {
+async function openBrowserDefault(url: string): Promise<void> {
   try {
     // Dynamic import of 'open' package
     const open = await import('open');
@@ -325,9 +331,13 @@ export class ImplicitOAuthStrategy implements AuthStrategy {
     logger.info({url: authorizeUrl}, `Login URL: ${authorizeUrl}`);
     logger.info('If the URL does not open automatically, copy/paste it into a browser on this machine.');
 
-    // Attempt to open the browser
+    // Attempt to open the browser (prefer injected opener, fall back to `open` package)
     logger.debug('[Auth] Attempting to open browser');
-    await openBrowser(authorizeUrl);
+    if (this.config.openBrowser) {
+      await this.config.openBrowser(authorizeUrl);
+    } else {
+      await openBrowserDefault(authorizeUrl);
+    }
 
     return new Promise<AccessTokenResponse>((resolve, reject) => {
       const sockets: Set<Socket> = new Set();

packages/b2c-tooling-sdk/src/auth/resolve.ts

@@ -182,6 +182,8 @@ export function resolveAuthStrategy(
             clientId: credentials.clientId,
             scopes: credentials.scopes,
             accountManagerHost: credentials.accountManagerHost,
+            redirectUri: credentials.redirectUri,
+            openBrowser: credentials.openBrowser,
           });
         }
         break;

packages/b2c-tooling-sdk/src/auth/types.ts

@@ -133,4 +133,8 @@ export interface AuthCredentials {
   apiKey?: string;
   /** Header name for API key (defaults to Authorization with Bearer prefix) */
   apiKeyHeaderName?: string;
+  /** Override redirect URI for implicit OAuth flow (e.g., for port forwarding in remote environments) */
+  redirectUri?: string;
+  /** Custom browser opener for implicit OAuth flow. Receives the authorization URL. */
+  openBrowser?: (url: string) => Promise<void>;
 }

packages/b2c-tooling-sdk/src/config/resolved-config.ts

@@ -82,6 +82,8 @@ export class ResolvedConfigImpl implements ResolvedB2CConfig {
       clientSecret: this.values.clientSecret,
       scopes: mergedScopes.length > 0 ? mergedScopes : undefined,
       accountManagerHost: this.values.accountManagerHost,
+      redirectUri: options?.redirectUri,
+      openBrowser: options?.openBrowser,
     };
     return resolveAuthStrategy(credentials, {allowedMethods: options?.allowedMethods});
   }

packages/b2c-tooling-sdk/src/config/types.ts

@@ -326,6 +326,10 @@ export interface CreateOAuthOptions {
   allowedMethods?: AuthMethod[];
   /** Additional OAuth scopes to request beyond those in config */
   scopes?: string[];
+  /** Override redirect URI for implicit OAuth flow (e.g., for port forwarding in remote environments) */
+  redirectUri?: string;
+  /** Custom browser opener for implicit OAuth flow. Receives the authorization URL. */
+  openBrowser?: (url: string) => Promise<void>;
 }
 
 /**

packages/b2c-vs-extension/src/api-browser/api-browser-tree-provider.ts

@@ -127,7 +127,8 @@ export class ApiBrowserTreeDataProvider implements vscode.TreeDataProvider<ApiBr
       const schemas = await vscode.window.withProgress(
         {location: {viewId: 'b2cApiBrowser'}, title: 'Loading SCAPI schemas...'},
         async () => {
-          const oauthStrategy = config.createOAuth();
+          const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+          const oauthStrategy = config.createOAuth(oauthOptions);
           const schemasClient = createScapiSchemasClient({shortCode, tenantId}, oauthStrategy);
           const orgId = toOrganizationId(tenantId);
           const {data, error, response} = await schemasClient.GET('/organizations/{organizationId}/schemas', {

packages/b2c-vs-extension/src/api-browser/swagger-webview.ts

@@ -218,7 +218,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
 
     // Resolve external $refs server-side so the webview doesn't have to fetch them
     if (config.hasOAuthConfig()) {
-      const oauthStrategy = config.createOAuth();
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth(oauthOptions);
       const authHeader = await oauthStrategy.getAuthorizationHeader?.();
       await resolveExternalRefs(spec, authHeader, this.log);
     }
@@ -308,7 +309,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
           const tenantId = deriveTenantId(config.values.hostname);
           if (!tenantId) throw new Error('Could not derive tenant ID from hostname.');
 
-          const oauthStrategy = config.createOAuth();
+          const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+          const oauthStrategy = config.createOAuth(oauthOptions);
           const schemasClient = createScapiSchemasClient({shortCode, tenantId}, oauthStrategy);
           const orgId = toOrganizationId(tenantId);
           const {data, error, response} = await schemasClient.GET(
@@ -452,7 +454,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
       if (!config.hasOAuthConfig()) return null;
       // Request the specific scopes required by this API spec so the token
       // includes them (the cache will re-authenticate if scopes are missing)
-      const oauthStrategy = config.createOAuth({scopes});
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth({...oauthOptions, scopes});
       const header = await oauthStrategy.getAuthorizationHeader?.();
       if (!header) return null;
       // Header is "Bearer <token>" — extract the token
@@ -510,7 +513,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
 
     try {
       this.log.appendLine(`[API Browser] Auto-discovering SLAS client for tenant ${tenantId}...`);
-      const oauthStrategy = config.createOAuth();
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth(oauthOptions);
       const slasClient = createSlasClient({shortCode}, oauthStrategy);
 
       const {data, error} = await slasClient.GET('/tenants/{tenantId}/clients', {

packages/b2c-vs-extension/src/config-provider.ts

@@ -8,6 +8,7 @@ import {
   EnvSource,
   type NormalizedConfig,
   type ResolvedB2CConfig,
+  type CreateOAuthOptions,
 } from '@salesforce/b2c-tooling-sdk/config';
 import type {B2CInstance} from '@salesforce/b2c-tooling-sdk/instance';
 import * as fs from 'fs';
@@ -234,6 +235,26 @@ export class B2CExtensionConfig implements vscode.Disposable {
     return resolveConfig(overrides, {workingDirectory});
   }
 
+  /**
+   * Returns CreateOAuthOptions with VS Code-specific overrides for implicit auth:
+   * - Uses `vscode.env.openExternal` to open the browser on the client (works in Codespaces/remote)
+   * - Uses `vscode.env.asExternalUri` to resolve the redirect URI for port forwarding
+   *
+   * Merge with any additional options before passing to `config.createOAuth()`.
+   */
+  async getImplicitAuthOptions(): Promise<CreateOAuthOptions> {
+    const localPort = parseInt(process.env.SFCC_OAUTH_LOCAL_PORT || '', 10) || 8080;
+    const localUri = vscode.Uri.parse(`http://localhost:${localPort}`);
+    const externalUri = await vscode.env.asExternalUri(localUri);
+
+    return {
+      redirectUri: process.env.SFCC_REDIRECT_URI || externalUri.toString(/* skipEncoding */ true),
+      openBrowser: async (url: string) => {
+        await vscode.env.openExternal(vscode.Uri.parse(url));
+      },
+    };
+  }
+
   dispose(): void {
     this._onDidReset.dispose();
     for (const d of this.disposables) {

packages/b2c-vs-extension/src/sandbox-tree/sandbox-commands.ts

@@ -11,13 +11,14 @@ import type {RealmTreeItem, SandboxTreeDataProvider, SandboxTreeItem} from './sa
 
 const DEFAULT_ODS_HOST = 'admin.dx.commercecloud.salesforce.com';
 
-function getOdsClientFromConfig(configProvider: SandboxConfigProvider) {
+async function getOdsClientFromConfig(configProvider: SandboxConfigProvider) {
   const config = configProvider.getConfigProvider().getConfig();
   if (!config) throw new Error('No B2C Commerce configuration found. Configure dw.json or SFCC_* env vars.');
   if (!config.hasOAuthConfig())
     throw new Error('OAuth credentials required. Set clientId and clientSecret in dw.json.');
   const host = config.values.sandboxApiHost ?? DEFAULT_ODS_HOST;
-  return createOdsClient({host}, config.createOAuth());
+  const oauthOptions = await configProvider.getConfigProvider().getImplicitAuthOptions();
+  return createOdsClient({host}, config.createOAuth(oauthOptions));
 }
 
 const SANDBOX_DETAIL_SCHEME = 'b2c-sandbox';
@@ -103,7 +104,7 @@ export function registerSandboxCommands(
       {location: vscode.ProgressLocation.Notification, title: `Creating sandbox in realm ${realm}...`},
       async () => {
         try {
-          const odsClient = getOdsClientFromConfig(configProvider);
+          const odsClient = await getOdsClientFromConfig(configProvider);
           const result = await odsClient.POST('/sandboxes', {
             body: {realm: realm!, ttl, analyticsEnabled: false},
           });
@@ -139,7 +140,7 @@ export function registerSandboxCommands(
       {location: vscode.ProgressLocation.Notification, title: `Deleting sandbox ${node.sandbox.id}...`},
       async () => {
         try {
-          const odsClient = getOdsClientFromConfig(configProvider);
+          const odsClient = await getOdsClientFromConfig(configProvider);
           const result = await odsClient.DELETE('/sandboxes/{sandboxId}', {
             params: {path: {sandboxId: node.sandbox.id}},
           });
@@ -180,7 +181,7 @@ export function registerSandboxCommands(
       },
       async () => {
         try {
-          const odsClient = getOdsClientFromConfig(configProvider);
+          const odsClient = await getOdsClientFromConfig(configProvider);
           const result = await odsClient.POST('/sandboxes/{sandboxId}/operations', {
             params: {path: {sandboxId: node.sandbox.id}},
             body: {operation: operationType},
@@ -264,7 +265,7 @@ export function registerSandboxCommands(
         },
         async () => {
           try {
-            const odsClient = getOdsClientFromConfig(configProvider);
+            const odsClient = await getOdsClientFromConfig(configProvider);
             const result = await odsClient.PATCH('/sandboxes/{sandboxId}', {
               params: {path: {sandboxId: node.sandbox.id}},
               body: {ttl},