GUACAMOLE-2196: OpenBao Vault Integration Extension by subbareddyalamur · Pull Request #1143 · apache/guacamole-client

subbareddyalamur · 2025-12-30T03:58:13Z

Pull Request: OpenBao Vault Integration Extension

Summary

This PR adds a new vault extension for integrating Apache Guacamole with OpenBao, an open-source secrets management platform (fork of HashiCorp Vault).

JIRA Issue

GUACAMOLE-XXXX (To be created at: https://issues.apache.org/jira/browse/GUACAMOLE-2196)

Motivation

OpenBao is a community-driven fork of HashiCorp Vault, maintained under the Linux Foundation. As organizations adopt OpenBao for secrets management, there is a need for native Guacamole integration to automatically retrieve connection credentials from OpenBao vaults. This extension enables:

Automatic Credential Retrieval: Users no longer need to manually manage or update connection passwords in Guacamole
Centralized Secrets Management: Credentials are stored and managed in OpenBao, not in Guacamole's database
Enhanced Security: Passwords are retrieved on-demand and never stored in Guacamole
User-Based Secret Mapping: Each Guacamole user can have their own set of credentials in OpenBao

Implementation Details

Architecture

The extension follows the same architectural pattern as the existing Keeper Secrets Manager (KSM) vault extension, utilizing the guacamole-vault-base framework. Key components:

OpenBaoAuthenticationProvider: Main extension entry point extending VaultAuthenticationProvider
OpenBaoSecretService: Implements VaultSecretService for token resolution and secret retrieval
OpenBaoClient: HTTP client for communicating with OpenBao REST API using Apache HttpClient 5
OpenBaoConfigurationService: Reads configuration from guacamole.properties
OpenBaoDirectoryService: Pass-through implementation (no directory management needed)
OpenBaoAttributeService: Minimal implementation (no custom attributes needed)

Token System

The extension supports two token patterns:

${OPENBAO_SECRET}: Replaced with the password retrieved from OpenBao
${GUAC_USERNAME}: Replaced with the logged-in Guacamole username

Secret Path Mapping

The extension maps Guacamole usernames directly to OpenBao KV v2 secret paths:

Guacamole username: "john"
OpenBao path: /v1/rdp-creds/data/john

Example secret structure in OpenBao:

{
  "data": {
    "data": {
      "username": "john",
      "password": "SecurePassword123"
    }
  }
}

Configuration

The extension requires minimal configuration in guacamole.properties:

# REQUIRED
openbao-server-url: http://openbao.example.com:8200
openbao-token: s.YourAuthTokenHere

# OPTIONAL (defaults shown)
openbao-mount-path: rdp-creds

Hardcoded defaults:

KV version: 2 (KV v2 secrets engine)
Connection timeout: 5000ms
Request timeout: 10000ms

Files Added

extensions/guacamole-vault/modules/guacamole-vault-openbao/
├── .ratignore
├── README.md
├── pom.xml
└── src/main/
    ├── java/org/apache/guacamole/vault/openbao/
    │   ├── OpenBaoAuthenticationProvider.java
    │   ├── OpenBaoAuthenticationProviderModule.java
    │   ├── conf/
    │   │   ├── OpenBaoConfig.java
    │   │   └── OpenBaoConfigurationService.java
    │   ├── secret/
    │   │   ├── OpenBaoClient.java
    │   │   └── OpenBaoSecretService.java
    │   └── user/
    │       ├── OpenBaoAttributeService.java
    │       └── OpenBaoDirectoryService.java
    └── resource-templates/
        └── guac-manifest.json

Files Modified

extensions/guacamole-vault/pom.xml: Added guacamole-vault-openbao module

Dependencies

New dependencies added for the OpenBao module:

org.apache.httpcomponents.client5:httpclient5:5.2.1 - HTTP client for REST API communication
com.google.code.gson:gson:2.10.1 - JSON parsing

Both dependencies are shaded into the final JAR.

Testing

Build Testing

The module builds successfully with Maven:

cd extensions/guacamole-vault
mvn clean install -DskipTests

Build output:

JAR: target/guacamole-vault-openbao-1.6.1.jar
All Apache RAT license checks pass
No compilation warnings or errors
Successfully integrates with guacamole-vault-dist module

Functional Testing

Tested with:

Guacamole: 1.6.0
OpenBao: v2.4.4
Protocol: RDP
Environment: Docker containers

Test scenario:

User "subba" logs into Guacamole
User connects to RDP connection configured with:
- Username: ${GUAC_USERNAME}
- Password: ${OPENBAO_SECRET}
Extension retrieves password from OpenBao at /v1/rdp-creds/data/subba
RDP connection succeeds with retrieved credentials

Result: ✅ All tests passed successfully

Compatibility

Guacamole Version: 1.6.x
Java Version: 8+
OpenBao Versions: Tested with v2.4.4, should work with v2.0.0+
Supported Protocols: All Guacamole protocols (RDP, VNC, SSH, etc.)

Security Considerations

Token Storage: OpenBao tokens are stored in guacamole.properties. Administrators should:
- Use read-only tokens with minimal permissions
- Restrict file permissions on guacamole.properties
- Rotate tokens regularly

TLS: Production deployments should use HTTPS:

openbao-server-url: https://openbao.example.com:8200

Network Security: OpenBao should only be accessible from Guacamole servers
Audit Logging: Enable OpenBao audit logging to track credential access

Documentation

README.md: Comprehensive documentation including:
- Overview and features
- Configuration guide
- Installation instructions
- Security best practices
- Troubleshooting guide
- Example deployment

Breaking Changes

None. This is a new extension module that does not modify any existing code.

Checklist

Code builds successfully
Apache license headers present on all files
Apache RAT check passes
README documentation provided
Follows existing code patterns (modeled after KSM extension)
Tested functionally with OpenBao server
JIRA issue created (pending)
Update GUACAMOLE-XXXX in commit message after JIRA issue creation

Questions for Reviewers

Should we add support for OpenBao namespaces in the configuration?
Should we add support for configurable KV version (v1/v2)?
Should connection groups be supported with group-level OpenBao configuration?
Should we add support for multiple OpenBao mount paths?

Future Enhancements

Potential future improvements (not in this PR):

Multiple Mount Paths: Support different OpenBao mount paths for different connection groups
Token Rotation: Automatic token renewal/rotation
AppRole Authentication: Support AppRole in addition to token-based auth
Connection Group Configuration: Allow OpenBao settings per connection group
Secret Caching: Optional caching to reduce API calls
Namespace Support: Support for OpenBao Enterprise namespaces

Related Work

This extension is inspired by and follows the same architectural patterns as:

Keeper Secrets Manager (KSM) vault extension (guacamole-vault-ksm)

Additional Notes

OpenBao project: https://openbao.org/
OpenBao GitHub: https://github.com/openbao/openbao

Ready for Review: This PR is ready for initial review. Will update JIRA issue number once created.

necouchman · 2026-01-25T20:00:15Z

@subbareddyalamur Please:

Update your commit messages to include GUACAMOLE-2196:
Make sure your commits have meaningful and unique messages, or squash them together.

subbareddyalamur · 2026-02-17T05:11:24Z

@subbareddyalamur Please:

Update your commit messages to include GUACAMOLE-2196:

Make sure your commits have meaningful and unique messages, or squash them together.

@necouchman Done.

corentin-soriano

Thank you for this contribution.
I've added a few questions to the code.

corentin-soriano · 2026-03-10T15:04:21Z

...ole-vault-openbao/src/main/java/org/apache/guacamole/vault/openbao/secret/OpenBaoClient.java

+            logger.warn("Password field not found in OpenBao response");
+            return null;
+
+        } catch (Exception e) {


Could we catch a more specific exception?

corentin-soriano · 2026-03-10T15:04:53Z

...lt-openbao/src/main/java/org/apache/guacamole/vault/openbao/secret/OpenBaoSecretService.java

+            } else {
+                logger.warn("Password not found in OpenBao for user: {}", username);
+            }
+        } catch (Exception e) {


Could we catch a more specific exception?

corentin-soriano · 2026-03-10T15:10:15Z

...ole-vault-openbao/src/main/java/org/apache/guacamole/vault/openbao/secret/OpenBaoClient.java

+
+        logger.info("Fetching secret from OpenBao: {}", fullUrl);
+
+        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {


Is there a specific reason to re-instantiate an HTTP client for each request?

corentin-soriano · 2026-03-10T15:15:48Z

...ole-vault-openbao/src/main/java/org/apache/guacamole/vault/openbao/secret/OpenBaoClient.java

+        String serverUrl = configService.getServerUrl();
+        String token = configService.getToken();
+        String mountPath = configService.getMountPath();
+        String kvVersion = configService.getKvVersion();


What will happen if the URL, path, or token is not defined or is empty?

subbareddyalamur force-pushed the feature/openbao-vault-extension branch from 24da733 to c0449db Compare December 30, 2025 09:30

subbareddyalamur changed the title ~~OpenBao Vault Integration Extension~~ GUACAMOLE-2196: OpenBao Vault Integration Extension Dec 31, 2025

GUACAMOLE-2196: Add OpenBao vault integration extension

ecca633

subbareddyalamur force-pushed the feature/openbao-vault-extension branch from c0449db to ecca633 Compare February 17, 2026 05:10

corentin-soriano reviewed Mar 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GUACAMOLE-2196: OpenBao Vault Integration Extension#1143

GUACAMOLE-2196: OpenBao Vault Integration Extension#1143
subbareddyalamur wants to merge 1 commit intoapache:mainfrom
subbareddyalamur:feature/openbao-vault-extension

subbareddyalamur commented Dec 30, 2025 •

edited by necouchman

Loading

Uh oh!

necouchman commented Jan 25, 2026

Uh oh!

subbareddyalamur commented Feb 17, 2026

Uh oh!

corentin-soriano left a comment

Uh oh!

corentin-soriano Mar 10, 2026

Uh oh!

corentin-soriano Mar 10, 2026

Uh oh!

corentin-soriano Mar 10, 2026

Uh oh!

corentin-soriano Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		logger.info("Fetching secret from OpenBao: {}", fullUrl);

		try (CloseableHttpClient httpClient = HttpClients.createDefault()) {

Conversation

subbareddyalamur commented Dec 30, 2025 • edited by necouchman Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request: OpenBao Vault Integration Extension

Summary

JIRA Issue

Motivation

Implementation Details

Architecture

Token System

Secret Path Mapping

Configuration

Files Added

Files Modified

Dependencies

Testing

Build Testing

Functional Testing

Compatibility

Security Considerations

Documentation

Breaking Changes

Checklist

Questions for Reviewers

Future Enhancements

Related Work

Additional Notes

Uh oh!

necouchman commented Jan 25, 2026

Uh oh!

subbareddyalamur commented Feb 17, 2026

Uh oh!

corentin-soriano left a comment

Choose a reason for hiding this comment

Uh oh!

corentin-soriano Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

corentin-soriano Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

corentin-soriano Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

corentin-soriano Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

subbareddyalamur commented Dec 30, 2025 •

edited by necouchman

Loading