Managing Data Safe Haven users#

Important

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

🔰 Create new users#

Users should be created on the main domain controller (DC1) in the SHM and synchronised to Azure Active Directory. A helper script for doing this is already uploaded to the domain controller - you will need to prepare a CSV file in the appropriate format for it.

📜 Generate user details CSV file#

🚗 Using data classification app#

  • Follow the instructions in the classification app documentation to create users

    • Users can be created in bulk by selecting Create User > Import user list and uploading a spreadsheet of user details

    • Users can also be created individually by selecting Create User > Create Single User

  • After creating users, export the UserCreate.csv file

    • To export all users, select Users > Export UserCreate.csv

    • To export only users for a particular project, select Projects > (Project Name) > Export UserCreate.csv

  • Upload the user details CSV file to a sensible location on the SHM domain controller

    Note

    We suggest using C:\Installation\YYYYDDMM-HHMM_user_details.csv but this is up to you

✋ Manually edit CSV#

On the SHM domain controller (DC1).

  • Make a new copy of the user details template file from C:\Installation\user_details_template.csv

    Tip

    We suggest naming this YYYYDDMM-HHMM_user_details.csv but this is up to you

  • Remove the example user and add the required details for each user

    • SamAccountName: Log in username without the @<SRE domain> part.

      Tip

      We recommend using firstname.lastname format.

      Warning

      Ensure that SamAccountName has a maximum of 20 characters from the 7-bit ASCII set (unaccented letters, numbers and some punctuation) or synchronisation will fail.

    • GivenName: User’s first / given name

      Warning

      Ensure that GivenName uses only characters from the 7-bit ASCII set (unaccented letters, numbers and some punctuation) or synchronisation will fail.

    • Surname: User’s last name / surname

      Warning

      Ensure that Surname uses only characters from the 7-bit ASCII set (unaccented letters, numbers and some punctuation) or synchronisation will fail.

    • Mobile: Phone number to use for initial password reset.

      Important

      • This must include country code in the format +<country-code> <local number> (e.g. +44 7123456789).

      • Include a space between the country code and local number parts but no other spaces.

      • Remove the leading 0 from local number if present.

      • This can be a landline or or mobile but must be accessible to the user when resetting their password and setting up MFA.

      • Users can add the authenticator app and/or additional phone numbers during MFA self-registration.

    • SecondaryEmail: An existing organisational email address for the user.

      Note

      This is not uploaded to their Data Safe Haven user account but is needed when sending account activation messages.

    • GroupName: [Optional] The name of the Active Directory security group(s) that the users should be added to (eg. SG SANDBOX Research Users ).

      Tip

      If the user needs to be added to multiple groups, separate them with a pipe-character ( | ).

🔄 Create and synchronise users#

Upload the user details CSV file to a sensible location on the SHM domain controller (recommended: C:\Installation). This can be done by copying and pasting the file from your deployment device to the SHM DC.

  • Log into the SHM primary domain controller (DC1-SHM-<SHM ID>) VM using the login credentials stored in Azure Key Vault

  • Open a Powershell command window with elevated privileges

  • Run C:\Installation\CreateUsers.ps1 <path_to_user_details_file>

  • This script will add the users and trigger synchronisation with Azure Active Directory

  • It will still take around 5 minutes for the changes to propagate

Error

If you get the message New-ADUser : The specified account already exists you should first check to see whether that user actually does already exist! Once you’re certain that you’re adding a new user, make sure that the following fields are unique across all users in the Active Directory.

  • SamAccountName

    • Specified explicitly in the CSV file.

    • If this is already in use, consider something like firstname.middle.initials.lastname

  • DistinguishedName

    • Formed of CN=<DisplayName>,<OUPath> by Active Directory on user creation.

    • If this is in use, consider changing DisplayName from <GivenName> <Surname> to <GivenName> <middle initials> <Surname> .

Danger

  • These domain administrator credentials have complete control over creating and deleting users as well as assigning them to groups

  • Do not use them except where specified and never write them down!

  • Be particularly careful never to use them to log in to any user-accessible VMs (such as the SRDs)

📲 Assign MFA licences#

✋ Manually add licence to each user#

  • Login into the Azure Portal and connect to the correct AAD

  • Open Azure Active Directory

  • Select Manage > Licenses > All Products

  • Click Azure Active Directory Premium P1

  • Click Assign

  • Click Users and groups

  • Select the users you have recently created and click Select

  • Click Assign to complete the process

🚗 Automatically assign licences to users#

