- 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.
- 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.
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!
- **_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 `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.
- **_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.
- 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.
- 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.
- 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.
- 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 [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.
