Support custom domain on SSL certificate and App Registration redirect (

#4014)

* Support custom domain on SSL certificate and App Registration redirect

* Update CHANGELOG.md

* Update core version number

* Custom domain documentation

* Fix docs formatting

* Update CHANGELOG.md

* Print certificate FQDN to console in letsencrypt.sh

.github/workflows/lets_encrypt.yml

@@ -51,6 +51,7 @@ jobs:
           TF_VAR_terraform_state_container_name: ${{ secrets.TERRAFORM_STATE_CONTAINER_NAME || 'tfstate' }}
           TF_VAR_mgmt_resource_group_name: ${{ secrets.MGMT_RESOURCE_GROUP_NAME }}
           TF_VAR_mgmt_storage_account_name: ${{ secrets.MGMT_STORAGE_ACCOUNT_NAME }}
+          CUSTOM_DOMAIN: ${{ secrets.CUSTOM_DOMAIN }}
         run: |
           sudo apt-get install -y python3 python3-venv libaugeas0 \
             && python3 -m venv /opt/certbot/ \

CHANGELOG.md

@@ -6,6 +6,7 @@
 FEATURES:
 
 ENHANCEMENTS:
+* Ability to host TRE on a custom domain ([#4014](https://github.com/microsoft/AzureTRE/pull/4014))
 
 BUG FIXES:
 

config.sample.yaml

@@ -42,11 +42,10 @@ tre:
   # The TRE Web UI is deployed by default.
   # Uncomment the following to disable deployment of the Web UI.
   # deploy_ui: false
-  # 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__
   firewall_sku: Standard
 
+  # Uncomment to deploy to a custom domain
+  # custom_domain: __CHANGE_ME__
 authentication:
   aad_tenant_id: __CHANGE_ME__
   # Setting AUTO_WORKSPACE_APP_REGISTRATION to false will:
@@ -83,3 +82,7 @@ developer_settings:
 # 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

@@ -85,14 +85,13 @@
           "description": "Determines whether the Swagger interface for the API will be available.",
           "type": "boolean"
         },
-        "tre_url": {
-          "description": "Url for the TRE environment.",
-          "type": "string",
-          "pattern": "^https?://"
-        },
         "firewall_sku": {
           "description": "SKU of the Azure Firewall.",
           "type": "string"
+        },
+        "custom_domain": {
+          "description": "Custom domain name.",
+          "type": "string"
         }
       }
     },

core/terraform/scripts/letsencrypt.sh

@@ -92,6 +92,13 @@ ledir=$(pwd)/letsencrypt
 
 mkdir -p "${ledir}/logs"
 
+CERT_FQDN=$FQDN
+if [[ -n "$CUSTOM_DOMAIN" ]]; then
+  CERT_FQDN=$CUSTOM_DOMAIN
+fi
+
+echo "Requesting certificate for $CERT_FQDN..."
+
 # Initiate the ACME challange
 /opt/certbot/bin/certbot certonly \
     --config-dir "${ledir}" \
@@ -101,13 +108,13 @@ mkdir -p "${ledir}/logs"
     --preferred-challenges=http \
     --manual-auth-hook "${script_dir}"/auth-hook.sh \
     --manual-cleanup-hook "${script_dir}"/cleanup-hook.sh \
-    --domain "$FQDN" \
+    --domain "$CERT_FQDN" \
     --non-interactive \
     --agree-tos \
     --register-unsafely-without-email
 
 # Convert the generated certificate to a .pfx
-CERT_DIR="${ledir}/live/$FQDN"
+CERT_DIR="${ledir}/live/$CERT_FQDN"
 CERT_PASSWORD=$(openssl rand -base64 30)
 openssl pkcs12 -export \
     -inkey "${CERT_DIR}/privkey.pem" \

core/version.txt

@@ -1 +1 @@
-__version__ = "0.10.1"
+__version__ = "0.10.2"

devops/scripts/aad/create_api_application.sh

@@ -22,6 +22,7 @@ Options:
                                 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
@@ -58,6 +59,7 @@ declare automationAppId=""
 declare automationAppObjectId=""
 declare msGraphUri=""
 declare spPassword=""
+declare customDomain=""
 
 # Initialize parameters specified from command line
 while [[ $# -gt 0 ]]; do
@@ -82,6 +84,10 @@ while [[ $# -gt 0 ]]; do
             resetPassword=$2
             shift 2
         ;;
+        -d|--custom-domain)
+            customDomain=$2
+            shift 2
+        ;;
         *)
             echo "Invalid option: $1."
             show_usage
@@ -244,6 +250,11 @@ 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\""
+fi
 
 uxAppDefinition=$(jq -c . << JSON
 {

devops/scripts/create_aad_assets.sh

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

docs/tre-admins/custom-domain.md

@@ -0,0 +1,28 @@
+# Custom domain name
+
+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.
+
+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.
+
+   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:
+
+```text
+  https://mytre-domain-name.org
+  https://mytre-domain-name.org/api/docs/oauth2-redirect
+```
+
+4. Generate an SSL certificate for the TRE's new domain name:
+
+```bash
+  make letsencrypt
+```
+
+## Limitations
+
+The method above allows a custom domain name to be used to access the Azure TRE's portal and Swagger UI.  It does not configure the custom domain name for Guacamole instances, or services available within the TRE network such as Gitea, or Sonatype Nexus.

docs/tre-admins/environment-variables.md

@@ -40,7 +40,7 @@
 | `WORKSPACE_APP_SERVICE_PLAN_SKU` | Optional. The SKU used for AppService plan used in E2E tests unless otherwise specified. Default value is `P1v2`. |
 | `RESOURCE_PROCESSOR_NUMBER_PROCESSES_PER_INSTANCE` | Optional. The number of processes to instantiate when the Resource Processor starts. Equates to the number of parallel deployment operations possible in your TRE. Defaults to `5`. |
 | `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). |
-
+| `CUSTOM_DOMAIN` | Optional. Custom domain name to access the Azure TRE portal. See [Custom domain name](custom-domain.md). |
 
 ## For authentication in `/config.yaml`
 

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

@@ -84,7 +84,7 @@ Configure the following **variables** in your github environment:
 | `RESOURCE_PROCESSOR_NUMBER_PROCESSES_PER_INSTANCE` | Optional. The number of processes to instantiate when the Resource Processor starts. Equates to the number of parallel deployment operations possible in your TRE. Defaults to `5`. |
 | `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). |
-
+| `CUSTOM_DOMAIN` | Optional. Custom domain name to access the Azure TRE portal. See [Custom domain name](../custom-domain.md). |
 
 ### Configure Authentication Secrets
 

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

@@ -127,6 +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). |
 
 
 ### Configure repository/environment variables

mkdocs.yml

@@ -132,6 +132,7 @@ nav:
           - Upgrading Resources Version: tre-admins/upgrading-resources.md
           - Configuring Airlock Reviews: tre-admins/configure-airlock-review.md
           - Supported Clouds: tre-admins/supported-clouds.md
+          - Custom Domain Name: tre-admins/custom-domain.md
 
       - Development: # Docs related to the developing code for the AzureTRE
           - Local Development: using-tre/local-development/local-development.md