From 5778fc93221fcb89ab64268be98703ba9d86c705 Mon Sep 17 00:00:00 2001 From: Jonny Rylands Date: Tue, 9 Jul 2024 16:26:54 +0100 Subject: [PATCH] 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 | 1 + CHANGELOG.md | 1 + config.sample.yaml | 9 ++++-- config_schema.json | 9 +++--- core/terraform/scripts/letsencrypt.sh | 11 ++++++-- core/version.txt | 2 +- devops/scripts/aad/create_api_application.sh | 11 ++++++++ devops/scripts/create_aad_assets.sh | 3 +- docs/tre-admins/custom-domain.md | 28 +++++++++++++++++++ docs/tre-admins/environment-variables.md | 2 +- .../cicd-pre-deployment-steps.md | 2 +- .../setup-instructions/workflows.md | 1 + mkdocs.yml | 1 + 13 files changed, 67 insertions(+), 14 deletions(-) create mode 100644 docs/tre-admins/custom-domain.md diff --git a/.github/workflows/lets_encrypt.yml b/.github/workflows/lets_encrypt.yml index 6a0712ab15..875ce050db 100644 --- a/.github/workflows/lets_encrypt.yml +++ b/.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/ \ diff --git a/CHANGELOG.md b/CHANGELOG.md index b9fc942a5e..caba3ef5d3 100644 --- a/CHANGELOG.md +++ b/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: diff --git a/config.sample.yaml b/config.sample.yaml index 21e757fe89..77ce40d68c 100644 --- a/config.sample.yaml +++ b/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__ diff --git a/config_schema.json b/config_schema.json index d16ff8f775..f388319883 100644 --- a/config_schema.json +++ b/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" } } }, diff --git a/core/terraform/scripts/letsencrypt.sh b/core/terraform/scripts/letsencrypt.sh index 937586ba53..cb1e68f4a1 100755 --- a/core/terraform/scripts/letsencrypt.sh +++ b/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" \ diff --git a/core/version.txt b/core/version.txt index 1f4c4d43b2..17c1a6260b 100644 --- a/core/version.txt +++ b/core/version.txt @@ -1 +1 @@ -__version__ = "0.10.1" +__version__ = "0.10.2" diff --git a/devops/scripts/aad/create_api_application.sh b/devops/scripts/aad/create_api_application.sh index bfc18ebb27..024b086bc7 100755 --- a/devops/scripts/aad/create_api_application.sh +++ b/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 { diff --git a/devops/scripts/create_aad_assets.sh b/devops/scripts/create_aad_assets.sh index d034e1be40..06584a9fb5 100755 --- a/devops/scripts/create_aad_assets.sh +++ b/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 diff --git a/docs/tre-admins/custom-domain.md b/docs/tre-admins/custom-domain.md new file mode 100644 index 0000000000..8fee96effc --- /dev/null +++ b/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. diff --git a/docs/tre-admins/environment-variables.md b/docs/tre-admins/environment-variables.md index 25f3e73751..739d438e17 100644 --- a/docs/tre-admins/environment-variables.md +++ b/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` diff --git a/docs/tre-admins/setup-instructions/cicd-pre-deployment-steps.md b/docs/tre-admins/setup-instructions/cicd-pre-deployment-steps.md index af61f035f7..b9ddc041c0 100644 --- a/docs/tre-admins/setup-instructions/cicd-pre-deployment-steps.md +++ b/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 diff --git a/docs/tre-admins/setup-instructions/workflows.md b/docs/tre-admins/setup-instructions/workflows.md index a06ccf46c6..37dfb97dc1 100644 --- a/docs/tre-admins/setup-instructions/workflows.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 34047b9fb4..e2b9e8d73f 100644 --- a/mkdocs.yml +++ b/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