Apache Guacamole: Single Sign-On integration using OpenID Connect

6 min readMar 26, 2023

Remote access solutions are essential for many businesses today, enabling employees to work from anywhere and collaborate seamlessly across different locations. However, managing multiple remote access tools and passwords can quickly become a headache for IT administrators and end-users alike. Single Sign-On (SSO) is a popular solution that addresses this issue by allowing users to access multiple applications with a single set of login credentials.

Apache Guacamole is an open-source remote desktop gateway that provides access to desktop environments and applications from anywhere with just a web browser. It supports a wide range of protocols and platforms, including VNC, RDP, SSH, and Telnet. In addition to its flexibility and ease of use, Guacamole also provides robust security features, such as SSL/TLS encryption and two-factor authentication.

In this blog post, we’ll explore how to integrate Apache Guacamole with SSO, allowing users to access their remote desktops and applications using their existing credentials. We’ll cover how to configure Guacamole to work with most popular identities providers such as Azure AD, and OKTA via OpenID Connect. With SSO integration, you can simplify remote access management, improve security, and streamline workflows for your organization.

Requirements

You will need a running Guacamole instance to complete this tutorial. I strongly advise you to read my previous article on the installation procedure, as it is the foundation for this one:

Apache Guacamole: manual installation with docker-compose

Apache Guacamole is one of the best open source tools out there. I love it and use it daily. But unfortunately, I’ve…

theko2fi.medium.com

Guacamole and Azure Active Directory

In this scenario, you have an Azure AD tenant and would like to delegate Guacamole authentication to Azure AD. You want your users to use their Azure account to log in to Guacamole.

So, let’s get started!

Register an application

