Migrating an SHM

These instructions will walk you through migrating an existing Safe Haven Management (SHM) environment to a newer Data Safe Haven release and migrating the users to it.

Note

This document assumes that you have already deployed a Safe Haven Management (SHM) environment and one or more Secure Research Environments (SREs) that are linked to it.

Danger

This is a complex operation and may not always work. You may lose data or user accounts in the migration process.

Explanation of symbols used in this guide

Powershell command

• This indicates a Powershell command which you will need to run locally on your machine

• Ensure you have checked out (or downloaded) the appropriate tag of the Safe Haven repository from alan-turing-institute/data-safe-haven.

• Open a Powershell terminal and navigate to the indicated directory of your locally checked-out version of the Safe Haven repository

• Ensure that you are logged into Azure by running the Connect-AzAccount command

  Tip

  If your account is a guest in additional Azure tenants, you may need to add the -Tenant <Tenant ID> flag, where <Tenant ID> is the ID of the Azure tenant you want to deploy into.

• This command will give you a URL and a short alphanumeric code.

• Go to URL in a web browser, enter the code and log in to your account on Azure.

  Tip

  If you have several Azure accounts, make sure you use one that has permissions to make changes to the subscription you are using

Remote command

• This indicates a command which you will need to run remotely on an Azure virtual machine (VM) using Microsoft Remote Desktop

• Open Microsoft Remote Desktop and click Add Desktop / Add PC

• Enter the private IP address of the VM that you need to connect to in the PC name field (this can be found by looking in the Azure portal)

• Enter the name of the VM (for example DC1-SHM-PROJECT) in the Friendly name field

• Click Add

• Ensure you are connected to the SHM VPN that you have set up

• Double click on the desktop that appears under Saved Desktops or PCs.

• Use the username and password specified by the appropriate section of the guide

Tip

If you see a warning dialog that the certificate cannot be verified as root, accept this and continue.

Azure Portal operation

• This indicates an operation which needs to be carried out in the Azure Portal using a web browser on your local machine.

• You will need to login to the portal using an account with privileges to make the necessary changes to the resources you are altering

Azure Active Directory operation

• This indicates an operation which needs to be carried out in the Azure Portal using a web browser on your local machine.

• You will need to login to the portal using an account with administrative privileges on the Azure Active Directory that you are altering.

• Note that this might be different from the account which is able to create/alter resources in the Azure subscription where you are building the Safe Haven.

OS-dependent steps

The following icons indicate steps that depend on the OS you are using to deploy the SHM

• MacOS

• Windows

• Linux

1. 🌱 Prerequisites

• All of the Safe Haven Management (SHM) environment prerequisites

The following variables will be used during deploying

• <old SHM ID>: the management environment ID for the previously deployed SHM

• <SHM ID>: the management environment ID for the new SHM you want to deploy

• <AAD tenant ID>: the Tenant ID for the Azure Active Directory that your previously deployed SHM is connected to

2. 🔓 Disconnect the old domain controller from the Azure Active Directory

• Log into the SHM primary domain controller for the old SHM (DC1-SHM-<old SHM ID>) VM using the private IP address, <admin login> and <admin password> from the portal

• Open Powershell as an administrator

  • Navigate to C:\Installation

  • Run .\Disconnect_AD.ps1

  • You will need to provide login credentials (including MFA if set up) for <admin username>@<SHM domain>

Warning

Do not attempt to add users to the old SHM after this point as they will not be synchronised to the Azure Active Directory!

Attention

Full disconnection of the Azure Active Directory can take up to 72 hours but will typically take around one day.

3. 📋 Safe Haven Management configuration

• Create a copy of the configuration file for your previous SHM

• You may want to change some of the following attributes:

{
  "azure": {
    "subscriptionName": "Azure subscription to deploy the SHM into. You might want to use a different subscription than for your previous SHM."
  },
  "shmId": "The <SHM ID> for the new SHM. If you try to deploy two SHMs with the same ID into the same subscription some resources will not deploy correctly."
}

