How to Use EXCLUDED_PROPS and INCLUDED_PROPS for Property-Level Filtering in Auth0 Deploy CLI

Use EXCLUDED_PROPS to strip specific properties from exported Auth0 tenant configurations and INCLUDED_PROPS to retain fields that would otherwise be removed by the CLI's default read-only field list, configuring both as resource-keyed maps in your JSON or YAML configuration file.

The auth0/auth0-deploy-cli repository provides granular control over infrastructure-as-code workflows through property-level filtering capabilities. By configuring EXCLUDED_PROPS and INCLUDED_PROPS in your configuration file, you can selectively remove sensitive data or unnecessary fields from exports while preserving secrets that the tool would normally strip automatically. These settings merge with built-in read-only field definitions in src/readonly.ts to customize exactly what gets written to your local configuration files.

Understanding EXCLUDED_PROPS and INCLUDED_PROPS

EXCLUDED_PROPS and INCLUDED_PROPS are configuration options that filter individual properties of Auth0 resources during dump and import operations. Both accept an object where keys are resource types (such as clients or connections) and values are arrays of property names.

Option	Type	Purpose
EXCLUDED_PROPS	{ [resource: string]: string[] }	Lists properties that must always be removed from the exported definition of the specified resource.
INCLUDED_PROPS	{ [resource: string]: string[] }	Lists properties that should be kept even if they appear in the default read-only list, effectively overriding the built-in exclusions.

The CLI maintains a default list of read-only fields—including client_secret, callback_url_template, and others—that are normally stripped to prevent secrets from leaking into version control. INCLUDED_PROPS acts as the inverse mechanism to re-add specific fields when you need them in your exported assets.

Core Implementation in src/readonly.ts

The merging logic lives in the getExcludedFields function within src/readonly.ts. This function combines your custom filters with the default readOnlyFields map:

// src/readonly.ts
function getExcludedFields(config: Config) {
  const strippedFields = { ...readOnlyFields };
  let { EXCLUDED_PROPS: excluded, INCLUDED_PROPS: included } = config;
  
  // Add user-provided excluded fields
  strippedFields[name] = (strippedFields[name] || []).concat(fields);
  
  // Remove any fields that the user explicitly included
  strippedFields[name] = strippedFields[name].filter(
    (field: string) => !fields.includes(field)
  );
}

The function validates that no property appears simultaneously in both maps. If getExcludedFields detects an intersection, the CLI throws a validation error:

if (intersections.length > 0) {
  throw new Error(
    `EXCLUDED_PROPS should NOT have any intersections with INCLUDED_PROPS. Intersections found: ${name}: ${intersections.join(', ')}`);
}

Configuration Examples

JSON Configuration Format

Define your filters in a JSON configuration file to strip custom login pages from clients and IDP-initiated settings from connections, while forcing the retention of client secrets:

{
  "AUTH0_DOMAIN": "mytenant.auth0.com",
  "AUTH0_CLIENT_ID": "xxxx",
  "AUTH0_CLIENT_SECRET": "yyyy",
  "EXCLUDED_PROPS": {
    "clients": [
      "client_secret",
      "custom_login_page"
    ],
    "connections": [
      "options.idp_initiated"
    ]
  },
  "INCLUDED_PROPS": {
    "clients": [
      "client_secret"
    ]
  }
}

YAML Configuration Format

The same filtering rules work in YAML syntax:

AUTH0_DOMAIN: mytenant.auth0.com
AUTH0_CLIENT_ID: xxxx
AUTH0_CLIENT_SECRET: yyyy
EXCLUDED_PROPS:
  clients:
    - custom_login_page
  connections:
    - options.idp_initiated
INCLUDED_PROPS:
  clients:
    - client_secret

Running the CLI with Property Filters

Execute the export command referencing your configuration file to apply the property-level filters:

# Export tenant configuration while applying the filters above

npm run build && node lib/index.js export \
  -c config.json \
  -f yaml \
  -o ./exported/

The resulting YAML or JSON files will not contain clients.custom_login_page or connections.options.idp_initiated. However, client_secret will remain present in the output because INCLUDED_PROPS overrides the default exclusion.

When Filtering Is Applied

During export, the cleanAssets function (also in src/readonly.ts) uses the calculated excludedFields to sanitize resources before writing them to disk. This ensures sensitive or unnecessary data never reaches your local file system.

During import, specific handlers may reference these maps to preserve certain values. For example, the connections handler in src/tools/auth0/handlers/connections.ts checks config()?.EXCLUDED_PROPS?.connections to maintain excluded options.* values while updating connection configurations, preventing the import process from overwriting settings you intentionally left out of your configuration files.

Summary

• EXCLUDED_PROPS removes specified properties from exported Auth0 resource definitions.
• INCLUDED_PROPS retains fields that would otherwise be stripped by the default read-only list in src/readonly.ts.
• The validation logic in getExcludedFields prevents conflicting configurations where a property appears in both lists simultaneously.
• Property filters apply during the export phase via cleanAssets and may be referenced by import handlers like the connections handler.
• Both options support dot notation for nested properties (for example, options.idp_initiated).

Frequently Asked Questions

What happens if I list the same property in both EXCLUDED_PROPS and INCLUDED_PROPS?

The CLI throws a validation error during configuration loading. The getExcludedFields function in src/readonly.ts explicitly checks for intersections between the two maps and fails with a message listing the conflicting properties, ensuring you cannot simultaneously include and exclude the same field.

Can I use dot notation to filter nested properties like options.idp_initiated?

Yes. The filtering mechanism supports dot notation for nested object paths. For example, configuring "connections": ["options.idp_initiated"] in EXCLUDED_PROPS targets specifically the idp_initiated key within the options object of connection definitions.

Do these filters modify my actual Auth0 tenant or only the exported files?

These filters primarily affect the exported configuration files written to your local file system. During import operations, handlers like the one in src/tools/auth0/handlers/connections.ts may reference EXCLUDED_PROPS to determine which existing tenant properties should be preserved rather than overwritten, but the filters do not delete data directly from the Auth0 tenant itself.

Where are the default read-only fields defined?

The default read-only field definitions reside in src/readonly.ts. This file contains the base readOnlyFields map that specifies which sensitive properties (such as client_secret and callback_url_template) are automatically stripped from exports unless explicitly retained via INCLUDED_PROPS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}