To automatically assign licences to all local Active Directory users that do not currently have a licence in Azure Active Directory.

  • Ensure you have the same version of the Data Safe Haven repository as was used by your deployment team

  • Open a Powershell terminal and navigate to the deployment/administration directory within the Data Safe Haven repository

  • Run the ./SHM_Add_AAD_Licences.ps1 -tenantId <Tenant ID> script, where <Tenant ID> is the ID of the Azure tenant belonging to the SHM you want to add the licences to

🏃 User activation#

We recommend using email to send connection details to new users.

Note

This is not a security risk since:

  • we are not sending passwords in this email

  • the user needs access to their previously-provided phone number in order to set their account password and MFA

A sample email might look like the following

Dear <participant name>,

Welcome to <event name>! You’ve been given access to a Data Safe Haven managed by <organisation name>. Please find a PDF version of our user guide attached. You should start by following the instructions about setting up your account and enabling multi-factor authentication (MFA).

Your username is: <username@domain> Your Safe Haven is hosted at: <URL>

The Safe Haven is only accessible from certain networks and may also involve physical location restrictions.

–details about network and location/VPN restrictions here–

👷 Common user problems#

One of the most common user issues is that they are unable to log in to the environment. Here we go through the login procedure and discuss possible problems at each step

🌘 Expired webclient certificate#

If the certificate for the SRE domain has expired, users will not be able to login.

Login failure - expired certificate

Tip

Solution: Replace the SSL certificate with a new one

  • Ensure you have the same version of the Data Safe Haven repository as was used by your deployment team

  • Open a Powershell terminal and navigate to the deployment/secure_research_environment/setup directory within the Data Safe Haven repository

  • Ensure you are logged into the Azure within Powershell using the command: Connect-AzAccount

  • Run ./Update_SRE_RDS_Ssl_Certificate.ps1 -sreId <SRE ID>, where the SRE ID is the one specified in the config

🔴 Unable to log into remote desktop gateway#

If users give the wrong username or password they will not be able to progress past the login screen.

Login failure - wrong password

Tip

Solution: Check user credentials, password may need to be reset.

🚋 Unable to open any remote apps#

Users are stuck at the Opening remote port message and never receive the MFA prompt.

Login failure - no MFA prompt

Tip

Solution: Check MFA setup

  • Ensure that the user has been assigned a license in Azure Active Directory

  • Check that the user has set up MFA (at https://aka.ms/mfasetup ) and is using the phone-call or app authentication method

⁉️ xrdp login failure on the SRD#

If users can get to the login screen:

SRD login screen

but then see this error message:

SRD login failure

there are a couple of possible causes.

Error

Problem: the username or password was incorrectly entered

Solution: check username and password

  • Confirm that the username and password have been correctly typed

  • Confirm that there are no unsupported special characters in the password

  • Reset the account if there is no other solution

Error

Problem: the computer is unable to communicate with the login server

Solution: run diagnostics

  • This can happen for a variety of reasons (DNS problems, broken services on the SRD etc.)

  • Run the script under deployment/administration/SRE_SRD_Remote_Diagnostics.ps1, providing the group and last IP octet of the problematic SRD

  • This will run a series of diagnostics intended to fix some common problems including

    • LDAP configuration

    • DNS configuration

    • SSS configuration

    • File mounting configuration

☁️ Unable to install from package mirrors#

If it is not possible to install packages from the package mirrors then this may be for one of the following reasons:

Error

Problem: Mirror VNet is not correctly peered

Solution: Re-run the network configuration script.

On your deployment machine.

  • Ensure you have the same version of the Data Safe Haven repository as was used by your deployment team

  • Open a Powershell terminal and navigate to the deployment/secure_research_environment/setup directory within the Data Safe Haven repository

  • Ensure you are logged into Azure within Powershell using the command: Connect-AzAccount

    • NB. 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.

  • Run the ./Apply_Network_Configuration.ps1 -sreId <SRE ID> script, where the SRE ID is the one specified in the config

Error

Problem: Internal mirror does not have the required package

Solution: Check package availability

To diagnose this, log into the Internal mirror using the Serial Console through the Azure portal. Check the packages directory (i.e. /datadrive/mirrordaemon/pypi/web/packages for PyPI or /datadrive/mirrordaemon/www/cran for CRAN)

Internal mirror package list

If the requested package should be available (i.e. it is on the appropriate allowlist), then you can force a mirror update by rebooting the EXTERNAL mirrors. This will trigger the following actions:

  1. Synchronisation of the external mirror with the remote, internet repository (a pull update)

  2. Synchronisation of the internal mirror with the external mirror (a push update)

This may take an hour or two but should solve the missing package problem.