feat: use UI Bridge API to generate a single-use frontdoor (#1375)

EstebanRomero84 · web-flow · commit a9bf347706e3 · 2025-03-18T17:36:27.000-03:00
* fix(org open): use UI Bridge API to generate a single-use frontdoor

* fix: generates a one-time use URL only when neither the --orl-only nor the --json flags are passed

* fix: add warning message to org open command

* fix: improve error handling

* fix: better UIT

* fix: add environment variable SF_SINGLE_USE_ORG_OPEN_URL
diff --git a/messages/messages.md b/messages/messages.md
@@ -3,3 +3,11 @@
 This command will expose sensitive information that allows for subsequent activity using your current authenticated session.
 Sharing this information is equivalent to logging someone in under the current credential, resulting in unintended access and escalation of privilege.
 For additional information, please review the authorization section of the https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_web_flow.htm.
+
+# BehaviorChangeWarning
+
+August 2025, this command will generate single-use URLs when you specify either the --json or --url-only (-r) flag. These URLs can be used only one time; subsequent use won't allow you to log in to the org.
+
+# SingleAccessFrontdoorError
+
+Failed to generate a single-use frontdoor URL.
diff --git a/src/commands/org/open.ts b/src/commands/org/open.ts
@@ -14,12 +14,14 @@ import {
 } from '@salesforce/sf-plugins-core';
 import { Connection, Messages } from '@salesforce/core';
 import { MetadataResolver } from '@salesforce/source-deploy-retrieve';
+import { env } from '@salesforce/kit';
 import { buildFrontdoorUrl } from '../../shared/orgOpenUtils.js';
 import { OrgOpenCommandBase } from '../../shared/orgOpenCommandBase.js';
 import { type OrgOpenOutput } from '../../shared/orgTypes.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'open');
+const sharedMessages = Messages.loadMessages('@salesforce/plugin-org', 'messages');
 
 export class OrgOpenCommand extends OrgOpenCommandBase<OrgOpenOutput> {
   public static readonly summary = messages.getMessage('summary');
@@ -66,12 +68,15 @@ export class OrgOpenCommand extends OrgOpenCommandBase<OrgOpenOutput> {
   };
 
   public async run(): Promise<OrgOpenOutput> {
+    this.warn(sharedMessages.getMessage('BehaviorChangeWarning'));
     const { flags } = await this.parse(OrgOpenCommand);
     this.org = flags['target-org'];
     this.connection = this.org.getConnection(flags['api-version']);
 
+    const singleUseEnvVar: boolean = env.getBoolean('SF_SINGLE_USE_ORG_OPEN_URL');
+    const singleUseMode = singleUseEnvVar ? singleUseEnvVar : !(flags['url-only'] || this.jsonEnabled());
     const [frontDoorUrl, retUrl] = await Promise.all([
-      buildFrontdoorUrl(this.org, this.connection),
+      buildFrontdoorUrl(this.org, this.connection, singleUseMode),
       flags['source-file'] ? generateFileUrl(flags['source-file'], this.connection) : flags.path,
     ]);
 
diff --git a/src/commands/org/open/agent.ts b/src/commands/org/open/agent.ts
@@ -53,7 +53,7 @@ export class OrgOpenAgent extends OrgOpenCommandBase<OrgOpenOutput> {
     this.connection = this.org.getConnection(flags['api-version']);
 
     const [frontDoorUrl, retUrl] = await Promise.all([
-      buildFrontdoorUrl(this.org, this.connection),
+      buildFrontdoorUrl(this.org, this.connection, true),
       buildRetUrl(this.connection, flags.name),
     ]);
 
diff --git a/src/shared/orgOpenCommandBase.ts b/src/shared/orgOpenCommandBase.ts
@@ -74,33 +74,46 @@ export abstract class OrgOpenCommandBase<T> extends SfCommand<T> {
       handleDomainError(err, url, env);
     }
 
-    // create a local html file that contains the POST stuff.
-    const tempFilePath = path.join(tmpdir(), `org-open-${new Date().valueOf()}.html`);
-    await fs.promises.writeFile(
-      tempFilePath,
-      getFileContents(
-        this.connection.accessToken as string,
-        this.connection.instanceUrl,
-        // the path flag is URI-encoded in its `parse` func.
-        // For the form redirect to work we need it decoded.
-        flags.path ? decodeURIComponent(flags.path) : retUrl
-      )
-    );
-    const filePathUrl = isWsl
-      ? 'file:///' + execSync(`wslpath -m ${tempFilePath}`).toString().trim()
-      : `file:///${tempFilePath}`;
-    const cp = await utils.openUrl(filePathUrl, {
-      ...(flags.browser ? { app: { name: apps[flags.browser] } } : {}),
-      ...(flags.private ? { newInstance: platform() === 'darwin', app: { name: apps.browserPrivate } } : {}),
-    });
-    cp.on('error', (err) => {
+    if (this.jsonEnabled()) {
+      // TODO: remove this code path once the org open behavior changes on August 2025 (see W-17661469)
+      // create a local html file that contains the POST stuff.
+      const tempFilePath = path.join(tmpdir(), `org-open-${new Date().valueOf()}.html`);
+      await fs.promises.writeFile(
+        tempFilePath,
+        getFileContents(
+          this.connection.accessToken as string,
+          this.connection.instanceUrl,
+          // the path flag is URI-encoded in its `parse` func.
+          // For the form redirect to work we need it decoded.
+          flags.path ? decodeURIComponent(flags.path) : retUrl
+        )
+      );
+      const filePathUrl = isWsl
+        ? 'file:///' + execSync(`wslpath -m ${tempFilePath}`).toString().trim()
+        : `file:///${tempFilePath}`;
+      const cp = await utils.openUrl(filePathUrl, {
+        ...(flags.browser ? { app: { name: apps[flags.browser] } } : {}),
+        ...(flags.private ? { newInstance: platform() === 'darwin', app: { name: apps.browserPrivate } } : {}),
+      });
+      cp.on('error', (err) => {
+        fileCleanup(tempFilePath);
+        throw SfError.wrap(err);
+      });
+      // so we don't delete the file while the browser is still using it
+      // open returns when the CP is spawned, but there's not way to know if the browser is still using the file
+      await sleep(platform() === 'win32' || isWsl ? 7000 : 5000);
       fileCleanup(tempFilePath);
-      throw SfError.wrap(err);
-    });
-    // so we don't delete the file while the browser is still using it
-    // open returns when the CP is spawned, but there's not way to know if the browser is still using the file
-    await sleep(platform() === 'win32' || isWsl ? 7000 : 5000);
-    fileCleanup(tempFilePath);
+    } else {
+      // it means we generated a one-time use frontdoor url
+      // so the workaround to create a local html file is not needed
+      const cp = await utils.openUrl(url, {
+        ...(flags.browser ? { app: { name: apps[flags.browser] } } : {}),
+        ...(flags.private ? { newInstance: platform() === 'darwin', app: { name: apps.browserPrivate } } : {}),
+      });
+      cp.on('error', (err) => {
+        throw SfError.wrap(err);
+      });
+    }
 
     return output;
   }
diff --git a/src/shared/orgOpenUtils.ts b/src/shared/orgOpenUtils.ts
@@ -13,20 +13,43 @@ import { Duration, Env } from '@salesforce/kit';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-org', 'open');
+const sharedMessages = Messages.loadMessages('@salesforce/plugin-org', 'messages');
 
 export const openUrl = async (url: string, options: Options): Promise<ChildProcess> => open(url, options);
 
 export const fileCleanup = (tempFilePath: string): void =>
   rmSync(tempFilePath, { force: true, maxRetries: 3, recursive: true });
 
-export const buildFrontdoorUrl = async (org: Org, conn: Connection): Promise<string> => {
+type SingleAccessUrlRes = { frontdoor_uri: string | undefined };
+
+/**
+ * This method generates and returns a frontdoor url for the given org.
+ *
+ * @param org org for which we generate the frontdoor url.
+ * @param conn the Connection for the given Org.
+ * @param singleUseUrl if true returns a single-use url frontdoor url.
+ */
+export const buildFrontdoorUrl = async (org: Org, conn: Connection, singleUseUrl: boolean): Promise<string> => {
   await org.refreshAuth(); // we need a live accessToken for the frontdoor url
   const accessToken = conn.accessToken;
   if (!accessToken) {
     throw new SfError('NoAccessToken', 'NoAccessToken');
   }
-  const instanceUrlClean = org.getField<string>(Org.Fields.INSTANCE_URL).replace(/\/$/, '');
-  return `${instanceUrlClean}/secur/frontdoor.jsp?sid=${accessToken}`;
+  if (singleUseUrl) {
+    try {
+      const response: SingleAccessUrlRes = await conn.requestGet('/services/oauth2/singleaccess');
+      if (response.frontdoor_uri) return response.frontdoor_uri;
+      throw new SfError(sharedMessages.getMessage('SingleAccessFrontdoorError')).setData(response);
+    } catch (e) {
+      if (e instanceof SfError) throw e;
+      const err = e as Error;
+      throw new SfError(sharedMessages.getMessage('SingleAccessFrontdoorError'), err.message);
+    }
+  } else {
+    // TODO: remove this code path once the org open behavior changes on August 2025 (see W-17661469)
+    const instanceUrlClean = org.getField<string>(Org.Fields.INSTANCE_URL).replace(/\/$/, '');
+    return `${instanceUrlClean}/secur/frontdoor.jsp?sid=${accessToken}`;
+  }
 };
 
 export const handleDomainError = (err: unknown, url: string, env: Env): string => {
diff --git a/test/unit/org/open.test.ts b/test/unit/org/open.test.ts
@@ -28,6 +28,8 @@ describe('org:open', () => {
   const testPath = '/lightning/whatever';
   const expectedDefaultUrl = `${testOrg.instanceUrl}/secur/frontdoor.jsp?sid=${testOrg.accessToken}`;
   const expectedUrl = `${expectedDefaultUrl}&retURL=${encodeURIComponent(testPath)}`;
+  const singleUseToken = (Math.random() + 1).toString(36).substring(2); // random string to simulate a single-use token
+  const expectedDefaultSingleUseUrl = `${testOrg.instanceUrl}/secur/frontdoor.jsp?otp=${singleUseToken}`;
 
   let sfCommandUxStubs: ReturnType<typeof stubSfCommandUx>;
 
@@ -45,6 +47,13 @@ describe('org:open', () => {
     stubSpinner($$.SANDBOX);
     await $$.stubAuths(testOrg);
     spies.set('open', stubMethod($$.SANDBOX, utils, 'openUrl').resolves(new EventEmitter()));
+    spies.set(
+      'requestGet',
+      stubMethod($$.SANDBOX, Connection.prototype, 'requestGet').resolves({
+        // eslint-disable-next-line camelcase
+        frontdoor_uri: expectedDefaultSingleUseUrl,
+      })
+    );
   });
 
   afterEach(() => {
@@ -157,6 +166,55 @@ describe('org:open', () => {
       expect(response.url).to.equal(expectedUrl);
       delete process.env.FORCE_OPEN_URL;
     });
+
+    it('generates a single-use frontdoor url when neither --url-only nor --json flag are passed in', async () => {
+      spies.set('resolver', stubMethod($$.SANDBOX, SfdcUrl.prototype, 'checkLightningDomain').resolves('1.1.1.1'));
+      const response = await OrgOpenCommand.run(['--targetusername', testOrg.username]);
+      expect(response.url).to.equal(expectedDefaultSingleUseUrl);
+      // verify we called to the correct endpoint to generate the single-use AT
+      expect(spies.get('requestGet').callCount).to.equal(1);
+      expect(spies.get('requestGet').args[0][0]).to.deep.equal('/services/oauth2/singleaccess');
+    });
+
+    it('honors SF_SINGLE_USE_ORG_OPEN_URL env var and generates a single-use frontdoor url even if --url-only or --json flag are passed in', async () => {
+      process.env.SF_SINGLE_USE_ORG_OPEN_URL = 'true';
+      spies.set('resolver', stubMethod($$.SANDBOX, SfdcUrl.prototype, 'checkLightningDomain').resolves('1.1.1.1'));
+      const response = await OrgOpenCommand.run(['--targetusername', testOrg.username, '--json', '--url-only']);
+      expect(response.url).to.equal(expectedDefaultSingleUseUrl);
+      // verify we called to the correct endpoint to generate the single-use AT
+      expect(spies.get('requestGet').callCount).to.equal(1);
+      expect(spies.get('requestGet').args[0][0]).to.deep.equal('/services/oauth2/singleaccess');
+      delete process.env.SF_SINGLE_USE_ORG_OPEN_URL;
+    });
+
+    it('handles api error', async () => {
+      $$.SANDBOX.restore();
+      const mockError = new Error('Invalid_Scope');
+      $$.SANDBOX.stub(Connection.prototype, 'requestGet').throws(mockError);
+      try {
+        await OrgOpenCommand.run(['--targetusername', testOrg.username]);
+        expect.fail('should have thrown Invalid_Scope');
+      } catch (e) {
+        assert(e instanceof SfError, 'should be an SfError');
+        expect(e.name).to.equal('Invalid_Scope');
+        expect(e.message).to.equal(sharedMessages.getMessage('SingleAccessFrontdoorError'));
+      }
+    });
+
+    it('handles invalid responde from api', async () => {
+      $$.SANDBOX.restore();
+      $$.SANDBOX.stub(Connection.prototype, 'requestGet').resolves({
+        invalid: 'some invalid response',
+      });
+      try {
+        await OrgOpenCommand.run(['--targetusername', testOrg.username]);
+        expect.fail('should have thrown Invalid_Scope');
+      } catch (e) {
+        assert(e instanceof SfError, 'should be an SfError');
+        expect(e.message).to.equal(sharedMessages.getMessage('SingleAccessFrontdoorError'));
+        expect(e.data).to.contain({ invalid: 'some invalid response' });
+      }
+    });
   });
 
   describe('domain resolution, with callout', () => {
@@ -263,6 +321,7 @@ describe('org:open', () => {
         )
       );
       expect(sfCommandUxStubs.warn.calledOnceWith(sharedMessages.getMessage('SecurityWarning')));
+      expect(sfCommandUxStubs.warn.calledOnceWith(sharedMessages.getMessage('BehaviorChangeWarning')));
 
       expect(spies.get('resolver').callCount).to.equal(1);
       expect(spies.get('open').callCount).to.equal(1);
@@ -275,6 +334,7 @@ describe('org:open', () => {
       await OrgOpenCommand.run(['--targetusername', testOrg.username, '--path', testPath, '-b', testBrowser]);
 
       expect(sfCommandUxStubs.warn(sharedMessages.getMessage('SecurityWarning')));
+      expect(sfCommandUxStubs.warn.calledOnceWith(sharedMessages.getMessage('BehaviorChangeWarning')));
       expect(
         sfCommandUxStubs.logSuccess.calledOnceWith(
           messages.getMessage('humanSuccessNoUrl', [testOrg.orgId, testOrg.username])
