microsoft · Copilot · Jul 17, 2025 · Jul 17, 2025 · Jul 17, 2025 · Jul 17, 2025
@@ -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)
 

@@ -10,15 +10,15 @@
  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)
  # 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
  # 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`
  # arm_tenant_id: __CHANGE_ME__
  # arm_client_id: __CHANGE_ME__
  # arm_client_secret: __CHANGE_ME__
@@ -39,11 +39,11 @@
  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
  # 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
  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,18 +56,20 @@
  # 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
  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
  # 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.
   # private_agent_subnet_id: __CHANGE_ME__
@@ -119,7 +121,3 @@
 # 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__
@@ -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": {

@@ -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

@@ -1 +1 @@
-__version__ = "0.16.3"
+__version__ = "0.17.0"
@@ -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
@@ -84,10 +92,6 @@ while [[ $# -gt 0 ]]; do
             resetPassword=$2
             shift 2
         ;;
-        -d|--custom-domain)
-            customDomain=$2
-            shift 2
-        ;;
         *)
             echo "Invalid option: $1."
             show_usage
@@ -249,11 +253,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

@@ -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

@@ -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=$(echo "$domain" | sed 's|/.*||')
+
+  # Remove port if present (everything after the first :)
+  domain=$(echo "$domain" | sed 's|:.*||')
+
+  echo "$domain"
+}
@@ -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

@@ -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:
 

@@ -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). |

@@ -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

@@ -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