added custom domain

Author: rishigupta-3

README.md

@@ -36,7 +36,7 @@ Please visit [Twilio Docs](https://www.twilio.com/docs/flex/developer/plugins) f
 * [Plugins API](https://www.twilio.com/docs/flex/developer/plugins/api)
 * [Troubleshooting and FAQ](faq.md)
 
-> **Important:** Starting with the latest version, local development uses `flex.local.com` instead of `localhost`. Please see the [FAQ](faq.md) for setup instructions.
+> **Note:** When using SSO v2 (OAuth flow), you may need to configure a custom domain for local development using the `--domain` flag to avoid authentication issues. See the [FAQ](faq.md) for setup instructions.
 
 ## Changelog
 

faq.md

@@ -1,29 +1,60 @@
 # Troubleshooting & FAQ
 
-#### Local Development URLs Changed from localhost to flex.local.com
+#### Configuring Custom Domain for Local Development
 
-Starting with this version, local plugin development uses `flex.local.com` instead of `localhost` to avoid login-related issues. You need to configure your local hosts file to point `flex.local.com` to `127.0.0.1`.
+You can configure a custom domain for local plugin development using the `--domain` flag. This is particularly important when using SSO v2 (OAuth flow), as `localhost` can cause authentication issues during login due to OAuth redirect URI restrictions.
 
-**On macOS/Linux:**
-1. Open Terminal
-2. Run: `sudo vim /etc/hosts` (or use your preferred text editor)
-3. Add this line: `127.0.0.1 flex.local.com`
-4. Save the file
+**Why use a custom domain?**
+- **SSO v2 OAuth Flow**: If you're using Twilio Flex with SSO v2 (OAuth authentication flow), `localhost` URLs may not be accepted as valid redirect URIs, causing login authentication failures
+- **CORS Issues**: Some authentication systems restrict `localhost` for security reasons
+- **Development Consistency**: Using a custom domain provides a more production-like development environment
 
-**On Windows:**
-1. Open Notepad as Administrator
-2. Open the file: `C:\Windows\System32\drivers\etc\hosts`
-3. Add this line: `127.0.0.1 flex.local.com`
-4. Save the file
+**Usage:**
+```bash
+twilio flex:plugins:start --domain flex.local.com
+```
+
+**Setting up the custom domain:**
+1. **macOS/Linux**: Add the domain to `/etc/hosts`
+   ```bash
+   sudo echo "127.0.0.1 flex.local.com" >> /etc/hosts
+   ```
+
+2. **Windows**: Add the domain to `C:\Windows\System32\drivers\etc\hosts`
+   ```
+   127.0.0.1 flex.local.com
+   ```
+
+**Available Options:**
+- Without `--domain`: Uses `localhost` (default behavior, may cause issues with SSO v2)
+- With `--domain flex.local.com`: Uses `flex.local.com` 
+- With `--domain my-custom.dev`: Uses any custom domain you prefer
 
-After making this change, your local plugin development server will be accessible at `http://flex.local.com:3000` instead of `http://localhost:3000`.
+**When is this required?**
+- **SSO v2 Users**: If your Twilio Flex instance uses SSO v2 with OAuth authentication, you will likely encounter login failures when using `localhost`
+- **CORS-restricted environments**: Some authentication providers block `localhost` requests
+- **Custom OAuth configurations**: If your OAuth provider has strict redirect URI policies
 
-**Quick Setup Script (macOS/Linux only):**
-You can also run the provided script to automatically configure your hosts file:
+After configuring your hosts file, your local plugin development server will be accessible at the specified domain (e.g., `http://flex.local.com:3000`).
+
+#### SSO v2 OAuth Authentication Issues with localhost
+
+If you're experiencing login failures during local development, especially with error messages related to OAuth redirects or authentication, this is likely due to SSO v2 OAuth flow restrictions with `localhost` URLs.
+
+**Common Error Symptoms:**
+- Login redirects fail or loop infinitely
+- OAuth callback errors mentioning invalid redirect URI
+- Authentication timeouts during local development
+- CORS errors related to authentication endpoints
+
+**Solution:**
+Use the `--domain` flag with a custom domain:
 ```bash
-./scripts/setup-hosts.sh
+twilio flex:plugins:start --domain flex.local.com
 ```
 
+Make sure to add the domain to your hosts file as described above. This resolves the OAuth redirect URI validation issues that occur with `localhost`.
+
 #### npm install fails on NPM 7
 
 If you are using `npm 7` (you can find out the version by typing `npm -v` in your terminal), then you may get the following error when you run `npm install`:

packages/flex-dev-utils/src/__tests__/urls.test.ts

@@ -37,9 +37,26 @@ describe('urls', () => {
 
     beforeEach(() => {
       process.env = { ...OLD_ENV };
+      delete process.env.DOMAIN; // Ensure clean state
     });
 
-    it('should return http', () => {
+    it('should return http with localhost (default)', () => {
+      const ip = jest.spyOn(address, 'ip').mockReturnValue('192.0.0.0');
+      const result = urls.getLocalAndNetworkUrls(1234);
+
+      expect(result.local.host).toEqual('0.0.0.0');
+      expect(result.local.port).toEqual(1234);
+      expect(result.local.url).toEqual('http://localhost:1234/');
+
+      expect(result.network.host).toEqual('192.0.0.0');
+      expect(result.network.port).toEqual(1234);
+      expect(result.network.url).toEqual('http://192.0.0.0:1234/');
+
+      ip.mockRestore();
+    });
+
+    it('should return http with custom domain', () => {
+      process.env.DOMAIN = 'flex.local.com';
       const ip = jest.spyOn(address, 'ip').mockReturnValue('192.0.0.0');
       const result = urls.getLocalAndNetworkUrls(1234);
 
@@ -54,14 +71,31 @@ describe('urls', () => {
       ip.mockRestore();
     });
 
-    it('should return https', () => {
+    it('should return https with localhost (default)', () => {
+      process.env.HTTPS = 'true';
+      const ip = jest.spyOn(address, 'ip').mockReturnValue('192.0.0.0');
+      const result = urls.getLocalAndNetworkUrls(1234);
+
+      expect(result.local.host).toEqual('0.0.0.0');
+      expect(result.local.port).toEqual(1234);
+      expect(result.local.url).toEqual('https://localhost:1234/');
+
+      expect(result.network.host).toEqual('192.0.0.0');
+      expect(result.network.port).toEqual(1234);
+      expect(result.network.url).toEqual('https://192.0.0.0:1234/');
+
+      ip.mockRestore();
+    });
+
+    it('should return https with custom domain', () => {
       process.env.HTTPS = 'true';
+      process.env.DOMAIN = 'secure.local.dev';
       const ip = jest.spyOn(address, 'ip').mockReturnValue('192.0.0.0');
       const result = urls.getLocalAndNetworkUrls(1234);
 
       expect(result.local.host).toEqual('0.0.0.0');
       expect(result.local.port).toEqual(1234);
-      expect(result.local.url).toEqual('https://flex.local.com:1234/');
+      expect(result.local.url).toEqual('https://secure.local.dev:1234/');
 
       expect(result.network.host).toEqual('192.0.0.0');
       expect(result.network.port).toEqual(1234);

packages/flex-dev-utils/src/urls.ts

@@ -77,15 +77,21 @@ export const findPort = async (startPort: number = 3000): Promise<number> => {
 /**
  * Returns the local and network urls
  * @param port  the port the server is running on
- * @note Changed from localhost to flex.local.com to avoid login-related issues
+ * @note Uses configurable domain instead of localhost to avoid SSO v2 OAuth authentication issues
  */
 export const getLocalAndNetworkUrls = (port: number): InternalServiceUrls => {
   const protocol = env.isHTTPS() ? 'https' : 'http';
+  const customDomain = env.getDomain();
+
+  let localHostname = 'localhost';
+  if (customDomain) {
+    localHostname = customDomain;
+  }
 
   const localUrl = url.format({
     protocol,
     port,
-    hostname: 'flex.local.com',
+    hostname: localHostname,
     pathname: '/',
   });
   const networkUrl = url.format({
@@ -99,7 +105,7 @@ export const getLocalAndNetworkUrls = (port: number): InternalServiceUrls => {
     local: {
       url: localUrl,
       port,
-      host: '0.0.0.0',
+      host: '0.0.0.0', // Keep binding host as 0.0.0.0 for proper network access
     },
     network: {
       url: networkUrl,

packages/flex-plugin-webpack/src/devServer/pluginServer.ts

@@ -55,6 +55,7 @@ export const _getLocalPlugin = (name: string): FlexConfigurationPlugin | undefin
 // eslint-disable-next-line import/no-unused-modules
 export const _getLocalPlugins = (port: Port, names: string[]): Plugin[] => {
   const protocol = `http${env.isHTTPS() ? 's' : ''}://`;
+  const domain = env.getDomain() || 'localhost';
 
   return names.map((name) => {
     const match = _getLocalPlugin(name);
@@ -63,7 +64,7 @@ export const _getLocalPlugins = (port: Port, names: string[]): Plugin[] => {
       return {
         phase: 3,
         name,
-        src: `${protocol}localhost:${port}/plugins/${name}.js`,
+        src: `${protocol}${domain}:${port}/plugins/${name}.js`,
       };
     }
 

packages/flex-plugin-webpack/src/webpack/webpack.dev.ts

@@ -12,19 +12,20 @@ import { WebpackType } from '..';
 // eslint-disable-next-line import/no-unused-modules
 export const _getBase = (): Configuration => {
   const { local } = getLocalAndNetworkUrls(env.getPort());
+  const customDomain = env.getDomain();
 
   return {
     compress: true,
     static: {},
     client: {
       logging: 'none',
       webSocketURL: {
-        hostname: local.host,
+        hostname: customDomain || local.host,
         pathname: local.url,
         port: env.getPort(),
       },
     },
-    host: env.getHost(),
+    host: env.getHost() || '0.0.0.0', // Keep binding to 0.0.0.0 for network access
     port: env.getPort(),
   };
 };

packages/flex-plugins-utils-env/src/index.ts

@@ -1,3 +1,3 @@
 /* eslint-disable import/no-unused-modules */
 
-export { default, default as env, Environment, Lifecycle, Region } from './lib/env';
+export { default, default as env, Environment, Lifecycle, Region, setDomain, getDomain, hasDomain } from './lib/env';

packages/flex-plugins-utils-env/src/lib/__tests__/env.test.ts

@@ -325,6 +325,33 @@ describe('env', () => {
     });
   });
 
+  describe('domain', () => {
+    it('should return domain', () => {
+      process.env.DOMAIN = 'flex.local.com';
+      expect(env.getDomain()).toEqual('flex.local.com');
+    });
+
+    it('getDomain should return nothing', () => {
+      expect(env.getDomain()).toEqual(undefined);
+    });
+
+    it('should set domain', () => {
+      expect(env.getDomain()).toEqual(undefined);
+      env.setDomain('my-custom.domain');
+      expect(env.getDomain()).toEqual('my-custom.domain');
+    });
+
+    it('hasDomain should return true when domain is set', () => {
+      env.setDomain('test.domain');
+      expect(env.hasDomain()).toBe(true);
+    });
+
+    it('hasDomain should return false when domain is not set', () => {
+      delete process.env.DOMAIN;
+      expect(env.hasDomain()).toBe(false);
+    });
+  });
+
   describe('port', () => {
     it('should return port', () => {
       process.env.PORT = '1234';

packages/flex-plugins-utils-env/src/lib/env.ts

@@ -86,6 +86,9 @@ export const getAccountSid = (): string | undefined => getProcessEnv('TWILIO_ACC
 export const getAuthToken = (): string | undefined => getProcessEnv('TWILIO_AUTH_TOKEN');
 export const hasHost = (): boolean => isDefined(getProcessEnv('HOST'));
 export const getHost = (): string | undefined => getProcessEnv('HOST');
+export const hasDomain = (): boolean => isDefined(getProcessEnv('DOMAIN'));
+export const getDomain = (): string | undefined => getProcessEnv('DOMAIN');
+export const setDomain = (domain: string): void => setProcessEnv('DOMAIN', domain);
 export const setHost = (host: string): void => setProcessEnv('HOST', host);
 export const hasPort = (): boolean => isDefined(getProcessEnv('PORT'));
 export const getPort = (): number => Number(getProcessEnv('PORT'));
@@ -257,6 +260,9 @@ export default {
   hasHost,
   getHost,
   setHost,
+  hasDomain,
+  getDomain,
+  setDomain,
   hasPort,
   getPort,
   setPort,

packages/plugin-flex/package.json

@@ -105,7 +105,8 @@
         "flags": {
           "name": "The name of the plugin you would like to run. You can provide multiple to run them all concurrently. You can include specific active remote plugins using \"--name 'plugin-name@remote'\" or \"--name 'plugin-name@0.0.0'\" for a specific remote version.",
           "includeRemote": "Use this flag to include all remote plugins in your build.",
-          "port": "The port to start your local development server on."
+          "port": "The port to start your local development server on.",
+          "domain": "The domain to start your local development server on. Required when using SSO v2 OAuth flow to avoid authentication issues."
         }
       },
       "flex:plugins:deploy": {