Skip to content

Commit ecca633

Browse files
subbareddyalamur1subbareddyalamur1
committed
GUACAMOLE-2196: Add OpenBao vault integration extension
1 parent f7a9d87 commit ecca633

14 files changed

Lines changed: 1085 additions & 0 deletions

File tree

‎extensions/guacamole-vault/modules/guacamole-vault-openbao/.ratignore‎

Whitespace-only changes.

‎extensions/guacamole-vault/modules/guacamole-vault-openbao/README.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# OpenBao Vault Extension for Apache Guacamole
2+
3+
This extension integrates Apache Guacamole with [OpenBao](https://openbao.org/) vault to automatically retrieve connection credentials from OpenBao at connection time.
4+
5+
## Overview
6+
7+
The OpenBao vault extension allows Guacamole to retrieve credentials from an OpenBao server using token-based authentication. Connection parameters configured with special tokens like `${OPENBAO_SECRET}` are automatically replaced with values retrieved from OpenBao when a user connects.
8+
9+
## Features
10+
11+
- **Automatic Credential Retrieval**: Fetches credentials from OpenBao without requiring users to re-enter passwords
12+
- **Token-Based Resolution**: Uses `${OPENBAO_SECRET}` and `${GUAC_USERNAME}` tokens in connection parameters
13+
- **KV v2 Support**: Works with OpenBao KV v2 secrets engine
14+
- **Simple Configuration**: Minimal configuration required in `guacamole.properties`
15+
- **Secure**: Uses OpenBao's token-based authentication for secure API access
16+
17+
## How It Works
18+
19+
1. User logs into Guacamole with their username
20+
2. User initiates a connection configured with `${OPENBAO_SECRET}` token
21+
3. Extension queries OpenBao API to retrieve the secret for that username
22+
4. Password is extracted and injected into the connection parameters
23+
5. Connection proceeds with the retrieved credentials
24+
25+
## Configuration
26+
27+
### OpenBao Server Setup
28+
29+
Before using this extension, you need:
30+
31+
1. An OpenBao server running and accessible from the Guacamole server
32+
2. A KV v2 secrets engine mounted (eg path: `guacamole-credentails`)
33+
3. An OpenBao authentication token with read access to the secrets
34+
4. Secrets stored with a `password` field in the data
35+
36+
Example secret structure:
37+
```json
38+
{
39+
"data": {
40+
"data": {
41+
"username": "user1",
42+
"password": "SecretPassword123"
43+
}
44+
}
45+
}
46+
```
47+
48+
### Guacamole Configuration
49+
50+
Add the following properties to `guacamole.properties`:
51+
52+
```properties
53+
# OpenBao server URL (required)
54+
openbao-server-url: http://openbao.example.com:8200
55+
56+
# OpenBao authentication token (required)
57+
openbao-token: s.YourTokenHere
58+
59+
# KV mount path (optional, default: guacamole-credentails)
60+
openbao-mount-path: guacamole-credentails
61+
```
62+
63+
**Note**: The extension uses hardcoded defaults for:
64+
- KV version: `2` (KV v2 secrets engine)
65+
- Connection timeout: `5000ms` (5 seconds)
66+
- Request timeout: `10000ms` (10 seconds)
67+
68+
### Connection Configuration
69+
70+
When creating connections in Guacamole, use these token patterns:
71+
72+
- **`${OPENBAO_SECRET}`**: Replaced with the password from OpenBao
73+
- **`${GUAC_USERNAME}`**: Replaced with the logged-in Guacamole username
74+
75+
Example RDP connection:
76+
- Username: `${GUAC_USERNAME}`
77+
- Password: `${OPENBAO_SECRET}`
78+
- Hostname: `192.168.1.100`
79+
80+
## Secret Path Mapping
81+
82+
The extension maps Guacamole usernames directly to OpenBao secret paths:
83+
84+
```
85+
Guacamole username: "john"
86+
OpenBao secret path: /v1/guacamole-credentails/data/john
87+
```
88+
89+
For each user, create a corresponding secret in OpenBao at the path matching their Guacamole username.
90+
91+
## Building
92+
93+
Build the extension from the guacamole-client source tree:
94+
95+
```bash
96+
cd extensions/guacamole-vault
97+
mvn clean package
98+
```
99+
100+
The built extension will be located at:
101+
```
102+
modules/guacamole-vault-openbao/target/guacamole-vault-openbao-<version>.jar
103+
```
104+
105+
## Installation
106+
107+
1. Copy the built JAR to the Guacamole extensions directory:
108+
```bash
109+
cp guacamole-vault-openbao-*.jar /etc/guacamole/extensions/
110+
```
111+
112+
2. Ensure `guacamole-vault-base-*.jar` is also present in the extensions directory (it's a dependency)
113+
114+
3. Configure `guacamole.properties` as described above
115+
116+
4. Restart Guacamole (e.g., restart Tomcat)
117+
118+
## Security Considerations
119+
120+
1. **Protect the OpenBao Token**: Use a dedicated token with minimal permissions (read-only access to required secret paths)
121+
122+
2. **Use TLS in Production**: Always use HTTPS URLs for OpenBao in production:
123+
```properties
124+
openbao-server-url: https://openbao.example.com:8200
125+
```
126+
127+
3. **Network Security**: Restrict OpenBao access to the Guacamole server using firewall rules
128+
129+
4. **Audit Logging**: Enable OpenBao audit logging to track credential access
130+
131+
5. **Token Rotation**: Regularly rotate OpenBao tokens and update the configuration
132+
133+
## Troubleshooting
134+
135+
### Extension Not Loading
136+
137+
Check the Guacamole logs (typically in Tomcat's `catalina.out`) for errors. Common issues:
138+
139+
- Missing `guacamole-vault-base` dependency
140+
- Incorrect permissions on JAR files
141+
- Configuration errors in `guacamole.properties`
142+
143+
### Secret Not Found
144+
145+
Error: `Secret not found in OpenBao for username: john`
146+
147+
Solutions:
148+
1. Verify the secret exists in OpenBao at the expected path
149+
2. Check that the Guacamole username matches the secret name in OpenBao
150+
3. Verify the token has read access to the secret
151+
152+
### Permission Denied
153+
154+
Error: `Permission denied accessing OpenBao. Check token permissions.`
155+
156+
Solutions:
157+
1. Verify the token has appropriate policies attached
158+
2. Check that the token hasn't expired
159+
3. Ensure the token has read access to the KV mount path
160+
161+
### Connection Timeout
162+
163+
Error: `Failed to communicate with OpenBao`
164+
165+
Solutions:
166+
1. Verify OpenBao is accessible from the Guacamole server
167+
2. Check firewall rules between Guacamole and OpenBao
168+
3. Verify the OpenBao URL is correct in the configuration
169+
170+
## Example Deployment
171+
172+
1. **Setup OpenBao**:
173+
```bash
174+
# Start OpenBao
175+
bao server -dev
176+
177+
# Enable KV v2 engine
178+
bao secrets enable -path=guacamole-credentails kv-v2
179+
180+
# Create a secret
181+
bao kv put guacamole-credentails/john password=SecretPass123
182+
```
183+
184+
2. **Configure Guacamole**:
185+
```properties
186+
openbao-server-url: http://openbao.example.com:8200
187+
openbao-token: s.yourtokenhere
188+
openbao-mount-path: guacamole-credentails
189+
```
190+
191+
3. **Create Connection**:
192+
- Name: Windows Server
193+
- Protocol: RDP
194+
- Hostname: 192.168.1.100
195+
- Username: `${GUAC_USERNAME}`
196+
- Password: `${OPENBAO_SECRET}`
197+
198+
4. **Connect**: Log in as user "john" and connect to the Windows Server connection. The password will be automatically retrieved from OpenBao.
199+
200+
## License
201+
202+
This extension is licensed under the Apache License, Version 2.0. See the LICENSE file for details.
203+
204+
## Support
205+
206+
For issues or questions:
207+
- Apache Guacamole: https://guacamole.apache.org/
208+
- OpenBao: https://openbao.org/
209+
- Issue Tracker: https://issues.apache.org/jira/browse/GUACAMOLE/

‎extensions/guacamole-vault/modules/guacamole-vault-openbao/pom.xml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
Licensed to the Apache Software Foundation (ASF) under one
4+
or more contributor license agreements. See the NOTICE file
5+
distributed with this work for additional information
6+
regarding copyright ownership. The ASF licenses this file
7+
to you under the Apache License, Version 2.0 (the
8+
"License"); you may not use this file except in compliance
9+
with the License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing,
14+
software distributed under the License is distributed on an
15+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
KIND, either express or implied. See the License for the
17+
specific language governing permissions and limitations
18+
under the License.
19+
-->
20+
<project xmlns="http://maven.apache.org/POM/4.0.0"
21+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
22+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
23+
http://maven.apache.org/maven-v4_0_0.xsd">
24+
25+
<modelVersion>4.0.0</modelVersion>
26+
<groupId>org.apache.guacamole</groupId>
27+
<artifactId>guacamole-vault-openbao</artifactId>
28+
<packaging>jar</packaging>
29+
<name>guacamole-vault-openbao</name>
30+
<url>http://guacamole.apache.org/</url>
31+
32+
<parent>
33+
<groupId>org.apache.guacamole</groupId>
34+
<artifactId>guacamole-vault</artifactId>
35+
<version>${revision}</version>
36+
<relativePath>../../</relativePath>
37+
</parent>
38+
39+
<dependencies>
40+
41+
<!-- Guacamole Extension API -->
42+
<dependency>
43+
<groupId>org.apache.guacamole</groupId>
44+
<artifactId>guacamole-ext</artifactId>
45+
</dependency>
46+
47+
<!-- Guacamole base key vault support -->
48+
<dependency>
49+
<groupId>org.apache.guacamole</groupId>
50+
<artifactId>guacamole-vault-base</artifactId>
51+
<version>${revision}</version>
52+
</dependency>
53+
54+
<!-- Apache HttpClient 5 for REST API calls -->
55+
<dependency>
56+
<groupId>org.apache.httpcomponents.client5</groupId>
57+
<artifactId>httpclient5</artifactId>
58+
<version>5.2.1</version>
59+
</dependency>
60+
61+
<!-- Gson for JSON parsing -->
62+
<dependency>
63+
<groupId>com.google.code.gson</groupId>
64+
<artifactId>gson</artifactId>
65+
<version>2.10.1</version>
66+
</dependency>
67+
68+
</dependencies>
69+
70+
</project>

‎extensions/guacamole-vault/modules/guacamole-vault-openbao/src/main/java/org/apache/guacamole/vault/openbao/OpenBaoAuthenticationProvider.java‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.apache.guacamole.vault.openbao;
21+
22+
import org.apache.guacamole.GuacamoleException;
23+
import org.apache.guacamole.vault.VaultAuthenticationProvider;
24+
import org.slf4j.Logger;
25+
import org.slf4j.LoggerFactory;
26+
27+
/**
28+
* OpenBao authentication provider that retrieves RDP passwords from OpenBao.
29+
* This provider integrates with the Guacamole vault framework to automatically
30+
* fetch passwords from OpenBao based on the logged-in username.
31+
*/
32+
public class OpenBaoAuthenticationProvider extends VaultAuthenticationProvider {
33+
34+
/**
35+
* Logger for this class.
36+
*/
37+
private static final Logger logger = LoggerFactory.getLogger(OpenBaoAuthenticationProvider.class);
38+
39+
/**
40+
* Creates a new OpenBaoAuthenticationProvider.
41+
*
42+
* @throws GuacamoleException
43+
* If an error occurs during initialization.
44+
*/
45+
public OpenBaoAuthenticationProvider() throws GuacamoleException {
46+
super(new OpenBaoAuthenticationProviderModule());
47+
logger.info("OpenBaoAuthenticationProvider initialized");
48+
}
49+
50+
@Override
51+
public String getIdentifier() {
52+
return "openbao";
53+
}
54+
}

0 commit comments

Comments
 (0)