Skip to main content
Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages.
Migrate your existing SAML Federation Connection from a legacy Auth0 custom domain to a new one, allowing your tenants to leverage Multiple Custom Domain (MCD) capabilities. External Identity Providers (IdPs) are often hardcoded to your old domain, which requires you to deploy a smart reverse proxy that intercepts the SAML response sent to your old domain and securely point it to a new custom domain. This ensures a seamless migration for federated users, allowing you to immediately use your new domain without waiting for mandatory configuration updates from your IdP.

​
Prerequisites

This process requires configuration via Terraform to set up the Auth0 components and deployment of a Cloudflare Worker for the proxy logic. Before getting started with your migration, review the requirements below:
  • A tenant on an Enterprise plan with MCD enabled.
  • Two verified custom domains configured in your Auth0 tenant:
    1. Old legacy domain (for the proxy)
    2. New target domain (for the application)
  • Terraform CLI and Node.js/npm installed.
  • Cloudflare account with access to the domain hosting your custom domains.

​
How it works

This migration strategy uses a smart reverse proxy to bridge the gap between your legacy custom domain and your new domain. This proxy is deployed on the old domain to intercept the SAML authentication response sent by your external Identity Provider (IdP). This is necessary because the IdP’s configuration is hardcoded to your old domain’s endpoint. The proxy modifies the SAML payload’s control fields (like Destination and Recipient) to accurately reflect the new custom domain. Finally, the proxy forwards this corrected payload to the new domain’s login endpoint. This enables a zero-downtime cutover to your new domain without requiring manual configuration changes from your IdP partners.

​
Setup and configuration

To setup and configure your migration:
  1. Clone the migration repository:
git clone <repository-url>
cd auth0-mcd-federation-migration
  1. Install dependencies:
npm install
  1. Create a terraform.auto.tfvars file in your tf firectory with the required credentials and domain information:
# Auth0 Service Provider (SP) variables
auth0_domain = "your-sp-tenant.auth0.com"
auth0_existing_custom_domain = "oldfed.example.com"
auth0_new_custom_domain = "id.example2.com"
auth0_tf_client_id = "your-sp-client-id"
auth0_tf_client_secret = "your-sp-client-secret"

# Auth0 Identity Provider (IDP) variables
auth0_idp_domain = "your-idp-tenant.auth0.com"
auth0_idp_tf_client_id = "your-idp-client-id"
auth0_idp_tf_client_secret = "your-idp-client-secret"

# Cloudflare variables
cloudflare_api_key = "your-cloudflare-api-key"
cloudflare_email = "your-cloudflare-email"
cloudflare_zone_id = "your-cloudflare-zone-id"
  1. Initialize and apply Terraform:
cd tf
terraform init
terraform apply
This creates the necessary SAML application and connection, configures the DNS via Cloudflare, and prepares the environment variables for the worker.

​
Deploy the Cloudflare worker

This proxy handles the SAML response interception and redirection logic. To deploy:
  1. Deploy the Cloudflare proxy:
cd ..
npx wrangler deploy
  1. The worker automatically receives the required environment variables (like AUTH0_EDGE_LOCATION and NEW_SP_DOMAIN) from the Terraform output.

​
Temporarily update SAML connection parameters

Your old domain receives the SAML response before being reposted to the new domain. Therefore, the SAML Connection’s expected validation parameters must temporarily point to the old domain’s callback URL to avoid mismatch errors.
  1. Obtain a Management API access token for your service provider tenant, with read:connections and update:connections scopes: 
    cd bin/
export access_token='<your-sp-management-api-token>'
  2. Update destination URL: 
    ./sp-set-destination-url.sh -i <saml-connection-id> -d [https://oldfed.example.com/login/callback](https://oldfed.example.com/login/callback)
  3. Update recipient URL: 
    ./sp-set-recipient-url.sh -i <saml-connection-id> -r [https://oldfed.example.com/login/callback](https://oldfed.example.com/login/callback)