From a8cbdb1f1f2f74961b8135ddbcbe9b798878fc21 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:30:01 +0000 Subject: [PATCH 1/7] Initial plan From 50805f365170e6fe4051f680a2f015805124f560 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:34:30 +0000 Subject: [PATCH 2/7] Add comprehensive authentication documentation for Guacamole workspace service Co-authored-by: marrobi <17089773+marrobi@users.noreply.github.com> --- .../workspace-services/guacamole.md | 16 +++++++++++ .../guacamole-auth-azure/readme.md | 28 ++++++++++++++++--- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index 6196ad0680..afc048bd68 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -2,6 +2,22 @@ See: [https://guacamole.apache.org/](https://guacamole.apache.org/) +## Authentication to VMs via Apache Guacamole in Azure TRE + +The Guacamole workspace service provides secure remote access to Virtual Machines (VMs) through a sophisticated authentication and authorization process that works seamlessly for both internal and external users: + +- **Initial Authentication**: Users authenticate to Guacamole using OIDC (OpenID Connect) via Azure Entra ID (Azure AD), typically mediated by OAuth2 Proxy. + +- **Token Validation**: The Guacamole extension receives and validates the user's token, ensuring required roles/claims are present (WorkspaceOwner, WorkspaceResearcher, or AirlockManager). + +- **VM Discovery**: The extension queries the TRE API to fetch the list of VMs the authenticated user may access based on their permissions. + +- **Credential Injection**: When the user connects to a VM, the extension fetches the VM credentials (username and password) from the TRE API (sourced from Azure Key Vault) and transparently injects these into the Guacamole connection configuration. The user never sees these credentials directly. + +- **Secure Access**: This approach allows both internal and external (guest) users to access VMs securely, regardless of whether native Azure AD login to the VM OS is supported. + +All access is brokered via the TRE API and local VM credentials are managed securely, enabling VM access for users that may not have direct accounts on the VM OS or direct Azure AD login capability. + ## Firewall Rules Please be aware that the following Firewall rules are opened for the workspace when this service is deployed: diff --git a/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md b/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md index 5aa0329ccd..8cc34a2d27 100644 --- a/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md +++ b/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md @@ -6,11 +6,31 @@ Read more [here](https://guacamole.apache.org/doc/gug/guacamole-ext.html). ## TRE Authorization extension -This extension works in the following manner: +This extension provides secure authentication and authorization for VM access in Azure TRE. It works in the following manner: -1. receives a token from the OpenId extension -2. The extension call the project api to get the user's vm list -3. When connect request is made, the extension call the project api to get the password to the selected vm and inject it into the Guacamole configurations. +### Authentication Flow + +1. **Token Reception**: Receives and validates an OIDC token from the OAuth2 Proxy extension after the user has authenticated via Azure Entra ID. + +2. **Role Validation**: Validates that the token contains the required `roles` claim with at least one of the following roles: + - `WorkspaceOwner` + - `WorkspaceResearcher` + - `AirlockManager` + +3. **VM Discovery**: Calls the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to get the list of VMs the authenticated user may access. + +4. **Credential Injection**: When a connection request is made to a specific VM, the extension: + - Retrieves VM credentials from Azure Key Vault using the managed identity + - Extracts the username and password from the secret named `{hostname}-admin-credentials` + - Transparently injects these credentials into the Guacamole connection configuration + - The user never sees or handles these credentials directly + +### Security Features + +- **Zero-Trust Access**: Users never have direct access to VM credentials +- **API-Mediated Authorization**: All access decisions are made through the TRE API +- **External User Support**: Enables secure VM access for guest users who may not have Azure AD accounts on the VM OS +- **Credential Rotation**: VM credentials are managed centrally in Azure Key Vault and can be rotated without user impact ## OAuth2 Proxy From c2b7bd31f7f989523a0162b89007b23c6035b040 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:40:34 +0000 Subject: [PATCH 3/7] Consolidate authentication documentation into main docs and remove readme Co-authored-by: marrobi <17089773+marrobi@users.noreply.github.com> --- .../workspace-services/guacamole.md | 39 ++++++++++++++++ .../guacamole-auth-azure/readme.md | 45 ------------------- 2 files changed, 39 insertions(+), 45 deletions(-) delete mode 100644 templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index afc048bd68..3fa2d6c183 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -18,6 +18,45 @@ The Guacamole workspace service provides secure remote access to Virtual Machine All access is brokered via the TRE API and local VM credentials are managed securely, enabling VM access for users that may not have direct accounts on the VM OS or direct Azure AD login capability. +### Detailed Authentication Flow + +The TRE Authorization extension implements the following detailed authentication process: + +1. **Token Reception**: Receives and validates an OIDC token from the OAuth2 Proxy extension after the user has authenticated via Azure Entra ID. + +2. **Role Validation**: Validates that the token contains the required `roles` claim with at least one of the following roles: + - `WorkspaceOwner` + - `WorkspaceResearcher` + - `AirlockManager` + +3. **VM Discovery**: Calls the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to get the list of VMs the authenticated user may access. + +4. **Credential Injection**: When a connection request is made to a specific VM, the extension: + - Retrieves VM credentials from Azure Key Vault using the managed identity + - Extracts the username and password from the secret named `{hostname}-admin-credentials` + - Transparently injects these credentials into the Guacamole connection configuration + - The user never sees or handles these credentials directly + +### Security Features + +- **Zero-Trust Access**: Users never have direct access to VM credentials +- **API-Mediated Authorization**: All access decisions are made through the TRE API +- **External User Support**: Enables secure VM access for guest users who may not have Azure AD accounts on the VM OS +- **Credential Rotation**: VM credentials are managed centrally in Azure Key Vault and can be rotated without user impact + +### OAuth2 Proxy Integration + +The authentication system uses [OAuth2_Proxy](https://github.com/oauth2-proxy/oauth2-proxy) which is a reverse proxy and static file server that provides authentication using Providers to validate accounts by email, domain or group. + +- The current version in use is **7.4.0** +- The main configuration is controlled by the runtime arguments in the OAuth2 Proxy service +- The Guacamole auth extension uses the generic provider (OIDC) since the Azure provider has known issues +- Important configuration includes: + - `--insecure-oidc-allow unverified-email true` + - `--oidc-groups-claim "roles"` + +These settings were added to address [OAuth2 Proxy issue #1680](https://github.com/oauth2-proxy/oauth2-proxy/issues/1680). + ## Firewall Rules Please be aware that the following Firewall rules are opened for the workspace when this service is deployed: diff --git a/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md b/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md deleted file mode 100644 index 8cc34a2d27..0000000000 --- a/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md +++ /dev/null @@ -1,45 +0,0 @@ -# Guacamole Authorization Extension - -This extension is built (maven) and is placed inside the extension directory. -Guacamole tries to authorize using all the given extensions. -Read more [here](https://guacamole.apache.org/doc/gug/guacamole-ext.html). - -## TRE Authorization extension - -This extension provides secure authentication and authorization for VM access in Azure TRE. It works in the following manner: - -### Authentication Flow - -1. **Token Reception**: Receives and validates an OIDC token from the OAuth2 Proxy extension after the user has authenticated via Azure Entra ID. - -2. **Role Validation**: Validates that the token contains the required `roles` claim with at least one of the following roles: - - `WorkspaceOwner` - - `WorkspaceResearcher` - - `AirlockManager` - -3. **VM Discovery**: Calls the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to get the list of VMs the authenticated user may access. - -4. **Credential Injection**: When a connection request is made to a specific VM, the extension: - - Retrieves VM credentials from Azure Key Vault using the managed identity - - Extracts the username and password from the secret named `{hostname}-admin-credentials` - - Transparently injects these credentials into the Guacamole connection configuration - - The user never sees or handles these credentials directly - -### Security Features - -- **Zero-Trust Access**: Users never have direct access to VM credentials -- **API-Mediated Authorization**: All access decisions are made through the TRE API -- **External User Support**: Enables secure VM access for guest users who may not have Azure AD accounts on the VM OS -- **Credential Rotation**: VM credentials are managed centrally in Azure Key Vault and can be rotated without user impact - -## OAuth2 Proxy - - -- The extention uses [OAuth2_Proxy](https://github.com/oauth2-proxy/oauth2-proxy) which is a reverse proxy and static file server that provides authentication using Providers to validate accounts by email, domain or group. -- The current version that is being used is **7.4.0.** -- The main file that controls the behavior of the oauth2 proxy is the [run](/workspaces/AzureTRE/templates/workspace_services/guacamole/guacamole-server/docker/services/oauth/run) file, which contains all the runtime arguments. -- Some important notes on the way we use the oauth2 proxy: - - Guacamole auth extention uses the generic provider (oidc) since the Azure provider is broken in the proxy repository. - - When upgraded to version 7.4.0, \ - `--insecure-oidc-allow unverified-email true, - --oidc-groups-claim "roles"` were added becaue of this following [issue](https://github.com/oauth2-proxy/oauth2-proxy/issues/1680). From 20acb80ae300e7c7e7dc843f9a341af59a1badd8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Jun 2025 12:48:14 +0000 Subject: [PATCH 4/7] Update Guacamole documentation to focus on how it works, remove version info, and add service intro Co-authored-by: marrobi <17089773+marrobi@users.noreply.github.com> --- docs/tre-templates/workspace-services/guacamole.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index 3fa2d6c183..a8186a8f7c 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -1,10 +1,12 @@ # Guacamole Service bundle +The Guacamole workspace service is a remote desktop gateway service that uses Apache Guacamole to access Virtual Machines (VMs) within Azure TRE workspaces. The service acts as a web-based remote desktop proxy, allowing users to connect to VMs through a web browser without requiring client software installation. + See: [https://guacamole.apache.org/](https://guacamole.apache.org/) ## Authentication to VMs via Apache Guacamole in Azure TRE -The Guacamole workspace service provides secure remote access to Virtual Machines (VMs) through a sophisticated authentication and authorization process that works seamlessly for both internal and external users: +The Guacamole workspace service uses a multi-step authentication and authorization process to broker access to Virtual Machines (VMs): - **Initial Authentication**: Users authenticate to Guacamole using OIDC (OpenID Connect) via Azure Entra ID (Azure AD), typically mediated by OAuth2 Proxy. @@ -14,9 +16,9 @@ The Guacamole workspace service provides secure remote access to Virtual Machine - **Credential Injection**: When the user connects to a VM, the extension fetches the VM credentials (username and password) from the TRE API (sourced from Azure Key Vault) and transparently injects these into the Guacamole connection configuration. The user never sees these credentials directly. -- **Secure Access**: This approach allows both internal and external (guest) users to access VMs securely, regardless of whether native Azure AD login to the VM OS is supported. +- **Secure Access**: This approach works for both internal and external (guest) users, regardless of whether native Azure AD login to the VM OS is configured. -All access is brokered via the TRE API and local VM credentials are managed securely, enabling VM access for users that may not have direct accounts on the VM OS or direct Azure AD login capability. +All access is brokered via the TRE API and local VM credentials are managed through Azure Key Vault, supporting users who may not have direct accounts on the VM OS or direct Azure AD login capability. ### Detailed Authentication Flow @@ -41,14 +43,13 @@ The TRE Authorization extension implements the following detailed authentication - **Zero-Trust Access**: Users never have direct access to VM credentials - **API-Mediated Authorization**: All access decisions are made through the TRE API -- **External User Support**: Enables secure VM access for guest users who may not have Azure AD accounts on the VM OS +- **External User Support**: Functions with guest users who may not have Azure AD accounts on the VM OS - **Credential Rotation**: VM credentials are managed centrally in Azure Key Vault and can be rotated without user impact ### OAuth2 Proxy Integration -The authentication system uses [OAuth2_Proxy](https://github.com/oauth2-proxy/oauth2-proxy) which is a reverse proxy and static file server that provides authentication using Providers to validate accounts by email, domain or group. +The authentication system uses [OAuth2_Proxy](https://github.com/oauth2-proxy/oauth2-proxy) which is a reverse proxy and static file server that handles authentication using Providers to validate accounts by email, domain or group. -- The current version in use is **7.4.0** - The main configuration is controlled by the runtime arguments in the OAuth2 Proxy service - The Guacamole auth extension uses the generic provider (OIDC) since the Azure provider has known issues - Important configuration includes: From a8cec1e2399bf3980937346c08e1bd65795e7793 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Jun 2025 13:21:45 +0000 Subject: [PATCH 5/7] Fix trailing spaces in Guacamole documentation Co-authored-by: marrobi <17089773+marrobi@users.noreply.github.com> --- docs/tre-templates/workspace-services/guacamole.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index a8186a8f7c..17ba75beee 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -28,7 +28,7 @@ The TRE Authorization extension implements the following detailed authentication 2. **Role Validation**: Validates that the token contains the required `roles` claim with at least one of the following roles: - `WorkspaceOwner` - - `WorkspaceResearcher` + - `WorkspaceResearcher` - `AirlockManager` 3. **VM Discovery**: Calls the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to get the list of VMs the authenticated user may access. From a2067b7bea2876fb5dea2e7cf5d63d34765b6028 Mon Sep 17 00:00:00 2001 From: Marcus Robinson Date: Fri, 27 Jun 2025 09:14:25 +0100 Subject: [PATCH 6/7] Update docs and version --- .../workspace-services/guacamole.md | 59 ++++--------------- .../guacamole-server/docker/version.txt | 2 +- 2 files changed, 11 insertions(+), 50 deletions(-) diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index 17ba75beee..a57806c9dc 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -8,55 +8,31 @@ See: [https://guacamole.apache.org/](https://guacamole.apache.org/) The Guacamole workspace service uses a multi-step authentication and authorization process to broker access to Virtual Machines (VMs): -- **Initial Authentication**: Users authenticate to Guacamole using OIDC (OpenID Connect) via Azure Entra ID (Azure AD), typically mediated by OAuth2 Proxy. +- **Initial Authentication**: Users authenticate to Guacamole using OIDC (OpenID Connect) via Azure Entra ID (Azure AD) mediated by OAuth2 Proxy. -- **Token Validation**: The Guacamole extension receives and validates the user's token, ensuring required roles/claims are present (WorkspaceOwner, WorkspaceResearcher, or AirlockManager). +- **Token Validation**: The Guacamole extension receives and validates an OIDC token from the OAuth2 Proxy extension after the user has authenticated via Azure Entra ID, ensuring workspace roles are present in the token. -- **VM Discovery**: The extension queries the TRE API to fetch the list of VMs the authenticated user may access based on their permissions. +- **VM Discovery**: The extension queries the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to fetch the list of VMs the authenticated user may access based on their permissions. -- **Credential Injection**: When the user connects to a VM, the extension fetches the VM credentials (username and password) from the TRE API (sourced from Azure Key Vault) and transparently injects these into the Guacamole connection configuration. The user never sees these credentials directly. - -- **Secure Access**: This approach works for both internal and external (guest) users, regardless of whether native Azure AD login to the VM OS is configured. - -All access is brokered via the TRE API and local VM credentials are managed through Azure Key Vault, supporting users who may not have direct accounts on the VM OS or direct Azure AD login capability. - -### Detailed Authentication Flow - -The TRE Authorization extension implements the following detailed authentication process: - -1. **Token Reception**: Receives and validates an OIDC token from the OAuth2 Proxy extension after the user has authenticated via Azure Entra ID. - -2. **Role Validation**: Validates that the token contains the required `roles` claim with at least one of the following roles: - - `WorkspaceOwner` - - `WorkspaceResearcher` - - `AirlockManager` - -3. **VM Discovery**: Calls the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to get the list of VMs the authenticated user may access. - -4. **Credential Injection**: When a connection request is made to a specific VM, the extension: +- **Credential Injection**: When a connection request is made to a specific VM, the extension: - Retrieves VM credentials from Azure Key Vault using the managed identity - Extracts the username and password from the secret named `{hostname}-admin-credentials` - Transparently injects these credentials into the Guacamole connection configuration - The user never sees or handles these credentials directly -### Security Features -- **Zero-Trust Access**: Users never have direct access to VM credentials -- **API-Mediated Authorization**: All access decisions are made through the TRE API -- **External User Support**: Functions with guest users who may not have Azure AD accounts on the VM OS -- **Credential Rotation**: VM credentials are managed centrally in Azure Key Vault and can be rotated without user impact +- **Secure Access**: This approach works for both internal and external (guest) users, regardless of whether native Azure AD login to the VM OS is configured. + +All access is brokered via the TRE API and local VM credentials are managed through Azure Key Vault, supporting users who may not have direct accounts on the VM OS or direct Azure AD login capability. ### OAuth2 Proxy Integration The authentication system uses [OAuth2_Proxy](https://github.com/oauth2-proxy/oauth2-proxy) which is a reverse proxy and static file server that handles authentication using Providers to validate accounts by email, domain or group. +### Guacamole Authorization Extension -- The main configuration is controlled by the runtime arguments in the OAuth2 Proxy service -- The Guacamole auth extension uses the generic provider (OIDC) since the Azure provider has known issues -- Important configuration includes: - - `--insecure-oidc-allow unverified-email true` - - `--oidc-groups-claim "roles"` +The extension is built (maven) and is placed inside the extension directory. Guacamole tries to authorize using all the given extensions. -These settings were added to address [OAuth2 Proxy issue #1680](https://github.com/oauth2-proxy/oauth2-proxy/issues/1680). +Read more [here](https://guacamole.apache.org/doc/gug/guacamole-ext.html). ## Firewall Rules @@ -69,18 +45,3 @@ Service Tags: ## Prerequisites - [A base workspace bundle installed](../workspaces/base.md) - -## Guacamole Workspace Service Configuration - -When deploying a Guacamole service into a workspace the following properties need to be configured. - -### Optional Properties - -| Property | Options | Description | -| -------- | ------- | ----------- | -| `guac_disable_copy` | `true`/`false` (Default: `true`) | Disable Copy functionality | -| `guac_disable_paste` | `true`/`false` (Default: `false`) | Disable Paste functionality" | -| `guac_enable_drive` | `true`/`false` (Default: `true`) | Enable mounted drive | -| `guac_disable_download` | `true`/`false` (Default: `true`) | Disable files download | -| `guac_disable_upload` | `true`/`false` (Default: `true`) | Disable files upload | -| `is_exposed_externally` | `true`/`false` (Default: `true`) | Is the Guacamole service exposed outside of the vnet | diff --git a/templates/workspace_services/guacamole/guacamole-server/docker/version.txt b/templates/workspace_services/guacamole/guacamole-server/docker/version.txt index f8c6ac7fea..50533e307d 100644 --- a/templates/workspace_services/guacamole/guacamole-server/docker/version.txt +++ b/templates/workspace_services/guacamole/guacamole-server/docker/version.txt @@ -1 +1 @@ -__version__ = "0.9.5" +__version__ = "0.9.6" From 54f77eb2ac7f5e4a15bdc77dfa1afa49b69947b1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Jun 2025 08:19:52 +0000 Subject: [PATCH 7/7] Fix MD007 unordered list indentation in Guacamole documentation Co-authored-by: marrobi <17089773+marrobi@users.noreply.github.com> --- docs/tre-templates/workspace-services/guacamole.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index a57806c9dc..5e14b26a48 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -15,10 +15,10 @@ The Guacamole workspace service uses a multi-step authentication and authorizati - **VM Discovery**: The extension queries the TRE API (`/api/workspaces/{workspace_id}/workspace-services/{service_id}/user-resources`) to fetch the list of VMs the authenticated user may access based on their permissions. - **Credential Injection**: When a connection request is made to a specific VM, the extension: - - Retrieves VM credentials from Azure Key Vault using the managed identity - - Extracts the username and password from the secret named `{hostname}-admin-credentials` - - Transparently injects these credentials into the Guacamole connection configuration - - The user never sees or handles these credentials directly + - Retrieves VM credentials from Azure Key Vault using the managed identity + - Extracts the username and password from the secret named `{hostname}-admin-credentials` + - Transparently injects these credentials into the Guacamole connection configuration + - The user never sees or handles these credentials directly - **Secure Access**: This approach works for both internal and external (guest) users, regardless of whether native Azure AD login to the VM OS is configured.