Merge pull request #2254 from craddm/doc-updates

Management documentation updates
alan-turing-institute · Oct 24, 2024 · 8a2fd5e · 8a2fd5e
2 parents fa7122e + f12de89
commit 8a2fd5e
Show file tree

Hide file tree

Showing 5 changed files with 114 additions and 22 deletions.
diff --git 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
diff --git 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;[email protected];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,16 +112,104 @@ 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:
 
 ```{code} shell
 $ 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-<YOUR_SHM_NAME>-sre-<YOUR_SRE_NAME>-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-<YOUR_SHM_NAME>-sre-<YOUR_SRE_NAME>-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 <role_researcher_shared_storage>`.
diff --git a/docs/source/management/ingress_token_write_only.png b/docs/source/management/ingress_token_write_only.png
diff --git 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
-```