4. 🚪 Configure DNS for the custom domain

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

5. 📁 Ensure the Azure Active Directory domain is registered

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

Note

You will need to use an AAD global admin when the AzureAD module asks you to sign-in.

6. 🔑 Deploy Key Vault for SHM secrets and create emergency admin account

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

Note

You will need to use an AAD global admin when the AzureAD module asks you to sign-in.

7. 🚉 Deploy network and VPN gateway

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

8. 🏡 Deploy the domain controllers

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

Important

Do not run any of the domain controller configuration steps yet

9. ⚡ Configure the new domain controllers

🔏 Suspend MFA for all users

• From the Azure portal, navigate to the AAD.

• Click Security in the left hand sidebar

• Click Conditional access in the left hand sidebar

• Click the Require MFA policy from the policy list

  • Toggle Enable policy to Off

  • Click the Save button

👥 Copy SHM users from old domain controller

at 📁 ./deployment/safe_haven_management_environment/setup

PS> ./Copy_SHM_Users.ps1 -oldShmId <old SHM ID> -newShmId <SHM ID>

• where <old SHM ID> is the management environment ID for the previously deployed SHM

• where <SHM ID> is the management environment ID for this SHM

⚓ Reset Azure AD source anchors

• Log into the SHM primary domain controller (DC1-SHM-<SHM ID>) VM that you have just deployed using the private IP address, <admin login> and <admin password> that you obtained from the portal

Run the following Powershell commands

# Get local users
$userOuPath = (Get-ADObject -Filter * | Where-Object { $_.Name -eq "Safe Haven Research Users" }).DistinguishedName
$users = Get-ADUser -Filter * -SearchBase "$userOuPath" -Properties *

# Connect to AzureAD
# Use the credentials for an AzureAD global admin (eg. `aad.admin.firstname.surname@<SHM domain>`)
Connect-MsolService

# Reset source anchor for AzureAD users
foreach ($user in $users) {
  $immutableId = [System.Convert]::ToBase64String($user.ObjectGUID.ToByteArray())
  Set-MsolUser -UserPrincipalName $($user.UserPrincipalName) -immutableID $immutableId
  Write-Output "Set source anchor for $($user.UserPrincipalName) to $immutableId"
}

Note

All research users in this SHM will have to go to https://aka.ms/sspr to reset their passwords although their MFA configuration will stay the same.

🚋 Install Azure Active Directory Connect

See the Safe Haven Management documentation for more details.

Error

Since you are trying to connect the new SHM to an Azure Active Directory that was already synchronised, you may find the AzureADConnect installation fails due to a Directory synchronisation failure.

If this happens then you will need to wait for the previous disconnection to complete, which may take up to 72 hours.

♻️ Update Azure Active Directory Connect rules

See the Safe Haven Management documentation for more details.

🚮 Unregister the old domain controller in Azure Active Directory

• From the Azure portal, navigate to the AAD you have created.

• Select Azure AD Connect from the left hand menu

• Under Health And Analytics click Azure AD Connect Health

• Select Sync services from the left hand menu

• Click on <Safe Haven identifier>.onmicrosoft.com

• Click on the Azure Active Directory Connect Server that corresponds to the old DC (marked as Unhealthy)

• Click Delete in the top bar, type the server name when prompted then click Delete

☑️ Validate Active Directory synchronisation

See the Safe Haven Management documentation for more details.

10. 🚓 Deploy and configure network policy server

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

11. 🔐 Require MFA for all users

See the Safe Haven Management documentation for more details.

12. 🚷 Block portal access for normal users

See the Safe Haven Management documentation for more details.

13. 📦 Deploy Python/R package repositories

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

14. 📈 Deploy logging

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.

15. 🚒 Deploy firewall

at 📁 ./deployment/safe_haven_management_environment/setup

See the Safe Haven Management documentation for more details.