Allowed Domains Part 1 foundation

[Linker44]

Ticket ENG-2569

Description Of Changes

First of a 4-part series adding core domain validation for SaaS connector parameters. This PR establishes the foundational data model and validation logic.

• Adds type and allowed_values fields to ConnectorParam, replacing the previous allowed_domains attribute. type="endpoint" designates parameters requiring value validation. For allowed_values: None means no validation, [] means self-hosted (any value), and a populated list restricts to those wildcard patterns.
• Adds an enable_connector_param_allowed_values security config flag gated by dev mode.
• Adds wildcard-to-regex matching utilities (domain_util.py, validate_value_against_allowed_list).
• Adds a SaaSConfig model validator that ensures all client_config.host placeholders reference connector params of type="endpoint" with allowed_values defined.
• Updates the Stripe connector config as an example of the new format.

runtime enforcement is added in Parts 2 and 3

Code Changes

• Added type and allowed_values fields to ConnectorParam in saas_config.py
• Added SaaSConfig.validate_host_domain_restrictions model validator and _collect_client_config_hosts helper
• Created src/fides/api/util/domain_util.py with wildcard_to_regex
• Added is_domain_validation_disabled and validate_value_against_allowed_list to saas_util.py
• Added enable_connector_param_allowed_values to SecuritySettings
• Updated stripe_config.yml with type: endpoint and allowed_values on the domain param

Steps to Confirm

1. Verify that creating a SaaSConfig with type="endpoint" and allowed_values on a connector param and a host placeholder referencing that param passes validation
2. Verify that pointing client_config.host at a param without type="endpoint" or allowed_values (when another param has it) raises a validation error
3. Verify that configs with no type="endpoint" params skip validation entirely

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • All UX related changes have been reviewed by a designer
  • No UX review needed
• Followup issues:
  • Followup issues created
  • No followup issues
• Database migrations:
  • Ensure that your downrev is up to date with the latest revision on main
  • Ensure that your downgrade() migration is correct and works
    • If a downgrade migration is not possible for this change, please call this out in the PR description!
  • No migrations
• Documentation:
  • Documentation complete, PR opened in fidesdocs
  • Documentation issue created in fidesdocs
  • If there are any new client scopes created as part of the pull request, remember to update public-facing documentation that references our scope registry
  • No documentation updates required

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ready	Preview, Comment	Mar 2, 2026 7:27pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
fides-privacy-center	Ignored		Mar 2, 2026 7:27pm

[greptile-apps]

Greptile Summary

This PR establishes the foundational data model and validation logic for domain validation in SaaS connector parameters. The implementation adds an allowed_domains field to ConnectorParam that restricts which domain patterns a connector param can resolve to, along with utilities for wildcard-to-regex matching and a model validator ensuring host placeholders reference domain-restricted params.

Key Changes:

• Added allowed_domains field to ConnectorParam with wildcard pattern support (* matches any sequence)
• Implemented wildcard_to_regex utility with proper re.escape() to prevent regex injection
• Added validate_domain_against_allowed_list function using re.fullmatch() to prevent bypass attacks
• Created model validator ensuring all client_config.host placeholders reference params with allowed_domains when any param has domain restrictions
• Added disable_domain_validation security config flag (defaults to False for security)
• Updated Stripe connector as example implementation

Important Note: This is Part 1 of a 3-part series. The validation functions are defined but runtime enforcement during actual connector operations is not yet implemented. This PR focuses on the data model and config-time validation only.

Confidence Score: 4/5

• This PR is safe to merge with minor considerations about the incomplete implementation.
• The code quality is high with proper security practices (re.escape, re.fullmatch), comprehensive test coverage (174 new test lines), and clean architecture. Score is 4 instead of 5 because: (1) this is Part 1 of 3 and runtime enforcement is not yet implemented, meaning the validation logic isn't actually called during connector operations yet, and (2) the model validator increases config complexity which could cause confusion during the transition period before all connectors are updated.
• No files require special attention - all changes are well-tested and follow security best practices.

Important Files Changed

Filename	Overview
src/fides/api/util/domain_util.py	New utility module for wildcard-to-regex conversion. Clean implementation with proper escaping to prevent regex injection.
src/fides/api/util/saas_util.py	Added domain validation functions with proper security checks. Uses fullmatch to prevent bypass attacks. However, runtime enforcement is not yet implemented in this foundational PR.
src/fides/api/schemas/saas/saas_config.py	Added allowed_domains field to ConnectorParam and model validator ensuring host placeholders reference domain-restricted params. Strong validation logic but increases config complexity.
tests/ops/models/test_saas_config.py	Comprehensive test coverage for "Rule B" validator with 11 test cases covering edge cases like suffix attacks, missing params, and nested endpoint configs.

_{Last reviewed commit: 5a61a2d}

[greptile-apps]

_{7 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[daveqnet]

All good from my perspective, thanks @Linker44