Skip to main content

Integrate with Apache Guacamole

Support level: authentik

What is Apache Guacamole?​

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.

-- https://guacamole.apache.org/

Preparation​

The following placeholders are used in this guide:

  • guacamole.company is the FQDN of the Guacamole installation.
  • authentik.company is the FQDN of the authentik installation.
info

This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.

authentik configuration​

Redirect URI changes in authentik 2026.5

In authentik versions earlier than 2026.5, all Redirect URIs are automatically treated as Authorization type. If you are using one of these older authentik versions, add only the Authorization URL to your Redirect URIs and do not configure a Post Logout URI.

To support the integration of Apache Guacamole with authentik, you need to create an application/provider pair in authentik.

Create an application and provider​

  1. Log in to authentik as an administrator and open the authentik Admin interface.

  2. Navigate to Applications > Applications and click New Application to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)

    • Application: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings. Note the Slug value because it will be required later.
    • Choose a Provider type: select OAuth2/OpenID Connect as the provider type.
    • Configure the Provider: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
      • Note the Client ID value because it will be required later.
      • Add a Redirect URI of type Strict Authorization as https://guacamole.company/. If users access Apache Guacamole on a subpath, use the full URL that users enter in their browser.
      • Select any available signing key.
      • If you customize token validity, keep the Access Token validity at 300 minutes or less.
    • Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's Application Dashboard page.

  3. Click Submit to save the new application and provider.

Apache Guacamole configuration​

Create an administrator account in Apache Guacamole before configuring single sign-on. Use the same username as the authentik user that will administer Apache Guacamole, and grant that user administrator permissions. This keeps the admin settings reachable if you need to revert the OpenID Connect configuration.

User identifier

This guide uses preferred_username as the Apache Guacamole user identifier. Ensure that the authentik Allow users to change username setting is disabled to prevent users from being mapped to a different Apache Guacamole account after a username change.

Add the following variables to your Apache Guacamole environment file:

.env
OPENID_ENABLED=true
OPENID_AUTHORIZATION_ENDPOINT=https://authentik.company/application/o/authorize/
OPENID_JWKS_ENDPOINT=https://authentik.company/application/o/<application_slug>/jwks/
OPENID_ISSUER=https://authentik.company/application/o/<application_slug>/
OPENID_CLIENT_ID=<Client ID from authentik>
OPENID_REDIRECT_URI=https://guacamole.company/
OPENID_USERNAME_CLAIM_TYPE=preferred_username

To automatically redirect unauthenticated users to authentik, add the following variable:

.env
EXTENSION_PRIORITY=openid

To show the Apache Guacamole login screen with an OpenID Connect login option, add the following variable instead:

.env
EXTENSION_PRIORITY=*,openid

If your deployment uses a custom GUACAMOLE_HOME, ensure that guacamole.properties includes the following setting so Apache Guacamole can read configuration from environment variables:

/etc/guacamole/guacamole.properties
enable-environment-properties: true

Restart Apache Guacamole after changing the OpenID Connect configuration. For Docker Compose deployments, recreate the Apache Guacamole container with docker compose up.

Trust self-signed certificates (optional)​

When authentik uses a certificate signed by a private certificate authority, add that certificate authority certificate to the operating system trust store and to the Java trust store on the Apache Guacamole host.

Add the certificate authority certificate to the operating system trust store​

On Debian-based operating systems, copy the certificate authority certificate to /usr/local/share/ca-certificates/ with a .crt file extension, then run the following command:

update-ca-certificates

On Synology systems, copy the certificate authority certificate to /usr/syno/etc/security-profile/ca-bundle-profile/ca-certificates/ with a .crt file extension, then run the following command:

update-ca-certificates.sh

Add the certificate authority certificate to the Java trust store​

Export the certificate authority certificate as a PKCS #12 file:

openssl pkcs12 -export -in <CA_certificate>.crt -inkey <CA_certificate>.key -out <CA_certificate>.p12 -passout pass:<password>

Import the certificate authority certificate into the Java trust store on the Apache Guacamole host:

keytool -importkeystore -srckeystore <CA_certificate>.p12 -srcstoretype PKCS12 -keystore /opt/java/openjdk/lib/security/cacerts -deststorepass <destination_store_password> -noprompt -srcstorepass <password>
Java trust store path

Apache Guacamole versions earlier than 1.6 commonly used /opt/java/openjdk/jre/lib/security/cacerts for the Java trust store.

Configuration verification​

To confirm that authentik is properly configured with Apache Guacamole, log out of Apache Guacamole and open it again. If you configured Apache Guacamole to show its login screen, click the OpenID Connect login option at the bottom-left corner of the login page and complete the authentik flow.

Resources​