Merge pull request #299970 from RoseHJM/mdb-dev-tunnels

MDB - Dev tunnels

Author: denrea

articles/dev-box/how-to-conditional-access-dev-tunnels-service.md

@@ -0,0 +1,98 @@
+---
+title: Configure Conditional Access Policies for Dev Tunnels
+description: Learn how to configure conditional access policies for the Dev tunnels service in Microsoft Entra ID to secure remote development environments and restrict access based on device management and IP ranges.
+author: RoseHJM
+contributors:
+ms.topic: how-to
+ms.date: 05/19/2025
+ms.author: rosemalcolm
+ms.reviewer: rosemalcolm
+---
+
+# Configure conditional access policies for Dev tunnels
+
+Microsoft Dev Box gives you an alternative connectivity method on top of Dev tunnels. You can develop remotely while coding locally or keep development going during Azure Virtual Desktop (AVD) outages or poor network performance. Many large enterprises using Dev Box have strict security and compliance policies, and their code is valuable to their business. Restricting Dev tunnels with conditional access policies is crucial for these controls.
+
+Conditional access policies for the Dev tunnels service:
+
+- Let Dev tunnels connect from managed devices, but deny connections from unmanaged devices.
+- Let Dev tunnels connect from specific IP ranges, but deny connections from other IP ranges.
+- Support other regular conditional access configurations.
+- Apply to both the Visual Studio Code application and VS Code web.
+
+## Configure conditional access
+
+The conditional access policies work correctly for the Dev tunnels service. Because registering the Dev tunnels service app to a tenant and making it available to the conditional access picker is unique, this article documents the steps.
+
+## Register Dev tunnels service to a tenant
+
+According to [Application and service principal objects in Microsoft Entra ID](/entra/identity-platform/app-objects-and-service-principals?tabs=browser), a service principal is created in each tenant where an application is used. However, this doesn't apply to the Dev tunnels service. The Dev tunnels service is a Microsoft service, and the service principal is created in the Microsoft Entra ID tenant where the Dev tunnels service is registered. The Dev tunnels service app isn't registered to your tenant by default, so you need to register it manually.
+
+Therefore, we're using [Microsoft.Graph PowerShell](/powershell/module/microsoft.graph.authentication/connect-mggraph?view=graph-powershell-1.0&preserve-view=true) to register the app to a tenant.
+
+1. Install PowerShell 7.x
+
+1. Follow [Install the Microsoft Graph PowerShell SDK | Microsoft Learn](/powershell/microsoftgraph/installation?view=graph-powershell-1.0&preserve-view=true) to install Microsoft.Graph PowerShell.
+
+1. Run the following commands:
+    ```powershell
+    # Connect to Microsoft Graph
+    Connect-MgGraph -TenatnId <TenantID> -Scopes "Application.ReadWrite.All"
+  
+    # Register the Dev tunnels service app to the tenant
+    $TunnelServiceAppId = "46da2f7e-b5ef-422a-88d4-2a7f9de6a0b2"
+    New-MgServicePrincipal -AppId $TunnelServiceAppId
+    ```
+
+1. Go to "Microsoft Entra ID" -> "Manage" -> "Enterprise applications" to verify if the Dev tunnels service is registered.
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-register-service.png" alt-text="Screenshot of the Enterprise applications page in Microsoft Entra ID, showing the Dev tunnels service registration." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-register-service.png":::
+
+## Enable the Dev tunnels service for the conditional access picker
+
+The Microsoft Entra IDteam is working on removing the need to onboard apps for them to appear in the app picker, with delivery expected in May. Therefore, we aren't onboarding Dev tunnel service to the conditional access picker. Instead, target the Dev tunnels service in a conditional access policy using [Custom Security Attributes](/entra/identity/conditional-access/concept-filter-for-applications).
+
+1. Follow [Add or deactivate custom security attribute definitions in Microsoft Entra ID](/entra/fundamentals/custom-security-attributes-add?tabs=ms-powershell) to add the following Attribute set and New attributes.
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-custom-attributes.png" alt-text="Screenshot of the custom security attribute definition process in Microsoft Entra ID." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-custom-attributes.png":::
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-attribute.png" alt-text="Screenshot of the new attribute creation in Microsoft Entra ID." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-attribute.png":::
+
+1. Follow [Create a conditional access policy](/entra/identity/conditional-access/concept-filter-for-applications#create-a-conditional-access-policy) to create a conditional access policy.
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-conditional-access-policy.png" alt-text="Screenshot of the conditional access policy creation process for Dev tunnels service." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-conditional-access-policy.png":::
+
+1. Follow [Configure custom attributes](/entra/identity/conditional-access/concept-filter-for-applications#configure-custom-attributes) to configure the custom attribute for the Dev tunnels service.
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-security-attributes.png" alt-text="Screenshot of configuring custom attributes for the Dev tunnels service in Microsoft Entra ID." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-security-attributes.png":::
+
+## Testing
+
+1. Turn off the BlockDevTunnelCA
+
+1. Create a DevBox in the test tenant and run the following commands inside it. Dev tunnels can be created and connected externally.
+```
+code tunnel user login --provider microsoft
+code tunnel
+```
+
+1. Enable the BlockDevTunnelCA.
+
+    1. New connections to the existing Dev tunnels can't be established. Test with an alternate browser if a connection has already been established.
+
+    1. Any new attempts to execute the commands in step #2 will fail. Both errors are:
+
+       :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-no-access.png" alt-text="Screenshot of error message when Dev tunnels connection is blocked by conditional access policy." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-no-access.png":::
+
+1. The Microsoft Entra ID sign-in logs show these entries.
+
+   :::image type="content" source="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-activity-logs.png" alt-text="Screenshot of Microsoft Entra ID sign-in logs showing entries related to Dev tunnels conditional access policy." lightbox="media/how-to-conditional-access-dev-tunnels-service/dev-tunnels-activity-logs.png":::
+
+## Limitations
+
+With Dev Tunnels, the following limitations apply:
+- You can't configure conditional access policies for Dev Box service to manage Dev tunnels for Dev Box users.
+- You can't limit Dev tunnels that aren't managed by the Dev Box service. In the context of Dev Boxes, if the Dev tunnels GPO is configured **to allow only selected Microsoft Entra tenant IDs**, Conditional Access policies can also restrict self-created Dev tunnels.
+
+## Related content
+- [Conditional Access policies](/entra/identity/conditional-access/concept-conditional-access-policies)

articles/dev-box/how-to-set-up-dev-tunnels.md

@@ -0,0 +1,83 @@
+--- 
+title: Set Up Dev Tunnels and Connect to Microsoft Dev Box Using VS Code
+description: Learn how to set up and connect to your Microsoft Dev Box using the Open in VS Code feature. Follow step-by-step instructions to provision a Dev Box, install the Dev Box extension, enable tunnels, and connect remotely for development.
+author: RoseHJM
+contributors:
+ms.topic: how-to
+ms.date: 05/19/2025
+ms.author: rosemalcolm
+ms.reviewer: rosemalcolm
+---
+
+# Set up Dev tunnels in VS Code 
+
+Use Microsoft Dev Box with Visual Studio Code (VS Code) to create secure, cloud-based development environments. This article explains how to set up dev tunnels and connect to your Dev Box from VS Code. You'll learn how to install the required extension, enable secure tunnels, and connect remotely for a streamlined development experience. Follow these steps to get started quickly and work efficiently from anywhere.
+
+## Prerequisites
+- A dev box.
+    - If you don't have a dev box, create one following these steps: [Quickstart: Create and connect to a dev box by using the Microsoft Dev Box developer portal](quickstart-create-dev-box.md)
+
+## Configure a dev tunnel
+
+Follow these steps to set up a dev tunnel and connect to your dev box using VS Code.
+
+1. Install VS Code extension
+
+   Search for **Dev Box** in the VS Code Extension Marketplace and install the latest version (2.0.0 as of May 15, 2025) in your **local** VS Code—not in the Dev Box you want to connect to.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-dev-box-extension.png" alt-text="Screenshot of the Dev Box extension in VS Code.":::
+
+1. Sign in to Dev Box extension
+
+   Select the Dev Box icon in the left sidebar, and select **Sign In**.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-sign-in-extension.png" alt-text="Screenshot of the Dev Box extension showing the sign-in option.":::
+
+1. Create and enable Dev Box Tunnel
+
+   After signing in, you'll see all the projects you can access. Choose the project where you created the Dev Box, and select the Dev Box you want to connect to.
+
+   If you see **No Tunnel** in the description, manually create a tunnel resource first.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-create-tunnel.png" alt-text="Screenshot of the Dev Box extension showing the option to create a tunnel.":::
+
+   Before enabling the tunnel, you **MUST** log into the Dev Box at least once using any client (for example, browser, Windows App, Remote Desktop client). This step is **mandatory** after each shutdown and restart to establish the required user session for setting up the tunnel. Once logged in, you can disconnect from the Dev Box.
+
+   You don't need to sign in every time you enable or connect to the tunnel—only after a shutdown or restart.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-enable-tunnel.png" alt-text="Screenshot of enabling the tunnel in the Dev Box extension.":::
+
+   Then, enable the tunnel. This process can take 1–3 minutes, as it installs VS Code on the Dev Box (if not already installed) and sets up the tunnel.
+
+1. Connect to the Dev Box in VS Code
+
+   Once everything is set up, you can open the Dev Box in VS Code by clicking the **Connect to Tunnel** button.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-connect-tunnnel.png" alt-text="Screenshot of the Dev Box extension showing the option to connect to the tunnel.":::
+
+1. Explore the remote experience in VS Code
+
+   Open any folder or workspace on the remote Dev Box using **File > Open File/Folder/Workspace** just as you would locally. 
+
+   If you have a Windows Subsystem for Linux (WSL) environment on the Dev Box, connect to it using **Remote Explorer**.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-wsl-targets.png" alt-text="Screenshot of the Remote Explorer in VS Code showing WSL targets.":::
+
+   Select WSL targets from the dropdown to see all the WSL distributions. Open any WSL distribution in the current or a new window.
+
+   :::image type="content" source="media/how-to-set-up-dev-tunnels/dev-tunnels-ubuntu.png" alt-text="Screenshot of a WSL distribution terminal in VS Code.":::
+
+   For more information on the WSL development experience, see [Remote - WSL](https://code.visualstudio.com/docs/remote/wsl) and [Set up a WSL development environment](/windows/wsl/setup/environment).
+
+## Frequently asked questions
+
+- Why do I need to sign-in to the Dev Box before enabling the tunnel?
+
+   This step is required to establish a user session for setting up the tunnel. After the initial login, you can just disconnect from the Dev Box. Then you can enable or connect 
+
+- Why can't I connect to the Dev Box even if the tunnel is enabled?
+
+   Refresh the Dev Box extension explorer view with the button in the top right corner to check the latest status of the tunnel. If the tunnel is enabled, but you still can't connect, try disabling the tunnel, signing in to the Dev Box, and then re-enabling the tunnel.nnect, try disabling the tunnel, logging into the Dev Box, and then re-enabling the tunnel.
+
+## Related content
+- [Configure Conditional Access Policies for Dev Tunnels](how-to-conditional-access-dev-tunnels-service.md)