https://github.com/andif888/workfromhome-with-inlets
HTML5 based remote desktop gateway using Apache Guacamole and inlets websocket reverse tunnel including AD authentication and 2-FA
https://github.com/andif888/workfromhome-with-inlets
activedirectory caddy docker guacamole homelab html5 inlet letsencrypt multifactor-authentication rdp remote-desktop remotedesktopgateway terraform vagrantfile websockets work-from-home
Last synced: 5 months ago
JSON representation
HTML5 based remote desktop gateway using Apache Guacamole and inlets websocket reverse tunnel including AD authentication and 2-FA
- Host: GitHub
- URL: https://github.com/andif888/workfromhome-with-inlets
- Owner: andif888
- Created: 2020-03-16T19:26:29.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-25T22:34:40.000Z (over 4 years ago)
- Last Synced: 2025-04-05T20:04:40.049Z (6 months ago)
- Topics: activedirectory, caddy, docker, guacamole, homelab, html5, inlet, letsencrypt, multifactor-authentication, rdp, remote-desktop, remotedesktopgateway, terraform, vagrantfile, websockets, work-from-home
- Language: Shell
- Homepage:
- Size: 726 KB
- Stars: 35
- Watchers: 2
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# WorkFromHome-with-inlets
*"Navigate in any webbrowser to [https://yourcompany.westeurope.cloudapp.azure.com](https://yourcompany.westeurope.cloudapp.azure.com) and logon with your corporate Active Directory account (including 2-FA) to access your Windows desktops"*
If you want your users to be able to access for example Windows PCs or Windows RDS, which are located on your corporate network from anywhere in the world using any HTML5 capable webbrowser, then this is right for.
If your are a homelab enthusiast and want your homelab to be accessible from any where from any device using HTML5, then this maybe worth to have a look.
This repo runs a bunch of docker containers on any Linux operating system to make this possible.
[inlets](https://github.com/inlets/inlets/) is used as a reverse tunneling solution using Websockets, which connects to a minimal cloud-hosted VM leveraging its public IP address and full qualified domain name.
[Apache Guacamole](https://guacamole.apache.org) is a clientless remote desktop gateway, which supports protocols like RDP, VNC and SSH. Because the Guacamole client is an HTML5 web application, use of your computers is not tied to any one device or location. As long as you have access to a web browser, you have access to your machines.
This repo automates the whole configuration and integration of inlets and Apache Guacamole. By setting a few mandatory environment variables, user authentication can be integrated into Active Directory using LDAP. Also 2-FA-Authentication is enabled using Google-Authenticator or any compatible TOTP implementation.
If you are not afraid of Linux, Docker and a bunch of Opensource Tools, then you are there **in a few minutes**.
## How to use this repo
### Pre-requesites
Ideally you have a vanilla or an existing Ubuntu server on your corporate network.
The repo contains a [Vagrantfile](Vagrantfile), so you also can easily use `vagrant up` to test the solution in a local VM using [Virtualbox](https://www.virtualbox.org/) and [Vagrant](https://www.vagrantup.com/downloads.html).
To spin up the Gacamole inlets exit-node in Azure you need a Azure Subcription.
**Pro-Tip**: Maybe you have spotted the [Vagrantfile](Vagrantfile). This means, for testing purpose you can use `vagrant up` to spin up an Ubuntu Linux immediately, if you are a little bit familiar with [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) and have already installed it somewhere. If you do so then you can already skip `Step 1`, because Vagrant has done it already for you.
### Step 1:
Run the [install.sh](install.sh) script as **root** on your Ubuntu server.
This script automatically installs docker, docker-compose, git, terraform, Azure CLI and inlets. It also clones this repo into the directoy `/srv/workfromhome-with-inlets` on your server.
```console
sudo -s
curl -sfL https://raw.githubusercontent.com/andif888/workfromhome-with-inlets/master/install.sh | sh -
```
### Step 2:
Spin up the Gacamole inlets exit-node in Azure.
For details please see [Guacamole inlets Exit-Node on Azure](inlets-exit-node) in the [inlets-exit-node](inlets-exit-node) subdirectory. These are very quick step, because the deployment is fully unattended.
### Step 3:
Edit the [.env](.env) file and customize at least the values of the mandatory environment variables with your preferred text editor. All mandatory an optional setting are documented inside the .env file.
```console
cd /srv/workfromhome-with-inlets
nano .env
```
### Step 4:
Start docker container using the [start.sh](start.sh) script as **root**.
```console
sudo -s
./start.sh
```
### Step 5:
Point your preferred webbrowser to the DNS host name, which you have configured as `FQDN_HOST_NAME` in your .env file.
Example: [https://yourcompany.westeurope.cloudapp.azure.com](https://yourcompany.westeurope.cloudapp.azure.com)
The default username is `guacadmin` and password is `guacadmin`.
After entering credentials your prompted to scan the QR-Code, with a compatible TOTP App on your mobile phone.
[**Google Authenticator**](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en) works good.
After scanning the QR-Code and entering the first token your are successfully logged into Apache Guacamole.
**Please change the default password immediatelly**.
## Configure your first Windows Machine accessible through Guacamole, which has RDP enabled
Click `Settings` in the top right menu.
Click `Connections` and the `New Connection`
Enter any Name. It's only a display name.
Select `RDP` as Protocol.
Scroll down to `Parameters` and enter the RDP connection details.
Optionally fine-tune for latest RDP-Protocol version.
And finally hit `Save` at the bottom of the page.
Go back to `Home`
And start the connection
and have fun! HTML5 based RDP into your Windows machine.
General Help on [How to configure connections in Guacamole](https://guacamole.apache.org/doc/gug/configuring-guacamole.html#connection-configuration)
## Using Active Directory Authentication and enable 2-FA
Make sure you have entered correct mandatory values regarding LDAP authentication into the [.env](.env) file in **Step 2** during initial configuration.
NOTE: We don't use the AD Schema preparation, documented at https://guacamole.apache.org/doc/gug/ldap-auth.html, because we don't like to do changes in our Acitive Directory Schema.
Please read the documention to understand the mapping between database users und AD users.
### Step 1: Create an initial admin user in Guacamole which maps to an AD user
Create a new user in Guacamole and set its username to the username of an existing AD user, which is located in your AD-Tree below the OU (Organizational Unit), which you have configured in `LDAP_USER_BASE_DN` environment variable.
If you haven't changed `LDAP_USERNAME_ATTRIBUTE` then the mapped username of your AD user is the `userPrincipalName` AD-Attribute.
Your can set any password. It **must not** match your AD user's password.
Make sure you check all permissions and hit `Save` at the bottom of the page.
### Step 2: Logon with your newly mapped AD user account
Now you should be able to logon with the AD user account.
Because of we have previously set the permission `Change own password`, we are prompted with the already familiar 2-FA screen. Again use your Google Authenticator to scan the QR-Code.
If you now navigate to `Settings -> Users` you should get already a list of your AD user accounts, which means, your LDAP integration and authentication is working perfect.
### Step 3: Enable 2-FA for and AD user
If you want to enable 2-FA for AD user then you minimum need to assign the permission `Change own password` on his user account.
Don't be afraid of the setting, it doesn't mean a user can change its AD password using this web GUI. It's only about changing its personal credential information in Guacamole's MySQL database, which is necessary to write down the TOTP secret key.
## The best thing at the Bottom: Pass-Through credentials to a connection
You have already learned to create your first connection to a Windows machine further above.
There is a nice feature which allows you to pass-through your Guacamole logon credentials to a connection.
You remember when you have scrolled down to `Parameters` and entered the RDP connection details?
To enable Pass-Through credentials you do not hardcode username and password. You only need to enter **parameter tokens**.
For the username you enter `${GUAC_USERNAME}`
For the password you enter `${GUAC_PASSWORD}`
If you use the `userPrincipalName` for your AD users all is perfect and no need to worry about the Domain field ;-)
To learn more about [parameter tokens](https://guacamole.apache.org/doc/gug/configuring-guacamole.html#connection-configuration)
# Troubleshooting and Logs
Viewing inlets Logs
```console
cd /srv/workfromhome-with-inlets
docker logs inlets-client
```
Viewing Guacamole Logs
```console
cd /srv/workfromhome-with-inlets
docker-compose logs -f --tail=1000 guacamole
```
Viewing all Logs
```console
cd /srv/workfromhome-with-inlets
docker-compose logs -f --tail=1000
```
# References and documentation
[Guacamole User Guide](https://guacamole.apache.org/doc/gug/users-guide.html)
[inlets Documentation](https://github.com/inlets/inlets)
# Disclaimer
Use at your own risk.
This is not a solution which scales for thousands of users.
Depending on your internet connection this is perfectly fine for 50+ users with a single Ubuntu machine.