如何借助QuickConnect扩展使用Guacamole API实现RDP远程连接

操作顺序与核心端点 #

1. 获取API访问令牌：调用/api/tokens端点完成身份验证，获取会话令牌
2. 发起QuickConnect RDP连接：使用令牌调用/api/quickconnect端点，创建临时RDP会话

步骤1：生成API令牌 #

端点信息 #

• 请求方法：POST
• 端点路径：https://<你的Guacamole服务器地址>/guacamole/api/tokens
• 请求头：Content-Type: application/x-www-form-urlencoded（注意：此接口不接受JSON格式请求）

必填参数 #

• username：Guacamole平台的用户名
• password：对应用户名的密码

curl示例 #

curl -X POST "https://your-guacamole-server/guacamole/api/tokens" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your-guac-user&password=your-guac-pass"

返回结果示例 #

成功后会返回包含令牌的JSON：

{
  "authToken": "abcdef1234567890",
  "username": "your-guac-user",
  "dataSource": "mysql",
  "availableDataSources": ["mysql"]
}

后续请求需要用到authToken的值作为身份凭证。

步骤2：调用QuickConnect API启动RDP会话 #

端点信息 #

• 请求方法：POST
• 端点路径：https://<你的Guacamole服务器地址>/guacamole/api/quickconnect
• 请求头：Content-Type: application/json
• 身份验证：将authToken通过URL参数token传递，或放在Authorization: Bearer <authToken>请求头中

必填参数（RDP协议） #

• protocol：固定值rdp
• hostname：远程RDP主机的IP或域名
• port：RDP服务端口，默认3389（数字类型，无需引号）
• （可选但常用）username/password：远程RDP主机的登录凭证（如果目标主机需要认证）

修正后的curl示例 #

curl -X POST "https://your-guacamole-server/guacamole/api/quickconnect?token=abcdef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "rdp",
    "hostname": "192.168.1.100",
    "port": 3389,
    "username": "rdp-user",
    "password": "rdp-pass"
  }'

返回结果说明 #

成功后会返回会话相关信息，包含connectionId和connectionToken，可用于后续与Guacamole的WebSocket连接建立桌面数据流。

常见问题排查 #

• 如果令牌请求失败：检查用户名密码是否正确，Guacamole服务是否正常，请求头的Content-Type是否为application/x-www-form-urlencoded
• 如果QuickConnect请求失败：
  1. 确认authToken未过期（默认有效期1小时）
  2. 检查RDP参数是否正确（比如端口是否开放、主机是否可达）
  3. 确保QuickConnect扩展已在Guacamole服务器上正确安装并启用

内容的提问来源于stack exchange，提问作者Arsalan Z