diff --git a/docs/source/deployment/configure_entra_id.md b/docs/source/deployment/configure_entra_id.md index 88aad944eb..ea1cca6b7e 100644 --- a/docs/source/deployment/configure_entra_id.md +++ b/docs/source/deployment/configure_entra_id.md @@ -42,7 +42,7 @@ Use the following settings: - **Other fields:** leave them with their default values - **Properties** tab: - **Usage location:** set to the country being used for this deployment -- **Assigments** tab: +- **Assignments** tab: - Click the **{guilabel}`+ Add role`** button - Search for **Global Administrator**, and check the box - Click the **{guilabel}`Select`** button diff --git a/docs/source/management/egress_token_read_only.png b/docs/source/management/egress_token_read_only.png new file mode 100644 index 0000000000..a28ca2e99d Binary files /dev/null and b/docs/source/management/egress_token_read_only.png differ diff --git a/docs/source/management/index.md b/docs/source/management/index.md index e4f8406ab7..e9f49a5733 100644 --- a/docs/source/management/index.md +++ b/docs/source/management/index.md @@ -1,6 +1,8 @@ # Management -## Add users to the Data Safe Haven +## Managing users + +### Add users to the Data Safe Haven :::{important} You will need a full name, phone number, email address and country for each user. @@ -27,7 +29,7 @@ Grace;Hopper;+18005550100;grace@nasa.gov;US $ dsh users add PATH_TO_MY_CSV_FILE ``` -## Listing available users +### List available users - You can do this from the [Microsoft Entra admin centre](https://entra.microsoft.com/) @@ -54,7 +56,7 @@ $ dsh users add PATH_TO_MY_CSV_FILE └──────────────────────────────┴──────────┴───────────────────┘ ``` -## Assign existing users to an SRE +### Assign existing users to an SRE 1. You can do this directly in your Entra tenant by adding them to the **Data Safe Haven SRE _YOUR\_SRE\_NAME_ Users** group, following the instructions [here](https://learn.microsoft.com/en-us/entra/fundamentals/groups-view-azure-portal#add-a-group-member). @@ -70,7 +72,7 @@ $ dsh users add PATH_TO_MY_CSV_FILE Do not include the Entra ID domain part of the username, just the part before the @. ::: -## Manually register users for self-service password reset +### Manually register users for self-service password reset :::{tip} Users created via the `dsh users` command line tool will be automatically registered for SSPR. @@ -87,7 +89,9 @@ If you have manually created a user and want to enable SSPR, do the following - **Email:** enter the user's email address here - Click the **{guilabel}`Save`** icon in the top panel -## Listing available SRE configurations and deployment status +## Managing SREs + +### List available SRE configurations and deployment status - Run the following if you want to check what SRE configurations are available in the current context, and whether those SREs are deployed @@ -108,7 +112,7 @@ Available SRE configurations for context 'green': └──────────────┴──────────┘ ``` -## Removing a deployed Data Safe Haven +### Remove a deployed Data Safe Haven - Run the following if you want to teardown a deployed SRE: @@ -116,8 +120,96 @@ Available SRE configurations for context 'green': $ dsh sre teardown YOUR_SRE_NAME ``` +::::{admonition} Tearing down an SRE is destructive and irreversible +:class: danger +Running `dsh sre teardown` will destroy **all** resources deployed within the SRE. +Ensure that any desired outputs have been extracted before deleting the SRE. +**All** data remaining on the SRE will be deleted. +The user groups for the SRE on Microsoft Entra ID will also be deleted. +:::: + - Run the following if you want to teardown the deployed SHM: ```{code} shell $ dsh shm teardown ``` + +::::{admonition} Tearing down an SHM +:class: warning +Tearing down the SHM permanently deletes **all** remotely stored configuration and state data. +Tearing down the SHM also renders the SREs inaccessible to users and prevents them from being fully managed using the CLI. +All SREs associated with the SHM should be torn down before the SHM is torn down. +:::: + +## Managing data ingress and egress + +### Data Ingress + +It is the {ref}`role_data_provider_representative`'s responsibility to upload the data required by the safe haven. + +The following steps show how to generate a temporary, write-only upload token that can be securely sent to the {ref}`role_data_provider_representative`, enabling them to upload the data: + +- In the Azure portal select **Subscriptions** then navigate to the subscription containing the relevant SHM +- Search for the resource group: `shm--sre--rg`, then click through to the storage account ending with `sensitivedata` +- Browse to **{menuselection}`Settings --> Networking`** and ensure that the data provider's IP address is one of those allowed under the **Firewall** header + - If it is not listed, modify and reupload the SRE configuration and redeploy the SRE using the `dsh` CLI, as per {ref}`deploy_sre` +- Browse to **{menuselection}`Data storage --> Containers`** from the menu on the left hand side +- Click **ingress** +- Browse to **{menuselection}`Settings --> Shared access tokens`** and do the following: + - Under **Signing method**, select **User delegation key** + - Under **Permissions**, check these boxes: + - **Write** + - **List** + - Set a 24 hour time window in the **Start and expiry date/time** (or an appropriate length of time) + - Leave everything else as default and click **{guilabel}`Generate SAS token and URL`** + - Copy the **Blob SAS URL** + + ```{image} ingress_token_write_only.png + :alt: write-only SAS token + :align: center + ``` + +- Send the **Blob SAS URL** to the data provider through a secure channel +- The data provider should now be able to upload data +- Validate successful data ingress + - Browse to **{menuselection}`Data storage --> Containers`** (in the middle of the page) + - Select the **ingress** container and ensure that the uploaded files are present + +### Data egress + +```{important} +Assessment of output must be completed **before** an egress link is created. +Outputs are potentially sensitive, and so an appropriate process must be applied to ensure that they are suitable for egress. +``` + +The {ref}`role_system_manager` creates a time-limited and IP restricted link to remove data from the environment. + +- In the Azure portal select **Subscriptions** then navigate to the subscription containing the relevant SHM +- Search for the resource group: `shm--sre--rg`, then click through to the storage account ending with `sensitivedata` +- Browse to **{menuselection}`Settings --> Networking`** and check the list of pre-approved IP addresses allowed under the **Firewall** header + - Ensure that the IP address of the person to receive the outputs is listed + - If it is not listed, modify and reupload the SRE configuration and redeploy the SRE using the `dsh` CLI, as per {ref}`deploy_sre` +- Browse to **{menuselection}`Data storage --> Containers`** +- Select the **egress** container +- Browse to **{menuselection}`Settings --> Shared access tokens`** and do the following: + - Under **Signing method**, select **User delegation key** + - Under **Permissions**, check these boxes: + - **Read** + - **List** + - Set a time window in the **Start and expiry date/time** that gives enough time for the person who will perform the secure egress download to do so + - Leave everything else as default and press **{guilabel}`Generate SAS token and URL`** + - Copy the **Blob SAS URL** + + ```{image} egress_token_read_only.png + :alt: Read-only SAS token + :align: center + ``` + +- Send the **Blob SAS URL** to the relevant person through a secure channel +- The appropriate person should now be able to download data + +### The output volume + +Once you have set up the egress connection in Azure Storage Explorer, you should be able to view data from the **output volume**, a read-write area intended for the extraction of results, such as figures for publication. +On the workspaces, this volume is `/mnt/output` and is shared between all workspaces in an SRE. +For more information on shared SRE storage volumes, consult the {ref}`Safe Haven User Guide `. diff --git a/docs/source/management/ingress_token_write_only.png b/docs/source/management/ingress_token_write_only.png new file mode 100644 index 0000000000..34829ee4fa Binary files /dev/null and b/docs/source/management/ingress_token_write_only.png differ diff --git a/docs/source/roles/data_provider_representative/data_ingress.md b/docs/source/roles/data_provider_representative/data_ingress.md index 659ee706ad..cb4e12faa4 100644 --- a/docs/source/roles/data_provider_representative/data_ingress.md +++ b/docs/source/roles/data_provider_representative/data_ingress.md @@ -5,9 +5,22 @@ The **Dataset Provider Representative** plays an important role in data ingress. As well as being involved in agreeing an appropriate security tier for a project, they may also prepare the data to be uploaded. -## Preparing data +## Bringing data into the environment + +Talk to your {ref}`role_system_manager` to discuss possible methods of bringing data into the environments. +It may be convenient to use [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer/). +In this case you will not need log-in credentials, as your {ref}`role_system_manager` can provide a short-lived secure access token which will let you upload data. + +```{tip} +You may want to keep the following considerations in mind when transferring data in order to reduce the chance of a data breach. + +- Use of short-lived access tokens limits the time within which an attacker can operate. +- Letting your {ref}`role_system_manager` know a fixed IP address you will be connecting from (_e.g._ a corporate VPN) limits the places an attacker can operate from. +- Communicating with your {ref}`role_system_manager` through a secure out-of-band channel (_e.g._ encrypted email) reduces the chances that an attacker can intercept or alter your messages in transit. + +``` -This section has some recommendations for preparing input data for the Data Safe Haven. +## Preparing input data for the Data Safe Haven ### Avoid archives @@ -86,16 +99,3 @@ md5sum -c hashes.txt | grep FAILED ``` To use the `sha256` algorithm, replace `md5sum` with `sha256` in the above commands. - -## Bringing data into the environment - -Talk to your {ref}`role_system_manager` to discuss possible methods of bringing data into the environments. -It may be convenient to use [Azure Storage Explorer](https://azure.microsoft.com/en-us/products/storage/storage-explorer/). -In this case you will not need log-in credentials, as your {ref}`role_system_manager` can provide a short-lived secure access token which will let you upload data. - -```{tip} -You may want to keep the following considerations in mind when transferring data in order to reduce the chance of a data breach -- use of short-lived access tokens limits the time within which an attacker can operate -- letting your {ref}`role_system_manager` know a fixed IP address you will be connecting from (eg. a corporate VPN) limits the places an attacker can operate from -- communicating with your {ref}`role_system_manager` through a secure out-of-band channel (eg. encrypted email) reduces the chances that an attacker can intercept or alter your messages in transit -```