feat: managed connection inclusion

docs/configuring-the-deploy-cli.md

@@ -86,6 +86,59 @@ 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, import, update, and delete 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, import, update, and delete). Connections not in this list will not appear in exports and will not be modified during imports.
+
+#### 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","Username-Password-Authentication"]'
+
+# Or as a single-line array
+export AUTH0_INCLUDED_CONNECTIONS='["github"]'
+```
+
+#### Use Cases
+
+**Scenario 1: Self-Service SSO**
+If your organization allows users to create their own SAML or OIDC connections through a self-service portal, you can exclude those connections from Deploy CLI management:
+
+```json
+{
+  "AUTH0_INCLUDED_CONNECTIONS": ["github", "google-oauth2"]
+}
+```
+
+**Scenario 2: Environment-Specific Connections**
+Manage only connections relevant to a specific environment:
+
+```json
+{
+  "AUTH0_INCLUDED_CONNECTIONS": ["dev-database", "dev-google-oauth2"]
+}
+```
+
 ### `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`.

src/tools/auth0/handlers/connections.ts

@@ -313,7 +313,17 @@ export default class ConnectionsHandler extends DefaultAPIHandler {
     });
 
     // Filter out database connections as we have separate handler for it
-    const filteredConnections = connections.filter((c) => c.strategy !== 'auth0');
+    let filteredConnections = connections.filter((c) => c.strategy !== 'auth0');
+
+    const managedConnectionNames = this.config('AUTH0_INCLUDED_CONNECTIONS');
+    if (managedConnectionNames) {
+      filteredConnections = filteredConnections.filter((conn) =>
+        managedConnectionNames.includes(conn.name ?? '')
+      );
+      log.info(
+        `AUTH0_INCLUDED_CONNECTIONS is configured. Retrieved ${filteredConnections.length} managed connection(s) from tenant.`
+      );
+    }
 
     // If options option is empty for all connection, log the missing options scope.
     const isOptionExists = filteredConnections.every(
@@ -359,6 +369,18 @@ export default class ConnectionsHandler extends DefaultAPIHandler {
         conflicts: [],
       };
 
+    const managedConnectionNames = this.config('AUTH0_INCLUDED_CONNECTIONS');
+    const filteredConnections = managedConnectionNames
+      ? connections.filter((conn) => managedConnectionNames.includes(conn.name))
+      : connections;
+
+    if (managedConnectionNames && filteredConnections.length !== connections.length) {
+      const excludedCount = connections.length - filteredConnections.length;
+      log.info(
+        `AUTH0_INCLUDED_CONNECTIONS is configured. Managing ${filteredConnections.length} connection(s), ignoring ${excludedCount} connection(s) not in the managed list.`
+      );
+    }
+
     // Convert enabled_clients by name to the id
     const clients = await paginate<Client>(this.client.clients.list, {
       paginate: true,
@@ -373,7 +395,7 @@ export default class ConnectionsHandler extends DefaultAPIHandler {
     // Prepare an id map. We'll use this map later to get the `strategy` and SCIM enable status of the connections.
     await this.scimHandler.createIdMap(existingConnections);
 
-    const formatted = connections.map((connection) => ({
+    const formatted = filteredConnections.map((connection) => ({
       ...connection,
       ...this.getFormattedOptions(connection, clients),
       enabled_clients: getEnabledClients(assets, connection, existingConnections, clients),

src/types.ts

@@ -81,6 +81,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[];