Consolidate custom_domain and tre_url settings into single tre_url setting

CHANGELOG.md

@@ -1,7 +1,8 @@
 <!-- markdownlint-disable MD041 -->
 ## 0.25.0 (Unreleased)
 
-* _No changes yet_
+**BREAKING CHANGES & MIGRATIONS**:
+* Consolidated `custom_domain` and `tre_url` settings into single `tre_url` setting. The `custom_domain` configuration option has been removed. Users should update their `config.yaml` to use `tre_url` with full URLs instead (e.g., `tre_url: https://mytre.example.com`). The `CUSTOM_DOMAIN` environment variable is now automatically derived from `TRE_URL` for backward compatibility ([#4248](https://github.com/microsoft/AzureTRE/issues/4248))
 
 ## 0.24.0 (July 16, 2025)
 

config.sample.yaml

@@ -10,15 +10,18 @@ management:
   acr_name: __CHANGE_ME__
   # Set this to true if you want to disable public access to mgmt acr
   disable_acr_public_access: true
-  # ID of external Key Vault to store CMKs in (only required if enable_cmk_encryption is true)
+  # ID of external Key Vault to store CMKs in
+  # (only required if enable_cmk_encryption is true)
   # external_key_store_id: __CHANGE_ME__
-  # Name of Key Vault for encryption, required if enable_cmk_encryption is true and external_key_store_id is not set
+  # Name of Key Vault for encryption, required if enable_cmk_encryption is true
+  # and external_key_store_id is not set
   # encryption_kv_name: __CHANGE_ME__
   # Azure Resource Manager credentials used for CI/CD pipelines
   arm_subscription_id: __CHANGE_ME__
 
   # If you want to override the currently signed in credentials
-  # You would do this if running commands like `make terraform-install DIR=./templates/workspaces/base`
+  # You would do this if running commands like
+  # `make terraform-install DIR=./templates/workspaces/base`
   # arm_tenant_id: __CHANGE_ME__
   # arm_client_id: __CHANGE_ME__
   # arm_client_secret: __CHANGE_ME__
@@ -39,11 +42,13 @@ tre:
   enable_swagger: true
   enable_airlock_malware_scanning: true
 
-  # Set to true if want to ensure users have an email address before airlock request is created
+  # Set to true if want to ensure users have an email address before airlock
+  # request is created
   # Used if rely on email notifications for governance purposes
   # enable_airlock_email_check: true
 
-  # TODO: move to RP default with https://github.com/microsoft/AzureTRE/issues/2948
+  # TODO: move to RP default with
+  # https://github.com/microsoft/AzureTRE/issues/2948
   workspace_app_service_plan_sku: P1v2
   # The TRE Web UI is deployed by default.
   # Uncomment the following to disable deployment of the Web UI.
@@ -56,43 +61,56 @@ tre:
   # Set to Basic if wish to connect to VMs in workspaces.
   bastion_sku: Basic
 
-  # Set to true if TreAdmins should be able to assign and de-assign users to workspaces via the UI
+  # Set to true if TreAdmins should be able to assign and de-assign users to
+  # workspaces via the UI
   user_management_enabled: false
 
-  # Uncomment to enable DNS Security policy on the system, and add any known DNS names that you need to allow
-  # DNS queries on, in addition to those in the core list in core/terraform/allowed-dns.json
+  # Uncomment to enable DNS Security policy on the system, and add any known
+  # DNS names that you need to allow
+  # DNS queries on, in addition to those in the core list in
+  # core/terraform/allowed-dns.json
   # Note, these need to be fully qualified, i.e. they end in a dot(.)
   # enable_dns_policy: true
   # allowed_dns:
   #   - mydomain.com.
 
-  # Uncomment to deploy to a custom domain
-  # custom_domain: __CHANGE_ME__
+  # Uncomment to deploy to a custom domain. If set, this should be the full
+  # TRE URL (e.g., https://mytre.example.com). If not set, the TRE URL will be
+  # constructed automatically based on tre_id and location.
+  # tre_url: __CHANGE_ME__
 
-  # Uncomment to enable vnet exception for the subnet to access private resources like TRE key vault and management storage account.
+  # Uncomment to enable vnet exception for the subnet to access private
+  # resources like TRE key vault and management storage account.
   # private_agent_subnet_id: __CHANGE_ME__
 authentication:
   aad_tenant_id: __CHANGE_ME__
   # Setting AUTO_WORKSPACE_APP_REGISTRATION to false will:
   # create an identity with `Application.ReadWrite.OwnedBy`.
   # Setting AUTO_WORKSPACE_APP_REGISTRATION to true will:
-  # create an identity with `Application.ReadWrite.All` and `Directory.Read.All`.
-  # When this is true, create Workspaces will also create an AAD Application automatically.
+  # create an identity with `Application.ReadWrite.All` and
+  # `Directory.Read.All`.
+  # When this is true, create Workspaces will also create an AAD Application
+  # automatically.
   # When this is false, the AAD Application will need creating manually.
   auto_workspace_app_registration: true
-  # Setting AUTO_WORKSPACE_GROUP_CREATION to true will create an identity with `Group.ReadWrite.All`
+  # Setting AUTO_WORKSPACE_GROUP_CREATION to true will create an identity with
+  # `Group.ReadWrite.All`
   auto_workspace_group_creation: false
-  # Setting this to true will remove the need for users to manually grant consent when creating new workspaces.
-  # The identity will be granted Application.ReadWrite.All and DelegatedPermissionGrant.ReadWrite.All permissions.
+  # Setting this to true will remove the need for users to manually grant
+  # consent when creating new workspaces.
+  # The identity will be granted Application.ReadWrite.All and
+  # DelegatedPermissionGrant.ReadWrite.All permissions.
   auto_grant_workspace_consent: false
 
 resource_processor:
   # The number of processes to start in the resource processor VMSS image
   resource_processor_number_processes_per_instance: 5
 
-# This setting provides a way to pass environment values to the resource processor
+# This setting provides a way to pass environment values to the resource
+# processor
 # to use as a source of bundle parameter values
-# For example, to specify your image_gallery_id for use in VM user resources with custom VM images:
+# For example, to specify your image_gallery_id for use in VM user resources
+# with custom VM images:
 # yamllint disable-line rule:line-length
 #  rp_bundle_values: '{"custom_key_1":"custom_value_1","image_gallery_id":"/subscriptions/<subscription-id>/resourceGroups/<your-rg>/providers/Microsoft.Compute/galleries/<your-gallery-name>"}'
 
@@ -105,21 +123,19 @@ ui_config:
 developer_settings:
 # Locks will not be added to stateful resources so they can be easily removed
 # stateful_resources_locked: false
-# TRE Core Key Vault purge protection will be disabled so it can be reused upon deletion
+# TRE Core Key Vault purge protection will be disabled so it can be reused
+# upon deletion
 # kv_purge_protection_enabled: false
 
 # This setting will enable your local machine to be able to
 # communicate with Service Bus and Cosmos. It will also allow deploying
 # the base workspace.
 #  enable_local_debugging: true
 
-# This setting enables customer-managed key encryption for all supported resources
+# This setting enables customer-managed key encryption for all supported
+# resources
 #  enable_cmk_encryption: true
 
 # Used by the API and Resource processor application to change log level
 # Can be "ERROR", "WARNING", "INFO", "DEBUG"
 #  logging_level: "INFO"
-
-# If you want to use TRE_URL to point to your local TRE API instance or be configured to another cloud provider
-# uncomment and set this variable
-#  tre_url: __CHANGE_ME__

config_schema.json

@@ -109,8 +109,8 @@
           "description": "SKU of the Azure Bastion.",
           "type": "string"
         },
-        "custom_domain": {
-          "description": "Custom domain name.",
+        "tre_url": {
+          "description": "Custom TRE URL (full URL including https://). If not specified, will be constructed automatically.",
           "type": "string"
         },
         "enable_cmk_encryption": {

core/terraform/scripts/letsencrypt.sh

@@ -69,6 +69,7 @@ ledir=$(pwd)/letsencrypt
 mkdir -p "${ledir}/logs"
 
 CERT_FQDN=$FQDN
+# CUSTOM_DOMAIN is automatically extracted from TRE_URL by load_and_validate_env.sh
 if [[ -n "$CUSTOM_DOMAIN" ]]; then
   CERT_FQDN=$CUSTOM_DOMAIN
 fi

core/version.txt

@@ -1 +1 @@
-__version__ = "0.16.3"
+__version__ = "0.17.0"

devops/scripts/aad/create_api_application.sh

@@ -5,6 +5,13 @@ set -euo pipefail
 
 # AZURE_CORE_OUTPUT=jsonc # force CLI output to JSON for the script (user can still change default for interactive usage in the dev container)
 
+# Get the directory that this script is in
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# Source the helper function for extracting domain from URL
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/../extract_domain_from_url.sh"
+
 function show_usage()
 {
     cat << USAGE
@@ -18,14 +25,15 @@ Usage: $0 -n <app-name> [-r <reply-url>] [-a] [-s] [--automation-account]
 Options:
     -n,--name                   Required. The prefix for the app (registration) names e.g., "TRE", or "Workspace One".
     -u,--tre-url                TRE URL, used to construct auth redirection URLs for the UI and Swagger app.
+                                If the URL contains a custom domain, it will be used automatically.
     -a,--admin-consent          Optional, but recommended. Grants admin consent for the app registrations, when this flag is set.
                                 Requires directory admin privileges to the Azure AD in question.
     -t,--automation-clientid    Optional, when --workspace is specified the client ID of the automation account can be added to the TRE workspace.
     -r,--reset-password         Optional, switch to automatically reset the password. Default 0
-    -d,--custom-domain          Optional, custom domain, used to construct auth redirection URLs (in addition to --tre-url)
 
 Examples:
-    1. $0 -n TRE -r https://mytre.region.cloudapp.azure.com -a
+    1. $0 -n TRE -u https://mytre.region.cloudapp.azure.com -a
+    2. $0 -n TRE -u https://mytre.example.com -a  (with custom domain)
 
     Using an Automation account
     3. $0 --name 'TRE' --tre-url https://mytre.region.cloudapp.azure.com --admin-consent --automation-account
@@ -59,7 +67,6 @@ declare automationAppId=""
 declare automationAppObjectId=""
 declare msGraphUri=""
 declare spPassword=""
-declare customDomain=""
 
 # Initialize parameters specified from command line
 while [[ $# -gt 0 ]]; do
@@ -84,10 +91,6 @@ while [[ $# -gt 0 ]]; do
             resetPassword=$2
             shift 2
         ;;
-        -d|--custom-domain)
-            customDomain=$2
-            shift 2
-        ;;
         *)
             echo "Invalid option: $1."
             show_usage
@@ -249,11 +252,14 @@ redirectUris="\"http://localhost:8000/api/docs/oauth2-redirect\", \"http://local
 if [[ -n ${treUrl} ]]; then
     echo "Adding reply/redirect URL \"${treUrl}\" to \"${appName}\""
     redirectUris="${redirectUris}, \"${treUrl}\", \"${treUrl}/api/docs/oauth2-redirect\""
-fi
-if [[ -n ${customDomain} ]]; then
-    customDomainUrl="https://${customDomain}"
-    echo "Adding reply/redirect URL \"${customDomainUrl}\" to \"${appName}\""
-    redirectUris="${redirectUris}, \"${customDomainUrl}\", \"${customDomainUrl}/api/docs/oauth2-redirect\""
+
+    # Check if this is a custom domain (not the default cloudapp.azure.com pattern)
+    # If so, we don't need to add it again as it's already the main URL
+    treUrlDomain=$(extract_domain_from_url "${treUrl}")
+    if [[ "${treUrlDomain}" != *".cloudapp.azure.com" && "${treUrlDomain}" != *".cloudapp.usgovcloudapi.net" ]]; then
+        echo "Detected custom domain in TRE URL: ${treUrlDomain}"
+        # The custom domain URL is already included as the main treUrl, no need to add separately
+    fi
 fi
 
 uxAppDefinition=$(jq -c . << JSON

devops/scripts/create_aad_assets.sh

@@ -71,8 +71,7 @@ APPLICATION_PERMISSION=$(IFS=,; echo "${APPLICATION_PERMISSIONS[*]}")
   --name "${TRE_ID}" \
   --tre-url "${TRE_URL}" \
   --admin-consent --automation-clientid "${TEST_ACCOUNT_CLIENT_ID}" \
-  --reset-password $RESET_PASSWORDS \
-  --custom-domain "${CUSTOM_DOMAIN}"
+  --reset-password $RESET_PASSWORDS
 
 if [ "${AUTO_WORKSPACE_APP_REGISTRATION:=false}" == false ]; then
   # Load the new values back in

devops/scripts/extract_domain_from_url.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# This script is designed to be `source`d to create reusable helper functions
+
+function extract_domain_from_url()
+{
+  url=$1
+
+  # Remove protocol (http:// or https://)
+  domain=$(echo "$url" | sed -E 's|^https?://||')
+
+  # Remove path and query parameters (everything after the first /)
+  domain=${domain%%/*}
+
+  # Remove port if present (everything after the first :)
+  domain=${domain%%:*}
+
+  echo "$domain"
+}

devops/scripts/load_and_validate_env.sh

@@ -11,6 +11,8 @@ set -o nounset
 # shellcheck disable=SC1091
 source "${DIR}"/construct_tre_url.sh
 # shellcheck disable=SC1091
+source "${DIR}"/extract_domain_from_url.sh
+# shellcheck disable=SC1091
 source "${DIR}"/convert_azure_env_to_arm_env.sh
 
 if [ ! -f "config.yaml" ]; then
@@ -88,8 +90,21 @@ else
     export ARM_ENVIRONMENT
     export TF_VAR_arm_environment="${ARM_ENVIRONMENT}"
 
-    TRE_URL=$(construct_tre_url "${TRE_ID}" "${LOCATION}" "${AZURE_ENVIRONMENT}")
+    # Set TRE_URL - either from config or constructed automatically
+    if [[ -n "${TRE_URL:-}" ]]; then
+        # TRE_URL was provided in config, use it as-is
+        echo "Using TRE_URL from config: ${TRE_URL}"
+    else
+        # Construct TRE_URL automatically
+        TRE_URL=$(construct_tre_url "${TRE_ID}" "${LOCATION}" "${AZURE_ENVIRONMENT}")
+        echo "Constructed TRE_URL: ${TRE_URL}"
+    fi
     export TRE_URL
+
+    # Set CUSTOM_DOMAIN by extracting domain from TRE_URL 
+    # This maintains backward compatibility for scripts that expect CUSTOM_DOMAIN
+    CUSTOM_DOMAIN=$(extract_domain_from_url "${TRE_URL}")
+    export CUSTOM_DOMAIN
 fi
 
 # if local debugging is configured, then set vars required by ~/.porter/config.yaml

docs/tre-admins/custom-domain.md

@@ -4,11 +4,18 @@ In order to use a custom domain name with the Azure TRE:
 
 1. Register a domain name, and create a DNS entry for the domain name pointing to the FQDN of the Azure App Gateway, e.g. `mytre-domain-name.org.  CNAME  mytre.region.cloudapp.azure.com.`
 
-2. Set the domain name in the `CUSTOM_DOMAIN` variable in `config.yaml` or create a GitHub Actions secret, depending on your deployment method.
+2. Set the full custom URL in the `tre_url` setting in `config.yaml`. For example:
+
+```yaml
+tre:
+  tre_url: https://mytre-domain-name.org
+```
+
+**Note:** The `CUSTOM_DOMAIN` environment variable has been deprecated. Use `tre_url` instead, which should contain the full URL including the protocol.
 
 3. Update the *TRE UX* App Registration redirect URIs:
 
-   a. If you haven't deployed your TRE yet, this is done automatically for you using the `make auth` command.  Refer to the setup instructions to deploy your TRE.
+   a. If you haven't deployed your TRE yet, this is done automatically for you using the `make auth` command. The script will automatically detect the custom domain from your `tre_url` setting and configure the redirect URIs accordingly.
 
    b. If your TRE has already been deployed, manually add the following redirect URIs in Entra ID > App Registrations > *TRE_ID UX* > Authentication > Single-page application Redirect URIs:
 

docs/tre-admins/environment-variables.md

@@ -24,7 +24,7 @@
 | <div style="width: 330px">Environment variable name</div> | Description |
 | ------------------------- | ----------- |
 | `TRE_ID` | A globally unique identifier. `TRE_ID` can be found in the resource names of the Azure TRE instance; for example, a `TRE_ID` of `mytre-dev` will result in a resource group name for Azure TRE instance of `rg-mytre-dev`. This must be less than 12 characters. Allowed characters: lowercase alphanumerics|
-| `TRE_URL`| This will be generated for you by populating your `TRE_ID`. This is used so that you can automatically register bundles |
+| `TRE_URL`| This will be generated for you based on your `TRE_ID` and `LOCATION`, or can be set to a custom URL (e.g., `https://mytre.example.com`) for custom domains. Used for automatic registration of bundles and authentication redirects. |
 | `CORE_ADDRESS_SPACE` | The address space for the Azure TRE core virtual network. `/22` or larger. |
 | `TRE_ADDRESS_SPACE` | The address space for the whole TRE environment virtual network where workspaces networks will be created (can include the core network as well). E.g. `10.0.0.0/12`|
 | `ENABLE_SWAGGER` | Determines whether the Swagger interface for the API will be available. |
@@ -45,7 +45,6 @@
 | `APP_GATEWAY_SKU` | Optional. The SKU of the Application Gateway. Default value is `Standard_v2`. Allowed values [`Standard_v2`, `WAF_v2`] |
 | `DEPLOY_BASTION` | Optional. If set to `true`, an Azure Bastion instance will be deployed. Default value is `true`. |
 | `BASTION_SKU` | Optional. The SKU of the Azure Bastion instance. Default value is `Basic`. Allowed values [`Developer`, `Standard`, `Basic`, `Premium`]. See [Azure Bastion SKU feature comparison](https://learn.microsoft.com/en-us/azure/bastion/bastion-overview#sku). |
-| `CUSTOM_DOMAIN` | Optional. Custom domain name to access the Azure TRE portal. See [Custom domain name](custom-domain.md). |
 | `ENABLE_CMK_ENCRYPTION` | Optional. Default is `false`, if set to `true` customer-managed key encryption will be enabled for all supported resources. |
 | `AUTO_WORKSPACE_APP_REGISTRATION`| Set to `false` by default. Setting this to `true` grants the `Application.ReadWrite.All` and `Directory.Read.All` permission to the *Application Admin* identity. This identity is used to manage other Microsoft Entra ID applications that it owns, e.g. Workspaces. If you do not set this, the identity will have `Application.ReadWrite.OwnedBy` permission. [Further information on Application Admin can be found here](./identities/application_admin.md). |
 | `AUTO_WORKSPACE_GROUP_CREATION`| Set to `false` by default. Setting this to `true` grants the `Group.ReadWrite.All` permission to the *Application Admin* identity. This identity can then create security groups aligned to each applciation role. Microsoft Entra ID licencing implications need to be considered as Group assignment is a premium feature. [You can read mode about Group Assignment here](https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles#roles-using-azure-ad-app-roles). |

docs/tre-admins/setup-instructions/cicd-pre-deployment-steps.md

@@ -86,7 +86,7 @@ Configure the following **variables** in your github environment:
 | `ENABLE_SWAGGER` | Optional. Determines whether the Swagger interface for the API will be available. Default value is `false`. |
 | `FIREWALL_SKU` | Optional. The SKU of the Azure Firewall instance. Default value is `Standard`. Allowed values [`Basic`, `Standard`, `Premium`]. See [Azure Firewall SKU feature comparison](https://learn.microsoft.com/en-us/azure/firewall/choose-firewall-sku). |
 | `APP_GATEWAY_SKU` | Optional. The SKU of the Application Gateway. Default value is `Standard_v2`. Allowed values [`Standard_v2`, `WAF_v2`] |
-| `CUSTOM_DOMAIN` | Optional. Custom domain name to access the Azure TRE portal. See [Custom domain name](../custom-domain.md). |
+| `TRE_URL` | Optional. Specify a custom URL for the TRE instance (e.g., `https://mytre.example.com`). If not set, the TRE URL will be constructed automatically based on `TRE_ID` and location. Can be configured in `config.yaml` as `tre_url`. |
 | `ENABLE_CMK_ENCRYPTION` | Optional. Default is `false`, if set to `true` customer-managed key encryption will be enabled for all supported resources. |
 
 ### Configure Authentication Secrets

docs/tre-admins/setup-instructions/workflows.md

@@ -127,7 +127,7 @@ Configure additional secrets used in the deployment workflow:
 | `MGMT_RESOURCE_GROUP_NAME` | The name of the shared resource group for all Azure TRE core resources. |
 | `MGMT_STORAGE_ACCOUNT_NAME` | The name of the storage account to hold the Terraform state and other deployment artifacts. E.g. `mystorageaccount`. |
 | `ACR_NAME` | A globally unique name for the Azure Container Registry (ACR) that will be created to store deployment images. |
-| `CUSTOM_DOMAIN` | Optional. Custom domain name to access the Azure TRE portal. See [Custom domain name](../custom-domain.md). |
+| `TRE_URL` | Optional. Specify a custom URL for the TRE instance (e.g., `https://mytre.example.com`). If not set, the TRE URL will be constructed automatically based on `TRE_ID` and location. Can be configured in `config.yaml` as `tre_url`. |
 
 
 ### Configure repository/environment variables