Add authentication documentation for Guacamole workspace service

[Copilot]

Summary

This PR adds detailed documentation explaining how authentication to VMs works through the Guacamole workspace service in Azure TRE. The documentation clarifies the authentication flow for both internal and external users, addressing a gap in understanding how VM access is secured and managed.

Changes Made

Main User Documentation (docs/tre-templates/workspace-services/guacamole.md)

Added a new section "Authentication to VMs via Apache Guacamole in Azure TRE" that explains:

• Initial Authentication: OIDC authentication via Azure Entra ID through OAuth2 Proxy
• Token Validation: Role validation ensuring users have required claims (WorkspaceOwner, WorkspaceResearcher, or AirlockManager)
• VM Discovery: How the extension queries the TRE API to fetch accessible VMs
• Credential Injection: Transparent injection of VM credentials from Azure Key Vault without user exposure
• Secure Access: Support for both internal and external users regardless of native Azure AD login capability

Technical Documentation (templates/workspace_services/guacamole/guacamole-server/guacamole-auth-azure/readme.md)

Enhanced the TRE Authorization extension section with:

• Detailed Authentication Flow: Step-by-step technical process from token reception to credential injection
• Security Features: Zero-trust access model, API-mediated authorization, and credential rotation capabilities
• Implementation Details: Specific API endpoints, Key Vault secret naming patterns, and managed identity usage

Why This Matters

This documentation is particularly valuable for:

• External Users: Understanding how guest users can securely access VMs without Azure AD accounts on the VM OS
• TRE Administrators: Clear overview of the security model and authentication flow
• Developers: Technical implementation details for extension development and troubleshooting

Authentication Flow Summary

User → OIDC/OAuth2 Proxy → Guacamole Extension → Token Validation → TRE API → VM List
                                                                              ↓
User Connects to VM ← Credential Injection ← Azure Key Vault ← TRE API ← VM Selection

All VM credentials are managed centrally in Azure Key Vault and never exposed to end users, enabling secure access for users who may not have direct VM accounts or Azure AD login capability.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[marrobi]

@copilot please remove the readme file and include all the docs in the actual docs.

[Copilot]

@copilot please remove the readme file and include all the docs in the actual docs.

Done! I've consolidated all the authentication documentation into the main docs file (docs/tre-templates/workspace-services/guacamole.md) and removed the separate readme file. The documentation now includes both the high-level authentication overview and detailed technical implementation details in one place. (6f4e85d)

[marrobi]

@copilot pease do nto make claims about what it does, purely document how it works. Do not include any versions etc that may change over time. Include an intro to the guacamole workspace service at the top of the page.

[Copilot]

@copilot pease do nto make claims about what it does, purely document how it works. Do not include any versions etc that may change over time. Include an intro to the guacamole workspace service at th...

Updated the documentation to focus on how the authentication works rather than making claims about capabilities, removed the OAuth2 Proxy version reference, and added a proper introduction to the Guacamole workspace service at the top of the page. (a8186a8)

[marrobi]

LGTM

[marrobi]

@copilot fix the linting.

/github/workspace/docs/tre-templates/workspace-services/guacamole.md:31:27 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]

[Copilot]

@copilot fix the linting.

/github/workspace/docs/tre-templates/workspace-services/guacamole.md:31:27 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
...

Fixed the trailing spaces linting error on line 31. (f7b8e1c)

[marrobi]

@copilot fix the build issue.

[Copilot]

@copilot fix the build issue.

I've tested the documentation build locally and it's working correctly with both mkdocs build and mkdocs build --strict. Could you provide more details about the specific build error you're seeing? For example:

• Is this a GitHub Actions workflow failure?
• What's the exact error message?
• Which build step is failing?

This will help me identify and fix the specific issue.

[github-actions]

Unit Test Results

15 tests   15 ✅  1s ⏱️
 4 suites   0 💤
 4 files     0 ❌

Results for commit a2067b7.

[marrobi]

@copilot fix this linting

/github/workspace/docs/tre-templates/workspace-services/guacamole.md:18:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3]
/github/workspace/docs/tre-templates/workspace-services/guacamole.md:19:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3]
/github/workspace/docs/tre-templates/workspace-services/guacamole.md:20:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3]
/github/workspace/docs/tre-templates/workspace-services/guacamole.md:21:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3]

[Copilot]

@copilot fix this linting

/github/workspace/docs/tre-templates/workspace-services/guacamole.md:18:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 3]
...

Fixed the MD007 unordered list indentation issues on lines 18-21 by changing from 3-space to 2-space indentation as required by the linting configuration. (a8cec1e)

[marrobi]

/test-force-approve

Docs

[github-actions]

🤖 pr-bot 🤖

✅ Marking tests as complete (for commit 54f77eb)

(in response to this comment from @marrobi)

[marrobi]

LGTM

[jonnyry]

LGTM