GUACAMOLE-2196: OpenBao Vault Integration Extension

[subbareddyalamur]

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:

1. Automatic Credential Retrieval: Users no longer need to manually manage or update connection passwords in Guacamole
2. Centralized Secrets Management: Credentials are stored and managed in OpenBao, not in Guacamole's database
3. Enhanced Security: Passwords are retrieved on-demand and never stored in Guacamole
4. 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:

1. OpenBaoAuthenticationProvider: Main extension entry point extending VaultAuthenticationProvider
2. OpenBaoSecretService: Implements VaultSecretService for token resolution and secret retrieval
3. OpenBaoClient: HTTP client for communicating with OpenBao REST API using Apache HttpClient 5
4. OpenBaoConfigurationService: Reads configuration from guacamole.properties
5. OpenBaoDirectoryService: Pass-through implementation (no directory management needed)
6. 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:

1. User "subba" logs into Guacamole
2. User connects to RDP connection configured with:
   • Username: ${GUAC_USERNAME}
   • Password: ${OPENBAO_SECRET}
3. Extension retrieves password from OpenBao at /v1/rdp-creds/data/subba
4. 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

1. 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

2. TLS: Production deployments should use HTTPS:

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

3. Network Security: OpenBao should only be accessible from Guacamole servers

4. 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

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

Future Enhancements

Potential future improvements (not in this PR):

1. Multiple Mount Paths: Support different OpenBao mount paths for different connection groups
2. Token Rotation: Automatic token renewal/rotation
3. AppRole Authentication: Support AppRole in addition to token-based auth
4. Connection Group Configuration: Allow OpenBao settings per connection group
5. Secret Caching: Optional caching to reduce API calls
6. 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.