subbareddyalamur opened a new pull request, #1143: URL: https://github.com/apache/guacamole-client/pull/1143
# 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/) ## 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: ```json { "data": { "data": { "username": "john", "password": "SecurePassword123" } } } ``` ### Configuration The extension requires minimal configuration in `guacamole.properties`: ```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: ```bash 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: ```properties 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 - [x] Code builds successfully - [x] Apache license headers present on all files - [x] Apache RAT check passes - [x] README documentation provided - [x] Follows existing code patterns (modeled after KSM extension) - [x] 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. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
