Update README.md

This commit is contained in:
Itiligent 2023-09-07 22:54:29 +10:00 committed by itiligent
parent 5f3756dcf8
commit ba7fab3e12
2 changed files with 97 additions and 109 deletions

View file

@ -1,19 +1,20 @@
# Integrating Guacamole with Active Directory
## **1. Ensure two way LDAP traffic is available to the Guacamole application server**
## :arrows_clockwise: **Step 1: Ensure two-way LDAP traffic is available to the Guacamole application server**
- If Guacamole is operating in a separate network to that of your Active Directory Servers, allow TCP 389 between all Guacamole application servers and all Active Directory Domain Controllers nominated in the config script settings below.
- If Guacamole is operating in a separate network from your Active Directory Servers, allow TCP 389 between all Guacamole application servers and all Active Directory Domain Controllers nominated in the config script settings below.
## **2. Establish the required accounts to bind with Active Directory**
## :key: **Step 2: Establish the required accounts to bind with Active Directory**
- An account with only **Domain Users** rights is sufficient for Guacamole to read and bind with Active Directory.
- a. In the Guacamole application, create a new Guacamole account with full admin rights to the Guacamole application e.g. `guacbind-ad` and assign it an appropriately strong password. (Then login with this new account and disable the default guacadmin account)
- b. Create a new Active Directory domain account of EXACTLY THE SAME NAME as the new full admin account named above, only this time assign a DIFFERENT strong password to that which was used above.
- a. In the Guacamole application, create a new Guacamole account with full admin rights to the Guacamole application, e.g., `guacbind-ad`, and assign it an appropriately strong password. (Then log in with this new account and disable the default guacadmin account)
- b. Create a new Active Directory domain account with EXACTLY THE SAME NAME as the new full admin account named above, only this time assign a DIFFERENT strong password than what was used above.
## **3. Edit the provided configuration script to reflect your specific Active Directory environment**
## :pencil: **Step 3: Edit the provided configuration script to reflect your specific Active Directory environment**
Below is the EXACT format to follow in editing the `$USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh` script. Be careful not to introduce new lines, spaces at ends of lines or carriage returns as anything outside of this format will cause the LDAP auth extension to fail. You have been warned!
Below is the EXACT format to follow in editing the `$USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh` script. Be careful not to introduce new lines, spaces at the ends of lines, or carriage returns, as anything outside of this format will cause the LDAP auth extension to fail. You have been warned!
```
ldap-hostname: dc1.yourdomain.com dc2.yourdomain.com dc3.yourdomain.com
@ -29,7 +30,8 @@ ldap-max-search-results:200
mysql-auto-create-accounts: true
```
**Edit only the following values from the above example to suit your environment, then save the script**
**Edit only the following values from the above example to suit your environment, then save the script:**
```
ldap-hostname:
ldap-search-bind-dn:
@ -39,35 +41,38 @@ ldap-user-base-dn:
mysql-auto-create-accounts: true
ldap-max-search-results:200
```
- **_Important note on `ldap-user-base-dn:`_** _This value sets a position in the directory as a relative root to search within. All Guacamole users to be authenticated by Active Directory must be placed in a lower position within the directory tree to this value. This line can be added multiple times to more efficiently search across multiple branches of a directory tree._
- **_Important note on `ldap-max-search-results:`_** _Yes, there is no space before the :200 value. In larger environments managing the directory efficiently requires we don't query every object in the tree for every user lookup. You may need to adjust this number depending on the number of objects in your tree._
- **_Important note on `ldap-user-base-dn:`_** This value sets a position in the directory as a relative root to search within. All Guacamole users to be authenticated by Active Directory must be placed in a lower position within the directory tree than this value. This line can be added multiple times to more efficiently search across multiple branches of a directory tree.
- **_Important note on `mysql-auto-create-accounts:`_** _This line is optional and can be deleted. This line ensures that all Active Directory user accounts will have a matching user account created in the Guacamole db at first logon. Local Guacamole accounts are NOT necessarily needed for access to Guacamole connections - these are only necessary when deploying MFA or you want to assign other settings specific to individual users. Domain users can be provisioned access to Guacamole sessions connections without creating local users in the Guacamole db. For many use cases, manually creating a small number of Guacamole user accounts to their matching domain accounts may be more preferable than all users inheriting access to establish a local account in the Guacamole db. See below for manual account setup._
- **_Important note on `ldap-max-search-results:`_** Yes, there is no space before the `:200` value. In larger environments managing the directory efficiently requires that we don't query every object in the tree for every user lookup. You may need to adjust this number depending on the number of objects in your tree.
## **4. Run the (now customised) LDAP configuration script**
- **_Important note on `mysql-auto-create-accounts:`_** This line is optional and can be deleted. This line ensures that all Active Directory user accounts will have a matching user account created in the Guacamole db at first logon. Local Guacamole accounts are NOT necessarily needed for access to Guacamole connections - these are only necessary when deploying MFA or you want to assign other settings specific to individual users. Domain users can be provisioned access to Guacamole sessions connections without creating local users in the Guacamole db. For many use cases, manually creating a small number of Guacamole user accounts to match their domain accounts may be more preferable than all users inheriting access to establish a local account in the Guacamole db. See below for manual account setup.
`sudo $USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh`
## :computer: **Step 4: Run the (now customised) LDAP configuration script**
## **5. Logging on to Guacamole with the new guacbind-ad account**
```shell
sudo $USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh
```
## :door: **Step 5: Logging on to Guacamole with the new guacbind-ad account**
- When logging in to Guacamole as the new Active Directory account and password created above, that domain user now passed through to Guacamole as both a Guacamole admin and a Domain User. If all is working correctly, all the users located below the directory tree position set in **ldap-user-base-dn** will be listed under **Settings | Users** of the Guacamole management console.
## **6. Manually creating and configuring new Guacamole users for Active Directory authentication**
## :busts_in_silhouette: **Step 6: Manually creating and configuring new Guacamole users for Active Directory authentication**
- If not using the **mysql-auto-create-accounts** directive, manually re-create the exact user account names in Guacamole as those in the directory you wish to give Guacamole access. **DO NOT configure a Guacamole password for any users that will be exclusively authenticating via Active directory**. Guacamole local user accounts without a password are first given an MFA challenge by the local Guacamole application (only if MFA is configured for that user) and then will be brokered to Active Directory for their authentication challenge. Guacamole local user accounts that are given passwords in Guacamole will always refer to the local db for authentication, never Active Directory. This design allows for a matrix of local, domain, MFA & non MFA access use cases to be deployed.
- If not using the **mysql-auto-create-accounts** directive, manually re-create the exact user account names in Guacamole as those in the directory you wish to give Guacamole access. **DO NOT configure a Guacamole password for any users that will be exclusively authenticating via Active directory**. Guacamole local user accounts without a password are first given an MFA challenge by the local Guacamole application (only if MFA is configured for that user) and then will be brokered to Active Directory for their authentication challenge. Guacamole local user accounts that are given passwords in Guacamole will always refer to the local db for authentication, never Active Directory. This design allows for a matrix of local, domain, MFA & non-MFA access use cases to be deployed.
## **7. Logging on using either the local vs the domain guacbind-ad account**
## :key: **Step 7: Logging on using either the local vs. the domain guacbind-ad account**
- As described above, logging on with the Guacamole admin user password will authenticate with the local Guacamole admin account, conversely if the Guacamole admin domain account password is given, the domain account is authenticated via Active Directory and then passed through as authorised to administer Guacamole. It may sometimes be necessary to log on with the local Guacamole admin account to manage some application functions, but be aware that when doing so you will not be able to view and search the user list from Active Directory. Only when logged on with the domain version of the Guacamole admin account can domain user permissions to various Guacamole sessions and objects be delegated and managed.
- As described above, logging on with the Guacamole admin user password will authenticate with the local Guacamole admin account, conversely if the Guacamole admin domain account password is given, the domain account is authenticated via Active Directory and then passed through as authorized to administer Guacamole. It may sometimes be necessary to log on with the local Guacamole admin account to manage some application functions, but be aware that when doing so you will not be able to view and search the user list from Active Directory. Only when logged on with the domain version of the Guacamole admin account can domain user permissions to various Guacamole sessions and objects be delegated and managed.
## **8. Creating a quasi Single Sign On user experience for Windows RDP access**
## :gear: **Step 8: Creating a quasi Single Sign-On user experience for Windows RDP access**
- Create a Global Security domain group (e.g. Guac_Users) and populate it with selected domain users as required.
- Create a Global Security domain group (e.g., Guac_Users) and populate it with selected domain users as required.
- Now add this new security group to the built-in “Remote Desktop Users” domain group.
- Next, for each connection profile you wish to create the SSO experience and behaviour, _parameter_ _tokens_ must be used in place of hard coded usernames and password values as follows...
- Next, for each connection profile you wish to create the SSO experience and behavior, _parameter_ _tokens_ must be used in place of hard-coded usernames and password values as follows...
- Add the parameter token `${GUAC_USERNAME}` to the Username field for each connection profile
- Add the parameter token `${GUAC_PASSWORD}` to the Password field for each connection profile
- If the user has been given directory rights to the Guacamole session object, Guacamole will first authenticate the user to the Guacamole application (via a brokered Active Directory challenge) and then seamlessly pass the user's same domain credentials through to the Guacamole remote desktop session, thus avoiding any further remote desktop authentication prompts.
- For more info on other dynamic connection settings see https://guacamole.apache.org/doc/gug/configuring-guacamole.html#parameter-tokens
- For full SSO, the SAML authentication extension must be used. As the Guacamole SAML extension requires a very bespoke approach to configuring login providers and login behaviours, the SAML authentication feature is beyond the scope of this project. If your organisation already uses SAML within your infrastructure then you likely already know what to do to implement.
- For more info on other dynamic connection settings see [Guacamole Documentation](https://guacamole.apache.org/doc/gug/configuring-guacamole.html#parameter-tokens)
- For full SSO, the SAML authentication extension must be used. As the Guacamole SAML extension requires a very bespoke approach to configuring login providers and login behaviors, the SAML authentication feature is beyond the scope of this project. If your organization already uses SAML within your infrastructure then you likely already know what to do to implement.

155
README.md
View file

@ -1,111 +1,94 @@
# **Guacamole 1.5.3 VDI/Jump Server Appliance Build Script**
# Guacamole 1.5.3 VDI/Jump Server Appliance Build Script
A menu based source build & install script for Guacamole 1.5.3 with optional TLS reverse proxy, AD integration, multi-factor authentication, Quick Connect & History Recording Storage features, dark mode support, auto database backup, O365 email alert integration and further security hardening.
<img src="https://github.githubassets.com/images/icons/emoji/sparkles.png" width="35"> This script makes setting up Guacamole 1.5.3 a breeze, with added features like TLS reverse proxy, AD integration, multi-factor authentication, Quick Connect, History Recording Storage, dark mode support, auto database backup, O365 email alerts, and enhanced security options.
### **Automatic build, install & config script**
## Automatic Installation
To build the Guacamole appliance, paste the below link into a terminal and follow prompts **(do not run as sudo)**:
<img src="https://github.githubassets.com/images/icons/emoji/rocket.png" width="35"> To start building the Guacamole appliance, paste the below link into a terminal and follow the prompts **(no need for sudo, but the user must be a member of the sudo group)**:
```
```shell
wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.sh && chmod +x 1-setup.sh && ./1-setup.sh
```
## **Prerequisites**
### NOTE: DEBIAN 12 & TOMCAT 10 NOT CURRENTLY COMPATIBLE - SEE ISSUE #10
## Prerequisites
- **Ubuntu 18.04 - 22.x / Debian 11 & 10 / Raspbian Buster or Bullseye**
- *(if using OS vendor cloud images - you must use **stable releases of the above OS variants.** Daily cloud image builds are akin to rolling releases and may contain as yet unsupported updates that break Guacamole!)*
- Minimum 8GB RAM and 40GB HDD
- Public or private DNS entries that match the default route interface IP address (required for TLS)
- Incoming access on TCP ports 22, 80, and 443
- Do not run as root, however the user executing the installer script must be a **member of the sudo group**
<img src="https://github.githubassets.com/images/icons/emoji/lock.png" width="35"> **Before diving in, make sure you have:**
## **Installer Menu Flow**
- A compatible OS: Ubuntu 18.04 - 22.x, Debian 11 & 10, or Raspbian Buster/Bullseye (stick to stable releases for cloud images).
- Minimum 8GB RAM and 40GB HDD.
- DNS entries matching your default route interface IP (essential for TLS).
- Open TCP ports: 22, 80, and 443.
### **1. Confirm the system hostname & local dns domain suffix**
## Installation Menu
### **2. Select a MySQL instance type and security baseline**
<img src="https://github.githubassets.com/images/icons/emoji/wrench.png" width="35"> **This script guides you through the installation process in the following steps:**
- Install a new local MySQL instance, or choose an existing/remote MySQL instance?
- *Optionally add **mysql_secure_installation** settings if a local instance*
1. Confirm system hostname and local DNS domain suffix.
2. Choose a MySQL instance type and set security preferences.
3. Pick an authentication extension (DUO, TOTP, LDAP, or none).
4. Select optional console features: Quick Connect and History Recorded Storage.
5. Decide on the Guacamole front end: Nginx reverse proxy (http or https) or keep the native Guacamole interface
### **3. Pick an authentication extension**
**For the more security minded, there's several post-install hardening options available:**
- DUO, TOTP, LDAP or none?
- `add-fail2ban.sh`: Adds a lockdown policy for Guacamole to guard against brute force attacks.
- `add-tls-guac-daemon.sh`: Wraps internal server daemon to guac application traffic in TLS.
- `add-auth-ldap.sh`: A template script for Active Directory integration.
- `add-smtp-relay-o365.sh`: A template script for email alerts via MSO65 (BYO app password).
### **4. Choose optional extra console features**
- Install Quick Connect feature? [y/n] *(allow unauthenticated add-hoc connections)*
- Install History Recorded Storage? [y/n] *(allocates storage & enables recorded session replay from console)*
## Active Directory Integration
### **5. Choose the Guacamole front end**
<img src="https://github.githubassets.com/images/icons/emoji/key.png" width="35"> **Need help with Active Directory authentication?** Check [here](https://github.com/itiligent/Guacamole-Install/blob/main/ACTIVE-DIRECTORY-HOW-TO.md).
- Install Nginx reverse Proxy? [y/n] *(no keeps the native front end)*
## Customise and Brand Your Guacamole Theme
<img src="https://github.githubassets.com/images/icons/emoji/art.png" width="35"> **Want to give Guacamole your personal touch? Follow the theme and branding instructions** [here](https://github.com/itiligent/Guacamole-Install/tree/main/custom-theme-builder).
## Installation Notes
<img src="https://github.githubassets.com/images/icons/emoji/unicode/2699.png" width="35">
1. Paste and run the wget autorun link in your home directory.
2. Exit `1-setup.sh` at the first prompt. (At this point the scripts are downloaded only.)
3. Customise the huge number of installation variables available in `1-setup.sh` as required. (Certain combinations of edits will produce a fully unattended install.)
4. **Caution: If editing `1-setup.sh`, be aware that running the autorun link again re-downloads and overwrites all changes. You must run setup locally after editing.** (Also be sure to comment out the download links in the setup script to any other downloaded scripts that you may have edited. There should be little need to edit outside of the setup script's options.)
5. The **upgrade-guac.sh, add-tls-guac-daemon.sh, refresh-tls-self-signed.sh & backup-guac.sh** scripts are automatically adjusted at installation to match your chosen installation settings. These can be run after install without any modification.
6. If the self-signed TLS proxy option is selected, browser client TLS certificates will be automatically created and saved to `$DOWNLOAD_DIR/guac-setup`.
7. Nginx is automatically configured to use TLS 1.2 or above (so really old browser versions may not work.)
8. A daily MySQL backup job will be automatically configured by the installer.
9. **Security info:** The Quick Connect and History Recorded Storage options bring a few security implications; so be aware of potential risks in your particular environment.
- Install Nginx reverse proxy with a self-signed TLS certificate? [y/n]
- *Nginx is configured with a self signed TLS certificate and http redirect*
- *Windows & Linux self signed client browser certificates generated*
## Upgrading Guacamole
- Install Nginx reverse proxy with a Let's Encrypt certificate? [y/n]
- *Nginx configured with a new LetsEncrypt certificate and http redirect*
- *Ongoing certbot certificate renewals scheduled*
<img src="https://github.githubassets.com/images/icons/emoji/globe_with_meridians.png" width="35"> To upgrade Guacamole, edit `upgrade-guac.sh` to relfect the latest available versions of Guacamole and MySQL connector/J before running it. This script will also automatically update the DUO, LDAP, TOTP, Quick Connect & History Recorded Storage extension if they are present.
## **Post install hardening options**
## Enterprise Scale Out & High Availability
The installer additionally downloads the following manual configuration scripts:
- `add-fail2ban.sh` - Adds a baseline fail2ban lockdown policy to Guacamole (& whitelists the local subnet)
- `add-tls-guac-daemon.sh` - Adds a TLS wrapper to internal traffic between the Guacamole application and guacd server daemon
- `add-auth-ldap.sh` - A template script for integrating Guacamole with Active Directory
- `add-smtp-relay-o365.sh` - A template script for email alerts via MSO65 (BYO app password)
<img src="https://github.githubassets.com/images/icons/emoji/unicode/1f454.png" width="35"> For Enterprise deployments, did you know that Guacamole can be run in a load balanced farm? To achieve this, the database, application and front end components are usually **split into a 3 layers.** (VLANs & firewalls between the layers helps with security too.)
- **For the DATABASE layer:** Find the included `install-mysql-backend-only.sh` to install just a standalone instance of the Guacamole MySQL database.
- **For the APPLICATION layer:** Simply use the main setup script on as many application servers as you like, just make sure to say no to both the Install MYSQL locally option and any Nginx front end options.
- **For the Front end**: You'll need to roll your own load balancer. **HA Proxy** provides superior session affinity under load balanced conditions when compared to Open source Nginx (Nginx Plus gives you all the good stuff.) There's too many possible ways to achieve this, and the target audience for this sort of setup likely knows how to run with whats already provided.
## **Active Directory integration**
## Auto Download Manifest
See Active Directory authentication instructions [here](https://github.com/itiligent/Guacamole-Install/blob/main/ACTIVE-DIRECTORY-HOW-TO.md)
<img src="https://github.githubassets.com/images/icons/emoji/package.png" width="35"> The autorun link downloads these repo files into `$DOWNLOAD_DIR/guac-setup`:
## **Customise and brand your Guacamole theme**
- `1-setup.sh`: The installation script.
- `2-install-guacamole.sh`: Guacamole main installation script.
- `3-install-nginx.sh`: Installs Nginx for reverse proxy (optional).
- `4a-install-tls-self-signed-nginx.sh`: Configures self-signed TLS for Nginx (optional).
- `4b-install-tls-letsencrypt-nginx.sh`: Installs Let's Encrypt for Nginx (optional).
- `add-auth-duo.sh`: Adds Duo MFA extension (optional).
- `add-auth-ldap.sh`: Adds Active Directory extension (optional).
- `add-auth-totp.sh`: Adds TOTP MFA extension (optional).
- `add-xtra-quickconnect.sh`: Adds Quick Connect console feature (optional).
- `add-xtra-histrecstore.sh`: Adds History Recorded Storage feature (optional).
- `add-smtp-relay-o365.sh`: Sets up SMTP auth relay with O365 for backup messages, monitoring & alerts (BYO app password).
- `add-tls-guac-daemon.sh`: Adds TLS wrapper for guacd server daemon (optional).
- `add-fail2ban.sh`: Adds a fail2ban policy for brute force protection.
- `backup-guacamole.sh`: A MySQL Guacamole backup script.
- `upgrade-guac.sh`: Upgrades Guacamole and MySQL connector.
- `refresh-tls-self-signed`: Generates and installs updated TLS certificates for Nginx.
- `branding.jar`: An example template for customising Guacamole's theme. Delete to keep the default UI.
See theme and branding instructions [here](https://github.com/itiligent/Guacamole-Install/tree/main/custom-theme-builder)
## **Installation notes**
**The installer can be run interactively, or for a customised/unattended setup:**
1. From a terminal session, change to your home directory then paste and run the above wget autorun link.
2. Exit the `1-setup.sh` script at the first prompt. (At this point only the scripts have downloaded).
3. Customise the many installation variables in the "Silent setup options" section of `1-setup.sh` as appropriate.
- *Script variables with a given value (e.g. `VARIABLE="value"`) will not prompt during the interactive setup.*
- *With the right combination of custom script variables, it is possible to deploy Guacamole appliance(s) with zero touch in only minutes.*
4. **Beware: If any settings in `1-setup.sh` are edited, you must now run this modified script locally. If you run the wget autorun link again you will re-download the scripts package and overwrite all your changes!**
- *If any other downloaded scripts are edited before install (not recommended), **you must also comment out each script's corresponding wget download link in `1-setup.sh`** to prevent re-download and overwrite when re-running setup.*
**General installation info:**
- The`upgrade-guac.sh`, `add-tls-guac-daemon.sh` & `backup-guac.sh` scripts are automatically adjusted at installation to match current installation settings. These can be run after install without any modification.
- If the self signed TLS proxy option is selected, client TLS certificates will be saved to `$DOWNLOAD_DIR/guac-setup`.
- Nginx is configured to only support TLS 1.2 or above, really old browser versions may not work.
- **There are security implications with the optional Quick Connect and History Recorded Storage features.**
- **Quick connect** allows for add-hoc unauthenticated connections. Whilst users must still authenticate directly with the endpoint, all other controls such as file sharing restrictions can be bypassed as add-hoc connections allow the user full access to all connection parameters. Also, add-hoc connections are not recorded or logged.
- **History Recorded Storage** creates a locked down location for recorded session storage, however potentially sensitive recorded session data may require additional considerations beyond just Guacamole console & local filesystem access controls. Risk mitigations across the full storage and data lifecylce may also be a requirement.
## **Upgrading Guacamole**
To upgrade Guacamole, edit `upgrade-guac.sh` to reflect the desired `NEW_GUAC_VERSION` and `NEW_MYSQLJCON` values prior to running. The upgrade script will automatically update any pre-existing extensions already present (duo, ldap, totp, quick-connect or history-recored-storage) to the new Guacamole version.
## **Download manifest**
The autorun link above downloads the following items into the `$DOWNLOAD_DIR/guac-setup` directory:
- `1-setup.sh`: The parent install script itself (saved to the current directory)
- `2-install-guacamole.sh`: Guacamole installation script (based on [MysticRyuujin/guac-install](https://github.com/MysticRyuujin/guac-install))
- `3-install-nginx.sh`: Installs Nginx & auto-configures a front-end reverse proxy for Guacamole (optional)
- `4a-install-tls-self-signed-nginx.sh`: Configures self-signed TLS certificate for Nginx proxy (optional)
- `4b-install-tls-letsencrypt-nginx.sh`: Installs & configures Let's Encrypt for Nginx proxy (optional)
- `add-auth-duo.sh`: Adds the Duo MFA extension if not selected during install (optional)
- `add-auth-ldap.sh`: Adds the Active Directory extension and setup template if not selected at install (optional)
- `add-auth-totp.sh`: Adds the TOTP MFA extension if not selected at install (optional)
- `add-xtra-quickconnect.sh` Adds the Quick Connect console feature if not selected at install (optional)
- `add-xtra-histrecstore.sh`: Adds History Recorded Storage console features if not selected at install. (optional)
- `add-smtp-relay-o365.sh`: Sets up an SMTP auth relay with O365 for monitoring & alerts (BYO app password)
- `add-tls-guac-daemon.sh`: A hardening script to add a TLS wrapper between the guacd server daemon and Guacamole application traffic (optional, consider extra performance impact mitigations)
- `add-fail2ban.sh`: A hardening script to add a fail2ban policy (with local subnet override) to secure Guacamole against external brute force attacks
- `backup-guacamole.sh`: A simple MySQL Guacamole backup script
- `upgrade-guac.sh` Upgrades the currently installed versions of Guacamole and MySQL connector.
- `refresh-tls-self-signed` Creates and installs updated TLS certificates into Nginx. (Can be configured to generate certs for any other application).
- `branding.jar`: An example template for a custom (dark mode) Guacamole theme. Delete this file to keep the default Guacamole UI. This extension's source is also included for easier study and customisation.
Happy Guacamole-ing! 😄🥑