Sign in to the Azure portal (https://portal.azure.com).
In the left-hand navigation menu, click on Azure Active Directory.
Click on App registrations and then click on New registration.
Enter a name for your application, I will name mine guacamole-digitalocean.
Select a supported account type, which determines who can use the application.
Select Web as the platform, and enter the redirect URI for your Apache Guacamole instance. The redirect URI should be in the format of https://<your_guacamole_instance>/guacamole. Replace <your_guacamole_instance> with the domain or IP address of your Guacamole instance. According to my previous article, mine is https://161-35-39-33.traefik.me/guacamole
After registering the application, note down the Application (client) ID and the Directory (tenant) ID values.

On the app’s overview page, select Authentication
In the implicit grant and hybrid flows section, check the ID tokens box and Save

Access your guacamole server terminal

Edit the ${HOME}/docker-stack/guacamole/.env file we created in the previous article and append the following secrets

POSTGRES_PASSWORD='PleasePutAStrongPasswordHere'
POSTGRES_USER='guacamole_user'
AZURE_TENANT_ID='bb0a294f-a214-965c-a186-7j60f6d64632'
OPENID_CLIENT_ID='c9da9e99-z38x-3i96-a3f0-y8f4c66qsf2p'
OPENID_REDIRECT_URI=https://161-35-39-33.traefik.me/guacamole

Where AZURE TENANT ID and OPENID CLIENT ID values are your Directory (tenant) ID and Application (client) ID values generated in the previous step. OPENID REDIRECT URI is the URL to your Guacamole instance.

Edit the ${HOME}/docker-stack/guacamole/docker-compose.yml file and append the following properties to the guacamole service environment section

...
  # guacamole
  guacamole:
    container_name: guacamole_frontend
    depends_on:
    - guacd
    - postgres
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_HOSTNAME: postgres
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
      POSTGRES_USER: '${POSTGRES_USER}'
      POSTGRESQL_AUTO_CREATE_ACCOUNTS: true
      OPENID_AUTHORIZATION_ENDPOINT: 'https://login.microsoftonline.com/${AZURE_TENANT_ID}/oauth2/v2.0/authorize'
      OPENID_JWKS_ENDPOINT: 'https://login.microsoftonline.com/${AZURE_TENANT_ID}/discovery/v2.0/keys'
      OPENID_ISSUER: 'https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0'
      OPENID_CLIENT_ID: '${OPENID_CLIENT_ID}'
      OPENID_REDIRECT_URI: '${OPENID_REDIRECT_URI}'
      OPENID_USERNAME_CLAIM_TYPE: email
      OPENID_SCOPE: openid email profile
      EXTENSION_PRIORITY: '*, openid'
...

If you want to know what each of these properties stands for, I recommend reading the Apache Guacamole documentation.

Then, to make the changes take effect, run the following command:

docker compose -f ${HOME}/docker-stack/guacamole/docker-compose.yml up -d

You now have the option to Sign in with OpenID when you browse to your Guacamole instance login page

Type your Microsoft account credentials and accept the permission request.

Congrats ! You’ve now successfully configured Apache Guacamole SSO integration with Azure AD

Guacamole and Okta

If you wish to use OKTA as your identity provider, there are the steps to follow

Register an APP

Sign in to the OKTA admin console.
In the left-hand navigation menu, click on Applications > applications.
Select Create App Integration.
Select OIDC — OpenID Connect as the Sign-in method

Select Web as the application type

Hit the next button
On the app’s General Settings page, enter a name in the App integration name field.
Upload a logo (optional)
Select Allow ID Token with implicit grant type in the Grant type section

Enter the Sign-in redirect URIs for your Apache Guacamole instance. The redirect URI should be in the format of https://<your_guacamole_instance>/guacamole. Replace <your_guacamole_instance> with the domain or IP address of your Guacamole instance. According to my previous article, mine is https://161-35-39-33.traefik.me/guacamole

Based on your company’s policies, you can choose to Allow everyone in your organization to access or Limit access to selected groups of users

After registering the application, note down the Client ID value.

Access to your Apache Guacamole server terminal

Edit the ${HOME}/docker-stack/guacamole/.env file we created in the previous article and append the following secrets

POSTGRES_PASSWORD='PleasePutAStrongPasswordHere'
POSTGRES_USER='guacamole_user'
OKTA_DOMAIN='trial-2548432.okta.com'
OPENID_CLIENT_ID='0oa4q22hf1WWRpCTh697'
OPENID_REDIRECT_URI=https://161-35-39-33.traefik.me/guacamole

Where OKTA_DOMAIN and OPENID_CLIENT_ID values are respectively your OKTA domain and the Client ID value generated in the previous step. OPENID_REDIRECT_URI is the URL to your Guacamole instance.

Edit the ${HOME}/docker-stack/guacamole/docker-compose.yml file and append the following properties to the guacamole service environment section

...
  # guacamole
  guacamole:
    container_name: guacamole_frontend
    depends_on:
    - guacd
    - postgres
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_HOSTNAME: postgres
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
      POSTGRES_USER: '${POSTGRES_USER}'
      POSTGRESQL_AUTO_CREATE_ACCOUNTS: true
      OPENID_AUTHORIZATION_ENDPOINT: 'https://${OKTA_DOMAIN}/oauth2/v1/authorize?state=foobarbaz'
      OPENID_JWKS_ENDPOINT: 'https://${OKTA_DOMAIN}/oauth2/v1/keys'
      OPENID_ISSUER: 'https://${OKTA_DOMAIN}'
      OPENID_CLIENT_ID: '${OPENID_CLIENT_ID}'
      OPENID_REDIRECT_URI: '${OPENID_REDIRECT_URI}'
      OPENID_USERNAME_CLAIM_TYPE: email
      OPENID_SCOPE: openid email profile
      EXTENSION_PRIORITY: '*, openid'
...

If you want to know what each of these properties stand for, I suggest you to have a look at the Apache Guacamole documentation.

Then run the command below for the changes to take effect

docker compose -f ${HOME}/docker-stack/guacamole/docker-compose.yml up -d

You now have the option to Sign in with OpenID when you browse to your Guacamole instance login page

When you click on that link, you’re prompted to type your OKTA login credentials

That’s all

Congrats ! You’ve now successfully configured Apache Guacamole SSO integration with OKTA

Please let me know if you want me to cover the SSO connection with Guacamole for any well-known identity providers. Thank you for reading all the way through; check back soon for more content. I’m accessible through the following channels: