feat: managed connection inclusion (#1242)

palashgdev · web-flow · commit 13723fa612bd · 2026-01-08T14:29:51.000+05:30
* fix: managed connection inclusion

* fix: remove Username-Password-Authentication from included connections example

* chore: resolve comments

* feat: add support for included connections in YAML context and update schema

* feat: enforce exclusive configuration for AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS

* fix: update AUTH0 connection handling to respect include list

- Adjusted logic to ensure 'enterprise-saml' is not marked for deletion when not in the include list.
- Modified tests to reflect that 'google-oauth2' should not be deleted if it's not in the include list.
- Updated behavior to only delete managed connections when assets are empty, preserving unmanaged ones.
- Ensured that unmanaged connections are ignored during updates, preventing unintended deletions.

* fix: update included connections in environment variable example

* fix: include rules in initial assets for proper asset management

* feat: add filterIncluded function to manage included connections in changes

* feat: enhance connection processing to respect included connections and improve test coverage
diff --git a/docs/configuring-the-deploy-cli.md b/docs/configuring-the-deploy-cli.md
@@ -86,6 +86,41 @@ String. Specifies the JWT signing algorithms used by the client when facilitatin
 
 Boolean. When enabled, will allow the tool to delete resources. Default: `false`.
 
+### `AUTH0_INCLUDED_CONNECTIONS`
+
+Array of strings. Specifies which connections should be managed by the Deploy CLI. When configured, only the connections listed by name will be included in export and import operations. All other connections in the tenant will be completely ignored.
+
+This is particularly useful for:
+- Managing only specific connections while preserving others (e.g., self-service SSO connections, third-party integrations)
+- Preventing accidental modifications to connections managed by other systems
+- Isolating connection management to specific subsets of your tenant
+
+**Important:** This setting affects all operations (export and import). Connections not in this list will not appear in exports and will not be modified during imports.
+
+Cannot be used simultaneously with `AUTH0_EXCLUDED_CONNECTIONS`.
+
+#### Example
+
+```json
+{
+  "AUTH0_INCLUDED_CONNECTIONS": ["github", "google-oauth2"]
+}
+```
+
+In the example above, only the `github` and `google-oauth2` connections will be managed. All other connections in the tenant will be ignored.
+
+#### Environment Variable Format
+
+When passing as an environment variable, use JSON array format:
+
+```shell
+# JSON array format
+export AUTH0_INCLUDED_CONNECTIONS='["github","google-oauth2"]'
+
+# Or as a single-line array
+export AUTH0_INCLUDED_CONNECTIONS='["github"]'
+```
+
 ### `AUTH0_EXCLUDED`
 
 Array of strings. Excludes entire resource types from being managed, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `phoneProviders`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`, `selfServiceProfiles`.
@@ -175,6 +210,8 @@ Array of strings. Excludes the management of specific databases by name. **Note:
 
 Array of strings. Excludes the management of specific connections by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
 
+Cannot be used simultaneously with `AUTH0_INCLUDED_CONNECTIONS`.
+
 ### `AUTH0_EXCLUDED_RESOURCE_SERVERS`
 
 Array of strings. Excludes the management of specific resource servers by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
diff --git a/src/context/directory/index.ts b/src/context/directory/index.ts
@@ -40,6 +40,10 @@ export default class DirectoryContext {
       resourceServers: config.AUTH0_EXCLUDED_RESOURCE_SERVERS || [],
       defaults: config.AUTH0_EXCLUDED_DEFAULTS || [],
     };
+
+    this.assets.include = {
+      connections: config.AUTH0_INCLUDED_CONNECTIONS || [],
+    };
   }
 
   loadFile(f: string, folder: string) {
diff --git a/src/context/index.ts b/src/context/index.ts
@@ -24,6 +24,7 @@ const nonPrimitiveProps: (keyof Config)[] = [
   'AUTH0_INCLUDED_ONLY',
   'EXCLUDED_PROPS',
   'INCLUDED_PROPS',
+  'AUTH0_INCLUDED_CONNECTIONS',
 ];
 
 const EA_FEATURES = [];
@@ -134,6 +135,21 @@ export const setupContext = async (
     }
   })(config);
 
+  ((config: Config) => {
+    const hasIncludedConnections =
+      config.AUTH0_INCLUDED_CONNECTIONS !== undefined &&
+      config.AUTH0_INCLUDED_CONNECTIONS.length > 0;
+    const hasExcludedConnections =
+      config.AUTH0_EXCLUDED_CONNECTIONS !== undefined &&
+      config.AUTH0_EXCLUDED_CONNECTIONS.length > 0;
+
+    if (hasIncludedConnections && hasExcludedConnections) {
+      throw new Error(
+        'Both AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS configuration values are defined, only one can be configured at a time.'
+      );
+    }
+  })(config);
+
   ((config: Config) => {
     // Check if experimental early access features are enabled
     if (config.AUTH0_EXPERIMENTAL_EA) {
diff --git a/src/context/yaml/index.ts b/src/context/yaml/index.ts
@@ -46,6 +46,10 @@ export default class YAMLContext {
       defaults: config.AUTH0_EXCLUDED_DEFAULTS || [],
     };
 
+    this.assets.include = {
+      connections: config.AUTH0_INCLUDED_CONNECTIONS || [],
+    };
+
     this.basePath = (() => {
       if (!!config.AUTH0_BASE_PATH) return config.AUTH0_BASE_PATH;
       //@ts-ignore because this looks to be a bug, but do not want to introduce regression; more investigation needed
@@ -100,6 +104,7 @@ export default class YAMLContext {
 
     const initialAssets: Assets = {
       exclude: this.assets.exclude, // Keep the exclude rules in result assets
+      include: this.assets.include, // Keep the include rules in result assets
     };
     this.assets = Object.keys(this.assets).reduce((acc: Assets, key: AssetTypes) => {
       // Get the list of asset types to include
@@ -202,6 +207,7 @@ export default class YAMLContext {
 
     // Delete exclude as it's not part of the auth0 tenant config
     delete cleaned.exclude;
+    delete cleaned.include;
 
     // Optionally Strip identifiers
     if (!this.config.AUTH0_EXPORT_IDENTIFIERS) {
diff --git a/src/tools/auth0/handlers/connections.ts b/src/tools/auth0/handlers/connections.ts
@@ -2,7 +2,13 @@ import dotProp from 'dot-prop';
 import { chunk, keyBy } from 'lodash';
 import { Management, ManagementError } from 'auth0';
 import DefaultAPIHandler, { order } from './default';
-import { filterExcluded, convertClientNameToId, getEnabledClients, sleep } from '../../utils';
+import {
+  filterExcluded,
+  convertClientNameToId,
+  getEnabledClients,
+  sleep,
+  filterIncluded,
+} from '../../utils';
 import { CalculatedChanges, Asset, Assets, Auth0APIClient } from '../../../types';
 import { ConfigFunction } from '../../../configFactory';
 import { paginate } from '../client';
@@ -621,6 +627,7 @@ export default class ConnectionsHandler extends DefaultAPIHandler {
       ...this.getFormattedOptions(connection, clients),
       enabled_clients: getEnabledClients(assets, connection, existingConnections, clients),
     }));
+
     const proposedChanges = await super.calcChanges({ ...assets, connections: formatted });
 
     const proposedChangesWithExcludedProperties = addExcludedConnectionPropertiesToChanges({
@@ -648,20 +655,20 @@ export default class ConnectionsHandler extends DefaultAPIHandler {
       );
     }
 
+    const includedConnections = (assets.include && assets.include.connections) || [];
     const excludedConnections = (assets.exclude && assets.exclude.connections) || [];
 
-    const changes = await this.calcChanges(assets);
+    let changes = await this.calcChanges(assets);
+
+    changes = filterExcluded(changes, excludedConnections);
+    changes = filterIncluded(changes, includedConnections);
 
-    await super.processChanges(assets, filterExcluded(changes, excludedConnections));
+    await super.processChanges(assets, changes);
 
     // process enabled clients
-    await processConnectionEnabledClients(
-      this.client,
-      this.type,
-      filterExcluded(changes, excludedConnections)
-    );
+    await processConnectionEnabledClients(this.client, this.type, changes);
 
     // process directory provisioning
-    await this.processConnectionDirectoryProvisioning(filterExcluded(changes, excludedConnections));
+    await this.processConnectionDirectoryProvisioning(changes);
   }
 }
diff --git a/src/tools/auth0/handlers/index.ts b/src/tools/auth0/handlers/index.ts
@@ -85,5 +85,10 @@ const auth0ApiHandlers: { [key in AssetTypes]: any } = {
 };
 
 export default auth0ApiHandlers as {
-  [key in AssetTypes]: { default: typeof APIHandler; excludeSchema?: any; schema: any };
+  [key in AssetTypes]: {
+    default: typeof APIHandler;
+    excludeSchema?: any;
+    schema: any;
+    includeSchema?: any;
+  };
 }; // TODO: apply stronger types to schema properties
diff --git a/src/tools/auth0/schema.ts b/src/tools/auth0/schema.ts
@@ -18,6 +18,16 @@ const excludeSchema = Object.entries(handlers).reduce(
   {}
 );
 
+const includeSchema = Object.entries(handlers).reduce(
+  (map: { [key: string]: Object }, [name, obj]) => {
+    if (obj.includeSchema) {
+      map[name] = obj.includeSchema;
+    }
+    return map;
+  },
+  {}
+);
+
 export default {
   type: 'object',
   $schema: 'http://json-schema.org/draft-07/schema#',
@@ -28,6 +38,11 @@ export default {
       properties: { ...excludeSchema },
       default: {},
     },
+    include: {
+      type: 'object',
+      properties: { ...includeSchema },
+      default: {},
+    },
   },
   additionalProperties: false,
 };
diff --git a/src/tools/utils.ts b/src/tools/utils.ts
@@ -199,6 +199,23 @@ export function filterExcluded(changes: CalculatedChanges, exclude: string[]): C
   };
 }
 
+export function filterIncluded(changes: CalculatedChanges, include: string[]): CalculatedChanges {
+  const { del, update, create, conflicts } = changes;
+
+  if (!include || !include.length) {
+    return changes;
+  }
+
+  const filter = (list: Asset[]) => list.filter((item) => include.includes(item.name));
+
+  return {
+    del: filter(del),
+    update: filter(update),
+    create: filter(create),
+    conflicts: filter(conflicts),
+  };
+}
+
 export function areArraysEquals(x: any[], y: any[]): boolean {
   return _.isEqual(x && x.sort(), y && y.sort());
 }
diff --git a/src/types.ts b/src/types.ts
@@ -82,6 +82,7 @@ export type Config = {
   INCLUDED_PROPS?: {
     [key: string]: string[];
   };
+  AUTH0_INCLUDED_CONNECTIONS?: string[];
   AUTH0_IGNORE_UNAVAILABLE_MIGRATIONS?: boolean;
   // Eventually deprecate. See: https://github.com/auth0/auth0-deploy-cli/issues/451#user-content-deprecated-exclusion-props
   AUTH0_EXCLUDED_RULES?: string[];
@@ -138,6 +139,9 @@ export type Assets = Partial<{
   exclude?: {
     [key: string]: string[];
   };
+  include?: {
+    [key: string]: string[];
+  };
   clientsOrig: Asset[] | null;
   themes: Theme[] | null;
   forms: Form[] | null;
diff --git a/test/context/context.test.js b/test/context/context.test.js
@@ -255,6 +255,49 @@ describe('#context loader validation', async () => {
       'Need to define at least one resource type in AUTH0_INCLUDED_ONLY configuration. See: https://github.com/auth0/auth0-deploy-cli/blob/master/docs/configuring-the-deploy-cli.md#auth0_included_only'
     );
   });
+
+  it('should error if trying to configure AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS simultaneously', async () => {
+    const dir = path.resolve(testDataDir, 'context');
+    cleanThenMkdir(dir);
+    const yaml = path.join(dir, 'empty.yaml');
+    fs.writeFileSync(yaml, '');
+
+    await expect(
+      setupContext(
+        {
+          ...config,
+          AUTH0_INPUT_FILE: yaml,
+          AUTH0_INCLUDED_CONNECTIONS: ['github', 'google-oauth2'],
+          AUTH0_EXCLUDED_CONNECTIONS: ['facebook'],
+        },
+        'import'
+      )
+    ).to.be.rejectedWith(
+      'Both AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS configuration values are defined, only one can be configured at a time.'
+    );
+
+    await expect(
+      setupContext(
+        {
+          ...config,
+          AUTH0_INCLUDED_CONNECTIONS: ['github', 'google-oauth2'],
+          AUTH0_INPUT_FILE: yaml,
+        },
+        'import'
+      )
+    ).to.be.not.rejected;
+
+    await expect(
+      setupContext(
+        {
+          ...config,
+          AUTH0_EXCLUDED_CONNECTIONS: ['facebook'],
+          AUTH0_INPUT_FILE: yaml,
+        },
+        'import'
+      )
+    ).to.be.not.rejected;
+  });
 });
 
 describe('#filterOnlyIncludedResourceTypes', async () => {
diff --git a/test/context/directory/context.test.js b/test/context/directory/context.test.js
@@ -15,7 +15,7 @@ describe('#directory context validation', () => {
     const context = new Context({ AUTH0_INPUT_FILE: dir }, mockMgmtClient());
     await context.loadAssetsFromLocal();
 
-    expect(Object.keys(context.assets).length).to.equal(Object.keys(handlers).length + 1);
+    expect(Object.keys(context.assets).length).to.equal(Object.keys(handlers).length + 2);
     Object.keys(context.assets).forEach((key) => {
       if (key === 'exclude') {
         expect(context.assets[key]).to.deep.equal({
@@ -26,6 +26,10 @@ describe('#directory context validation', () => {
           resourceServers: [],
           defaults: [],
         });
+      } else if (key === 'include') {
+        expect(context.assets[key]).to.deep.equal({
+          connections: [],
+        });
       } else {
         expect(context.assets[key]).to.equal(null);
       }
@@ -57,6 +61,20 @@ describe('#directory context validation', () => {
     expect(context.assets.exclude.defaults).to.deep.equal(['emailProvider']);
   });
 
+  it('should load includes', async () => {
+    const dir = path.resolve(testDataDir, 'directory', 'empty');
+    cleanThenMkdir(dir);
+
+    const config = {
+      AUTH0_INPUT_FILE: dir,
+      AUTH0_INCLUDED_CONNECTIONS: ['github', 'google-oauth2'],
+    };
+    const context = new Context(config, mockMgmtClient());
+    await context.loadAssetsFromLocal();
+
+    expect(context.assets.include.connections).to.deep.equal(['github', 'google-oauth2']);
+  });
+
   it('should respect resource exclusion on import', async () => {
     const tenantConfig = {
       allowed_logout_urls: ['https://mycompany.org/logoutCallback'],
diff --git a/test/context/yaml/context.test.js b/test/context/yaml/context.test.js
@@ -67,6 +67,23 @@ describe('#YAML context validation', () => {
     expect(context.assets.exclude.defaults).to.deep.equal(['emailProvider']);
   });
 
+  it('should load includes', async () => {
+    const dir = path.resolve(testDataDir, 'yaml', 'empty');
+    cleanThenMkdir(dir);
+    const yaml = path.join(dir, 'empty.yaml');
+    fs.writeFileSync(yaml, '');
+
+    const config = {
+      AUTH0_INPUT_FILE: yaml,
+      AUTH0_INCLUDED_CONNECTIONS: ['github', 'google-oauth2'],
+    };
+
+    const context = new Context(config, mockMgmtClient());
+    await context.loadAssetsFromLocal();
+
+    expect(context.assets.include.connections).to.deep.equal(['github', 'google-oauth2']);
+  });
+
   it('should respect resource exclusion on import', async () => {
     /* Create empty directory */
     const dir = path.resolve(testDataDir, 'yaml', 'resource-exclusion');
diff --git a/test/e2e/recordings/should-deploy-while-deleting-resources-if-AUTH0_ALLOW_DELETE-is-true.json b/test/e2e/recordings/should-deploy-while-deleting-resources-if-AUTH0_ALLOW_DELETE-is-true.json
diff --git a/test/e2e/recordings/should-deploy-without-deleting-resources-if-AUTH0_ALLOW_DELETE-is-false.json b/test/e2e/recordings/should-deploy-without-deleting-resources-if-AUTH0_ALLOW_DELETE-is-false.json
diff --git a/test/e2e/recordings/should-deploy-without-throwing-an-error.json b/test/e2e/recordings/should-deploy-without-throwing-an-error.json
diff --git a/test/e2e/recordings/should-dump-and-deploy-without-throwing-an-error.json b/test/e2e/recordings/should-dump-and-deploy-without-throwing-an-error.json
diff --git a/test/tools/auth0/handlers/connections.tests.js b/test/tools/auth0/handlers/connections.tests.js
