diff --git a/docs/tre-templates/workspace-services/guacamole.md b/docs/tre-templates/workspace-services/guacamole.md index 6196ad0680..5e14b26a48 100644 --- a/docs/tre-templates/workspace-services/guacamole.md +++ b/docs/tre-templates/workspace-services/guacamole.md @@ -1,7 +1,39 @@ # 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 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) mediated by OAuth2 Proxy. + +- **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 (`/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 + + +- **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 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). + ## Firewall Rules Please be aware that the following Firewall rules are opened for the workspace when this service is deployed: @@ -13,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" 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 5aa0329ccd..0000000000 --- a/templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md +++ /dev/null @@ -1,25 +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 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. - -## 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).