mike-jumper commented on code in PR #195: URL: https://github.com/apache/guacamole-manual/pull/195#discussion_r1105024120
########## src/vault.md: ########## @@ -0,0 +1,373 @@ +Retrieving secrets from a vault +=============================== + +Guacamole supports reading secrets such as connection-specific passwords from a +key vault, automatically injecting those secrets into connection configurations +using [parameter tokens](parameter-tokens) or Guacamole configuration +properties via an additional, vault-specific configuration file analogous to +`guacamole.properties`. This support is intended with multiple vault providers +in mind and currently supports [Keeper Secrets Manager (KSM)](https://www.keepersecurity.com/secrets-manager.html). + +:::{important} +This chapter involves modifying the contents of `GUACAMOLE_HOME` - the +Guacamole configuration directory. If you are unsure where `GUACAMOLE_HOME` is +located on your system, please consult [](configuring-guacamole) before +proceeding. +::: + +(vault-downloading)= + +Downloading the vault extension +------------------------------- + +The vault extension is available separately from the main `guacamole.war`. The +link for this and all other officially-supported and compatible extensions for +a particular version of Guacamole are provided on the release notes for that +version. You can find the release notes for current versions of Guacamole here: +<http://guacamole.apache.org/releases/>. + +The vault extension is packaged as a `.tar.gz` file containing directories +specific to vault implementations (currently only `ksm/` for the KSM +implementation). Each vault-specific directory contains a `.jar` file (the +actual Guacamole extension). The Guacamole extension `.jar` will ultimately +need to be placed within `GUACAMOLE_HOME/extensions`. + +(installing-vault-support)= + +Installing key vault support +---------------------------- + +Guacamole extensions are self-contained `.jar` files which are located within +the `GUACAMOLE_HOME/extensions` directory. To install the KSM vault extension, +you must: + +1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already + exist. + +2. Copy `ksm/guacamole-vault-ksm-1.5.0.jar` within `GUACAMOLE_HOME/extensions`. + +3. Configure Guacamole to use KSM to retrieve secrets, as described below. + +:::{important} +You will need to restart Guacamole by restarting your servlet container in +order to complete the installation. Doing this will disconnect all active +users, so be sure that it is safe to do so prior to attempting installation. If +you do not configure the vault support properly, Guacamole will not start up +again until the configuration is fixed. +::: + +(adding-guac-to-ksm)= + +### Adding Guacamole to KSM + +Allowing an application like Guacamole to access secrets via KSM involves +creating an application in KSM. A KSM application is simply a means of +assigning permissions, narrowing exactly which secrets the application in +question should be able to access. + +1. Log into your vault via the Keeper Security website and create at least one + shared folder to house any secrets that should be made available to Apache + Guacamole. These folders will be used when registering Apache Guacamole with + KSM and functions to define exactly which secrets the application may access. + **Secrets that are not within these shared folders will not be accessible by + Guacamole.** + + The option for creating a shared folder is within a submenu that appears + when you click on "Create New": + +  + + No special options need to be selected for the shared folder except for + providing a reasonable name for the folder: + +  + +2. Navigate to KSM by selecting the "Secrets Manager" tab in the navigation + sidebar on the left side of the screen: + +  + +3. Click "Create Application" on the right ride of the toolbar near the top of + the screen: + +  + + The dialog that appears will prompt you to provide a name for the + application that will access the vault, as well as the shared folder(s) that + this application will have access to. Enter a reasonable name for the + application, such as "Apache Guacamole", and select the shared folder(s) you + created for Guacamole to access: + +  + + Guacamole only needs read-only access permissions to secrets, which should + already be selected by default. + + :::{warning} + You should only check the "Lock external WAN IP" box if your Guacamole + server has a static IP _and_ you will be using the KSM CLI tool directly on + that server. **If you will be running the KSM CLI tool on a separate machine + with a different public IP address, you must not check this box.** + ::: + +4. Once satisfied with the application name and parameters, click "Generate + Token" to generate a one-time token: + +  + +5. Copy the provided one-time token using [the KSM CLI tool](https://docs.keeper.io/secrets-manager/secrets-manager/secrets-manager-command-line-interface/init-command) + to obtain the base64-encoded configuration that must be provided to + Guacamole with [the `ksm-config` property](guac-vault-config). **This token + can only be used once, but the base64 configuration can be used indefinitely + unless manually revoked within KSM:** + + ```console + $ ./ksm init default US:_-L2NIxWdMatbyYwBnYROLlJVjeg4BzO3xZWoiDkh4U + + ewogICJjbGllbnRJZCI6ICJTR1ZzYkc4Z2RHaGxjbVVoSUZSb1pYTmxJSEJ5YjNCbGNuUnBaWE1n + YUdGMlpTQmlaV1Z1SUcxaGJuVmhiR3g1SUhKbFpHRmpkR1ZrTGlCWGFIay9Qdz09IiwKICAicHJp + dmF0ZUtleSI6ICJWRzhnWlc1emRYSmxJSFJvWVhRZ1lXTjBkV0ZzSUhObGJuTnBkR2wyWlNCMllX + eDFaWE1nWVhKbElHNXZkQ0JsZUhCdmMyVmtJSFpwWVNCdmRYSWdiV0Z1ZFdGc0xpQlVhR1Y1SUcx + aGVTQnViM1FnUVV4TUlHSmxJSE5sYm5OcGRHbDJaU0IyWVd4MVpYTXNJR0oxZENCaGRDQnNaV0Z6 + ZENCdmJtVWdjMlZsYlhNZ2RHOGdZbVV1IiwKICAiYXBwS2V5IjogIlYyVnNZMjl0WlNFZ1JXNXFi + M2tnUVhCaFkyaGxJRWQxWVdOaGJXOXNaU0U9IiwKICAiaG9zdG5hbWUiOiAia2VlcGVyc2VjdXJp + dHkuY29tIiwKICAic2VydmVyUHVibGljS2V5SWQiOiAiMTAiCn0K + $ + ``` + +(guac-vault-config)= + +### Configuring Guacamole for KSM + +Guacamole requires only a single configuration property to configure secret Review Comment: In this case (the `ksm-config` property), only a base64-encoded configuration can be accepted. The changes that allow one-time tokens to be provided for individual users or connection groups do need to be documented, but are not part of 1.5.0 and do not affect the `ksm-config` property, which must always be a base64-encoded configuration. -- 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]
