Signing in to Apache Guacamole with authentik SSO
The supported method for signing users in to Apache Guacamole with authentik is OpenID Connect, following the Apache Guacamole guide in the authentik integrations catalog, which is marked with authentik support level. The decision you face is not how to configure that login, but whether to keep Guacamole as your browser gateway at all, or to use authentik's own RAC provider for browser access to Windows, macOS and Linux machines. Settle that question first, because it determines whether you build and operate a second system. Guacamole splits into two parts. The Guacamole web application is written in Java and provides the web interface and the authentication layer. The guacd daemon is separate: it listens for connections from the web application, reads just enough of the Guacamole protocol to choose a client plugin, and those plugins connect to the remote desktop servers on the user's behalf. Both components are released under the Apache License, Version 2.0, so licensing does not decide the question. Operating cost and the number of moving parts do. You will run the web application, guacd and a database backend (MariaDB or MySQL, PostgreSQL or SQL Server are documented), and the OIDC extension sits inside that stack.
If you keep Guacamole, confirm three things before you start: the Guacamole version you will run (1.6.0 was released on June 22, 2025), the OIDC extension settings your installation needs, and how group claims from authentik will map to Guacamole permissions, since Guacamole's database still holds connection and user grants. If you move to the RAC provider instead, confirm that it covers every protocol and target you use today, that its RAC outpost can reach your target hosts, and that your session recording and audit requirements are met without the Guacamole session recording player. Write that comparison down with your security team, then choose one path and plan the cutover. Running both for long periods doubles your patching and access review work.
What you need before configuring Guacamole SSO
Guacamole SSO depends on a few pieces being in place before any client settings are touched. Each card below is one item to confirm, from the authentik release line to the database Guacamole stores its state in.
Supported authentik release line
Run authentik on a release line that still receives security fixes. The security policy lists 2026.5.x and 2026.8.x as supported, and the project announces security releases at least 24 hours in advance, so plan a maintenance window that can absorb a patch on short notice. Confirm the exact version against the authentik Guacamole guide before you start, because the guide's steps are tied to a specific authentik version.
Guacamole version to standardize on
Pick the Guacamole release your team will run and record it in your change log. Apache Guacamole 1.6.0 was released on June 22, 2025, and the OpenID Connect extension must match the Guacamole server version it loads into. Check the extension version named in the authentik guide, since a mismatch between the web application and the extension is a common cause of failed sign-in.
Database backend for Guacamole
Guacamole stores connection definitions, users and permissions in a database. The manual documents MariaDB or MySQL, PostgreSQL and SQL Server, so choose the engine your database team already backs up and patches. Decide this before deployment, because moving connection definitions later means exporting and re-importing them, and the OIDC login does not replace the need for a database account.
DNS names and TLS certificates
Give authentik and Guacamole each a stable DNS name with a certificate trusted by the browsers and the authentik server. The OpenID Connect redirect URI must match the Guacamole address exactly, including scheme and path, so a name change later breaks sign-in. Confirm which certificate authority your organization uses and whether internal clients need its root certificate installed.
OAuth2/OIDC provider in authentik
Create an OAuth2/OpenID Connect provider and application in authentik for Guacamole before editing Guacamole's configuration. You will need the client ID, client secret, issuer URL and the redirect URI that Guacamole expects, and the provider must issue the group or user claims that Guacamole uses to decide access. Keep a local Guacamole administrator account available so you can recover if the identity provider is unreachable.
Remote targets and access paths
List the Windows, macOS and Linux machines users will reach over RDP, SSH and VNC, along with the network paths from the guacd host to each one. If you plan to use authentik's RAC provider instead of a separate Guacamole server, confirm the protocols and outpost placement it needs, because that changes which of these items you still need to build.
How to configure the OpenID Connect sign-in step by step
This sequence connects Apache Guacamole to authentik over OpenID Connect so users sign in through authentik, while a local administrator account stays available for recovery. Each step ends with a check you can run before moving on.
Create the OAuth2/OIDC provider in authentik
In the authentik admin interface, create an OAuth2/OpenID Connect provider for Guacamole and record its client ID and client secret. Choose a confidential client type, set the authorization flow you intend to use, and note the issuer URL that authentik shows for the provider, since Guacamole needs it in a later step. Confirm the provider appears in the providers list with the expected name. The step is done when you can open the provider and read back the client ID, the client secret and the issuer URL without errors.
Create the application and bind it to the provider
Create an application in authentik that uses the provider from the previous step, and set a slug that you will reuse in the issuer path. Restrict access with a policy or group binding so that only the people who should reach Guacamole can start the sign-in. Confirm the application is visible in the user library for a test account in the bound group and hidden for an account outside it. Both checks are done when the test accounts behave as expected.
Set redirect URIs and scopes
On the provider, enter the redirect URI that matches your Guacamole base URL with the OpenID Connect callback path described in the Guacamole extension documentation, using https. Keep the scopes to the standard openid, profile and email set unless your group claim design needs an additional scope. Confirm the redirect URI matches character for character, including the trailing path, because a mismatch is the most common cause of a failed callback. Verify by opening the provider's configuration and comparing the saved URI to the one in your Guacamole reverse proxy settings.
Install the Guacamole OpenID Connect extension
Install the OpenID Connect extension on the Guacamole web application, following the Guacamole manual for your installation method, whether native or Docker. Place the extension JAR in the Guacamole extensions directory and restart the Tomcat-hosted web application so it loads. Check the Guacamole logs for a line showing the extension loaded without errors. Keep the existing database or local authentication extension in place at this stage so you retain a working login path.
Set the issuer and client settings in guacamole.properties
Edit guacamole.properties to add the OpenID Connect issuer, authorization endpoint, token endpoint, client ID, client secret, redirect URI and the username claim name, using the values recorded from authentik. Set the username claim to a stable attribute your organization uses, such as the preferred username, and confirm the exact key names against the version of the extension you installed. Restart Guacamole and check the logs for a successful load of the OpenID Connect settings with no missing-property warnings.
Map the username claim to Guacamole accounts
Decide how the claim value from authentik maps to Guacamole usernames, and confirm that the value is unique across your user base. Sign in once with a test account and review which username Guacamole created or matched. If you already have local Guacamole accounts, check that the claim values match their usernames exactly, since case or formatting differences create duplicate accounts. The step is done when the test user lands on the Guacamole home page under the expected name and the existing permissions apply.
Test an interactive sign-in and review the authentik event log
Sign in to Guacamole from a clean browser session through the authentik login, complete any MFA step your policy requires, and confirm you reach the Guacamole home page. Then open the authentik event log and find the authorization and login events for that user, checking that the application and provider names are correct and no failure events appear. This check confirms both the authentik side and the Guacamole callback. Record the result before you move on.
Confirm the local administrator account still works
Before you disable local login or retire the old authentication path, sign in to Guacamole with the local administrator account using the database or local credentials. Confirm that this account can open the administration pages and change settings. Keep the recovery credentials stored in your secrets manager and document how to switch the OpenID Connect extension off if authentik is unavailable. The step is done when the local administrator login succeeds in a fresh session.
Mapping authentik claims and groups to Guacamole accounts
This table compares each OIDC claim authentik returns with the Guacamole role it feeds and the checks needed before relying on it. Read it as a sequence: the identity arrives from authentik, Guacamole matches it to an account, and only then do group-based permissions apply. The main takeaway is that a successful login does not by itself grant access to any connection.
| Claim or element | What it carries | How Guacamole uses it | What to verify in your environment |
|---|---|---|---|
| Subject (sub) | Stable unique identifier for the authentik user | Typically not the display name; confirm which claim the integration matches to the Guacamole username | Confirm the claim is stable across renames and that it does not change between test and production |
| Username (preferred_username) | The authentik username | Candidate for the Guacamole username, which must match an existing account in the backend | Check that usernames are unique and that case handling matches the backend's account records |
| The user's email address | Informational unless your configuration maps it to an account field | Confirm whether your Guacamole build uses email for matching or only for display | |
| Groups claim | Group names the user belongs to in authentik | Group membership can drive Guacamole user group permissions, if the mapping is configured | Verify the group claim is present in the ID token or userinfo response and the names match exactly |
| Guacamole account in backend | A user record in the database, LDAP directory or other backend Guacamole reads | Permissions attach to accounts and groups in this backend after login | Confirm whether the account must be created in advance and whether auto-creation is available for your chosen backend |
| Connections and permissions | Remote desktop or SSH connections and the users or groups granted access | Access is granted here, separate from authentication | Test that each group can see only the intended connections, with a non-admin test user |
| Admin account | Local or break-glass Guacamole administrator | Used when the OIDC configuration or group mapping fails | Keep one tested admin path outside SSO and confirm it works before cutover |
When authentik's RAC provider can replace a separate Guacamole deployment
The RAC provider in authentik gives signed-in users browser access to Windows, macOS and Linux machines over RDP, SSH and VNC through a RAC outpost. If the only requirement is that people reach a known set of machines through the same identity provider that governs everything else, a second gateway may add operating cost without adding a capability you need. That is a hypothesis to test, not a default. Start by listing the protocols, the number of target machines, and who needs access to which systems, then check each item against the RAC provider documentation before deciding whether authentik alone covers it.
Several items decide the question and should be verified rather than assumed. First, confirm session recording requirements: if auditors or incident responders need recorded remote sessions, check what authentik's RAC provider records in your version and compare it with the session recording player extension the Guacamole manual describes. Second, confirm protocol coverage and any extension needs, such as smart card, MFA or session-specific behavior that you depend on today. Third, if you run Guacamole now, inventory its database-backed administration on MariaDB or MySQL, PostgreSQL or SQL Server, including connection definitions, user mappings and connection history, and decide whether that data must be kept, exported or retired. Ask your team which of these is required, because each one can change the answer.
Keeping an existing Guacamole deployment is usually the simpler path when its users, connection history or recordings must survive, or when your team already runs its extensions and backups reliably. In that case, the integration guide covers the OpenID Connect sign-in layer with authentik and leaves the gateway in place. If you migrate to the RAC provider, plan a parallel run, confirm the target machine list and access policies in authentik, and agree in writing with the team that owns the machines which history will be retained. The result of this check is a documented decision, which is what a scope review or a fixed-scope quote should start from.
Hardening the Guacamole and authentik connection
The Guacamole sign-in path runs through authentik, and the remote desktop sessions run through Guacamole and guacd, so a weak point in either one exposes every machine behind it. The cards below cover the controls that connect the two products: the OIDC trust, the MFA gate, the internal traffic between Guacamole and guacd, recovery access, encryption and session audit.
Restrict the redirect URI and client secret
The OpenID Connect client in authentik should accept only the exact callback URL of your Guacamole host, with no wildcards and no extra schemes or ports you do not run. Store the client secret in your secret manager and inject it into the Guacamole configuration at deploy time, not in a shared file. Check that the client secret rotates through a documented procedure, and confirm which token lifetimes authentik applies to the client so a stolen session ends quickly.
Enforce MFA in authentik before Guacamole
Guacamole trusts the identity that authentik asserts, so the second factor must be enforced in authentik's authentication flow, not in Guacamole. Bind the MFA stage to the application or to the group that holds Guacamole access, and confirm that users cannot reach the OIDC authorization step through a flow that skips it. Test with an account that has no second factor enrolled to confirm enrollment is required.
Limit guacd to the web application
The guacd daemon listens for TCP connections from the Guacamole web application and should never be reachable from user networks. Bind it to a loopback or private interface, and restrict its port with host or network firewall rules so only the Guacamole web application host or container can connect. In a containerized setup, keep guacd on an internal network with no published port. Verify this with a port scan from a user subnet.
Keep a break-glass local admin
If authentik is down or its signing keys or provider settings are misconfigured, every Guacamole user is locked out. Keep a local Guacamole administrator account with a strong, offline-stored password and a documented procedure for enabling it. Test the break-glass path on a schedule, and confirm that the local account is excluded from the OIDC-only login policy you apply to daily users.
Encrypt every hop
Serve the Guacamole web interface only over HTTPS, and make sure the browser-to-authentik and authentik-to-Guacamole OIDC redirects and token calls use TLS with certificates your clients trust. Confirm that the connections from Guacamole to the database and to the target machines over RDP, SSH and VNC use the encryption those protocols support. Record which hop terminates TLS at a reverse proxy, because the proxy then becomes part of the trust boundary.
Enable session recording where audit requires it
Where access to remote machines must be auditable, install the session recording player extension and configure recording on the connections that need it. Decide retention and access to recordings before go-live, since recordings can capture sensitive screens and commands. Confirm with your auditors which connections must be recorded and whether the RAC provider in authentik would cover the same requirement for your setup.
Testing the sign-in, permissions and session paths
The identity team owns the authentik side of the OpenID Connect flow. Their checks confirm that the Guacamole client is registered correctly, that the redirect URI matches the one Guacamole uses, and that the tokens carry the claims Guacamole needs to map users and groups. Run these checks with a test user and a test group before any production user signs in, and keep the results with the change record.
- Provider and application settings: Confirm the OAuth2/OIDC provider, the application entry and the redirect URI match the values in the Guacamole configuration exactly, including scheme and path.
- Token claims: Sign in as a test user and inspect the ID token or userinfo response to confirm the username and group claims appear with the names Guacamole expects.
- Group membership: Add the test user to one group that should have access and to one that should not, then confirm the claims change accordingly.
- Flow behavior: Check that the authorization and login flow sends the user to the expected MFA stage and returns them to Guacamole without loops.
Save each claim sample so the platform team can compare it against what Guacamole receives.
The platform team owns the Guacamole side: the sign-in handoff, which connections each user can see, and whether guacd opens sessions to each target protocol. Test these paths with a dedicated test account for each permission level and with one target machine per protocol that the design includes. A session that opens over RDP but fails over SSH usually points to a connection definition or a guacd plugin problem, not to authentication.
- Sign-in handoff: Confirm a test user reaches the Guacamole home screen after authentik and that a user without the required group is refused.
- Connection visibility: Check that each test group sees only the connections granted to it and that no connection appears for users outside the group.
- Protocol sessions: Open one session each over RDP, SSH and VNC where those protocols are in scope, and confirm the remote desktop or shell appears in the browser.
- guacd behavior: Review the guacd log during each session and confirm the connection starts and closes cleanly.
- Local admin path: Verify the break-glass administrator account still signs in when the OIDC path is disabled in a test window.
Record the connection names, test accounts and outcomes for each protocol so repeat runs after upgrades are comparable.
The security team checks that authentication decisions are enforced and recorded. They confirm that MFA applies to every path into Guacamole, that failed and successful sign-ins are logged in both authentik and Guacamole, and that session recording, where the design enables it, captures what the design says it captures. These checks run against the live configuration, so they should be repeated after any change to flows, policies or the Guacamole extension set.
- MFA enforcement: Attempt sign-in with a test account that has no second factor enrolled and confirm the flow blocks or forces enrollment, as the policy intends.
- Bypass attempts: Try to reach Guacamole directly without going through authentik and confirm the request is refused or redirected.
- Log coverage: Confirm sign-in events, failed attempts and session starts appear in the logs each system sends, and that the log timestamps and user identifiers can be matched across systems.
- Session recording: If session recording is enabled, start a test session, end it and confirm the recording is stored and playable by the intended reviewers only.
- Access review evidence: Export the list of groups and connection grants so the reviewer can compare it with the approved access model.
Confirm the retention period for these logs with your own policy owner, because the required retention depends on your regulatory context.
Common failures in authentik and Guacamole SSO
This table lists the failures teams most often hit when wiring authentik to Apache Guacamole over OpenID Connect, with the likely cause and the fix for each. Read it while testing the sign-in path, because several symptoms look identical from the browser but have different causes in authentik, Guacamole or the target host.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch | The redirect URI registered in the authentik OAuth2/OIDC provider does not exactly match the callback URL Guacamole sends, often because of a scheme, host name, port or trailing path difference behind a reverse proxy. | Copy the callback URL from the Guacamole OIDC settings, paste it into the authentik provider's redirect URIs exactly, then retest from a fresh browser session. |
| Wrong issuer URL | The OpenID issuer configured in Guacamole points to the wrong application slug or to the authentik root instead of the provider's issuer endpoint, so discovery and token validation fail. | Take the issuer value from the authentik provider's details in the admin interface and set it in Guacamole exactly, including the application slug and no extra trailing characters. |
| Username claim does not match a Guacamole account | Guacamole matches the claim it receives to an existing user name, and the claim configured (for example, the preferred username) differs in case or value from the account created in Guacamole. | Confirm which claim Guacamole reads, compare it with the value authentik returns for a test user, then align the username or the claim setting. Ask the vendor guide which claim the integration expects. |
| Signed in, but no connections visible | Guacamole authenticates the user but the account has no permissions on any connection, so the connection list is empty after login. Group claims are often not mapped to Guacamole permissions. | Grant the user or a group read permission on the required connections in Guacamole, or map the authentik group claim to a Guacamole user group that holds those permissions. Verify with a test account. |
| Admins locked out when SSO fails | The only administrator account is an OIDC-linked user, and a misconfigured issuer, client secret or redirect URI blocks every login path. | Before enabling SSO, keep a local Guacamole administrator with a known password and test it. Document the procedure for disabling the OIDC extension if the identity provider is unavailable. |
| guacd cannot reach the target host | The guacd daemon runs on a different host or network segment than the target, so it cannot open RDP, SSH or VNC sessions, even though the web sign-in succeeds. | Test the protocol port from the guacd host to the target, check firewall and routing rules, and confirm the connection settings (host, port, credentials) in Guacamole. Review guacd logs for the error. |
| RAC outpost cannot reach the target when using authentik RAC | When authentik's RAC provider is used instead, the RAC outpost lacks network access to the remote machine, or the outpost is not running or registered. | Verify the outpost is running and connected to authentik, then test the RDP, SSH or VNC port from the outpost's network. Confirm the target is listed in the RAC provider configuration. |
| Session recording or extension missing after upgrade | An extension such as OpenID Connect or session recording is absent in the new Guacamole build or the image was not updated alongside the web application. | Check the extension files deployed with the running Guacamole version, match extension and web application versions, and retest sign-in after each upgrade. |
Questions buyers ask about authentik and Guacamole SSO
What drives the cost of an authentik and Guacamole SSO integration?
Scope drives most of the cost: how many target protocols and applications are involved, whether Guacamole runs natively or in Docker, and whether authentik's RAC provider is part of the design. Database work matters too, because Guacamole supports MariaDB or MySQL, PostgreSQL and SQL Server backends, and the authentik side depends on its own PostgreSQL. Certificate work adds effort when internal certificate authorities, reverse proxies or custom trust chains are involved. A written scope should list each component, who operates it after handover, and what testing is included. Ask for the quote to separate one-time build work from any recurring support or upgrade retainer, since those are priced differently and recur on different schedules.
How long does the integration take to complete?
The duration depends mostly on how ready your environment is when work starts. Existing DNS names, a working authentik instance, a Guacamole host you can reach, and a defined test group shorten the path, while missing access, unclear ownership of certificates or undecided RAC requirements extend it. DeployOpen does not estimate durations in this section. Ask for a timeline in the written scope, and confirm which dependencies the timeline assumes you will meet and by which dates. Delays from waiting on approvals or change windows are common in regulated environments and should be named explicitly in the plan.
What does our team need to provide before the work starts?
Plan for administrative access to the authentik instance and the Guacamole host, a DNS name for each service, and certificates that the browsers and servers will trust. You will also need a small test group in authentik with known users, the group names you plan to map to Guacamole permissions, and a named contact who can approve changes. If the RAC provider is in scope, add network paths from the RAC outpost to the remote Windows, macOS or Linux machines over RDP, SSH or VNC. Confirm each item in writing so that access and approvals are not discovered as blockers during the build.
Can our own team set up authentik and Guacamole SSO without a partner?
Yes, if your team has people comfortable with OpenID Connect, reverse proxies, PostgreSQL and Linux service management. The Apache Guacamole guide on the authentik integrations catalog covers the OAuth2 and OpenID Connect configuration, and the Guacamole manual documents its extensions and architecture. The work that most often takes longer for internal teams is testing failure paths, such as a lockout when the identity provider is unavailable, and documenting the setup so it survives staff changes. A partner is useful when you want that verification, operational runbooks and a supported upgrade path handled as a fixed scope.
Does the RAC provider replace a separate Guacamole deployment?
It can replace it for some use cases, but the decision depends on your requirements. authentik's RAC provider gives browser access to remote Windows, macOS and Linux machines over RDP, SSH and VNC through a RAC outpost, all managed inside authentik. Guacamole is a clientless gateway with its own web application, guacd daemon, database options, session recording player and a wider set of authentication extensions. Compare the protocols you need, whether you require Guacamole's session recording, how you handle connection rules per user, and which team will operate each platform. Confirm the RAC provider's current capabilities against the authentik documentation before you decide.
Is authentik free to use for this integration?
The Open Source edition of authentik is released under the MIT license, according to the license file in its GitHub repository, and most of the code falls under that license. Code in the authentik/enterprise/ directory is covered by a separate enterprise license defined in that directory, and the pricing page lists features such as mTLS client certificate authentication, password history and enhanced audit logging as Enterprise-only. Check which edition and features your design needs before the build. Apache Guacamole itself is released under the Apache License, Version 2.0, so review that license alongside authentik's terms.
What breaks most often after a Guacamole SSO setup goes live?
The common failures involve redirect URIs that do not match the Guacamole hostname, certificate trust errors in the browser or on the Guacamole server, and group claims that do not map to the Guacamole permissions you intended. Upgrades to authentik can also change behavior, and the project's security policy lists supported versions that receive fixes, so plan a test environment for each upgrade. Keep a local administrator path in Guacamole for recovery and test it before go-live. Operational checks should cover logins, group mapping and session connectivity to the target machines.
How DeployOpen scopes and delivers authentik and Guacamole SSO
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so authentik and Guacamole run in your cloud accounts, data centers or air-gapped network. Engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm which Guacamole deployment exists or is planned, and whether it runs natively or in Docker.
- Record the authentik version, deployment method and PostgreSQL arrangement that the integration will use.
- Agree in writing whether the scope covers OIDC sign-in only, the authentik RAC provider, or a replacement decision.
How we build
- Configure the authentik OAuth2/OpenID Connect provider and application for Guacamole, including redirect URIs and group claims.
- Map authentik groups to Guacamole user and connection permissions, and test each role against real connections.
- Test the sign-in path, a local administrator fallback, and the RAC outpost connections where that option is in scope.
How we hand over
- Document the client settings, claim mappings, redirect URIs and secrets locations so your team can rotate them.
- Provide a runbook for adding users, changing group access and recovering when the identity provider is unavailable.
- Walk your operators through the test results and the decisions recorded during scoping.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Plan authentik and Guacamole version changes against their release notes before you upgrade either component.
- Ask any support provider to confirm response terms in writing, since these are set per agreement.
