GUACAMOLE-2210: Add support for AAD authentication to RDP protocol. by aleitner · Pull Request #633 · apache/guacamole-server

aleitner · 2026-02-13T20:52:03Z

Adds Azure AD (Entra ID) authentication for RDP connections using FreeRDP 3's AadSecurity mode
Uses the OAuth2 device authorization grant (RFC 8628), so no credentials are stored in or entered through Guacamole. The user completes sign-in on a separate device (typically a phone) by scanning a QR code
HTTP requests use libcurl; token/device-code responses are parsed with WinPR's JSON API

Authentication flow

When security=aad is set on an RDP connection:

FreeRDP begins the AAD handshake and invokes the GetAccessToken callback with the requested scope and a Proof-of-Possession key confirmation (req_cnf).
guacd requests a device code from Azure AD using the configured application (client) ID and scope, receiving a user code and a verification URI.
guacd opens a pipe stream to the connection owner carrying the user code and verification URI as JSON. The web client renders this as a QR code (paired change: apache/guacamole-client#1168).
guacd polls the token endpoint (grant_type=urn:ietf:params:oauth:grant-type:device_code) while the user authenticates on their own device, forwarding req_cnf so Azure issues a Proof-of-Possession token. Polling honors the server-provided interval and slow_down, and stops if the connection closes or the code expires.
When the flow completes, the pipe stream is closed (dismissing the prompt) and the access token is handed to FreeRDP, which finishes the AAD-authenticated RDP session.

Configuration

New RDP parameters:

aad-client-id (required for AAD) is the Azure AD application (client) ID to authenticate as. The app must have public client flows enabled so it can use the device code grant.
aad-scope (optional) is the OAuth2 scope to request. If omitted, the scope FreeRDP derives for the target host is used.
aad-tenant-id (optional) is the Azure AD tenant, defaulting to organizations.

Notes

The entire feature is gated on HAVE_FREERDP_AAD_SUPPORT (FreeRDP built with AAD) and the presence of libcurl. If either is unavailable it compiles out cleanly, and non-AAD RDP is unaffected.
Adds a unit test for the percent-decoding helper.

Paired with apache/guacamole-client#1168

aleitner · 2026-02-13T21:05:30Z

Didn't realize we don't have curl. This would require adding curl as a dependency

necouchman

Looks like the build is failing with an error about the switch() statement and one of the enums.

aleitner · 2026-02-14T02:42:26Z

Looks like the build is failing with an error about the switch() statement and one of the enums.

Ahh whoops! I was testing with only freerdp3 as that's when AAD support was implemented. Just added a case to the switch for freerdp2 so that it errors if AAD is selected

necouchman

A few comments/changes. Also, generally:

It seems like there might be a couple of opportunities for reusing code by creating a couple of new functions?
Some of the documentation within the code is a bit sparse and could use a little more building out.

aleitner · 2026-05-07T00:34:56Z

Also fixed two runtime issues from changes Microsoft made to the AAD login flow. The credential POST field name needs to be flowToken (camelCase) per $Config.sFTName, and for AVD sessions Microsoft now serves a /common/rdp/set device-binding page that the browser auto-submits before the OAuth redirect, which we replicate with a second POST

aleitner · 2026-07-21T17:25:44Z

This has been reworked from the original login-page automation to the OAuth2 device authorization grant (RFC 8628), so the user signs in on a separate device via a QR code and no credentials pass through Guacamole.

bbennett-ks

LGTM!

bbennett-ks · 2026-08-20T19:00:43Z

+     * not held open. */
+    guac_stream* stream = guac_client_alloc_stream(client);
+    if (stream == NULL) {
+        guac_client_log(client, GUAC_LOG_DEBUG,


Should this be a warning?

Made it a warning.

bbennett-ks · 2026-08-20T19:11:44Z

+        guac_client_log(client, GUAC_LOG_DEBUG,
+                "AAD: Failed to send the sign-in prompt");
+
+    guac_client_free_stream(client, stream);


If guac_protocol_send_pipe() succeeds, but guac_protocol_send_blob() fails, send & flush?

Reworked so end and flush always run once the pipe is open, even if the blob send fails.

bbennett-ks · 2026-08-20T19:13:08Z

+    /* Store the prompt so users who join or reconnect while sign-in is pending
+     * are brought up to date, then show it to the current owner */
+    char* body = guac_rdp_aad_build_prompt_json(dc);
+    if (body != NULL) {


Log a warning if body == NULL?

Added a warning on the null path.

bbennett-ks · 2026-08-20T19:26:38Z

+        /* Sleep in short slices so a disconnect is noticed within ~1s rather
+         * than after the full polling interval */
+        for (int i = 0; i < interval && client->state == GUAC_CLIENT_RUNNING; i++)
+            sleep(1);


In for (int i loop, maybe check for time(NULL) < deadline and guac_client_for_owner(client, guac_rdp_aad_owner_present, NULL), like in the while loop?

Added the deadline and owner checks to the sleep loop too.

bbennett-ks

New changes LGTM!

aleitner mentioned this pull request Feb 13, 2026

GUACAMOLE-2210: Add support for AAD authentication to RDP protocol. apache/guacamole-client#1168

Open

aleitner force-pushed the GUACAMOLE-2210-AAD branch from 14d083e to ff25596 Compare February 13, 2026 21:13

necouchman requested changes Feb 14, 2026

View reviewed changes

Comment thread src/protocols/rdp/rdp.c Outdated

aleitner force-pushed the GUACAMOLE-2210-AAD branch from ff25596 to de377cf Compare February 14, 2026 02:39

mike-jumper reviewed Mar 31, 2026

View reviewed changes

Comment thread src/protocols/rdp/aad.c Outdated

aleitner force-pushed the GUACAMOLE-2210-AAD branch from 7989a72 to 37b1d5a Compare April 1, 2026 21:13

necouchman requested changes May 2, 2026

View reviewed changes

davekempe mentioned this pull request May 18, 2026

Proposal: Entra ID 'use a web account to sign in' RDP authentication sol1/rustguac#136

Open

mike-jumper changed the base branch from staging/1.6.1 to main July 14, 2026 03:51

aleitner force-pushed the GUACAMOLE-2210-AAD branch 2 times, most recently from 685437e to eb58713 Compare July 21, 2026 17:16

bbennett-ks suggested changes Aug 16, 2026

View reviewed changes

Comment thread src/protocols/rdp/Makefile.am

Comment thread src/protocols/rdp/Makefile.am Outdated

Comment thread src/protocols/rdp/aad.c Outdated

Comment thread src/protocols/rdp/aad.c

Comment thread src/protocols/rdp/aad.c

bbennett-ks suggested changes Aug 16, 2026

View reviewed changes

Comment thread src/protocols/rdp/aad.c Outdated

Comment thread src/protocols/rdp/aad.c Outdated

aleitner force-pushed the GUACAMOLE-2210-AAD branch from eb58713 to 954e72d Compare August 20, 2026 14:17

bbennett-ks approved these changes Aug 20, 2026

View reviewed changes

aleitner force-pushed the GUACAMOLE-2210-AAD branch from 954e72d to b91cf82 Compare August 20, 2026 16:29

bbennett-ks suggested changes Aug 20, 2026

View reviewed changes

GUACAMOLE-2210: Add support for AAD authentication to RDP protocol.

b34a98d

aleitner force-pushed the GUACAMOLE-2210-AAD branch from b91cf82 to b34a98d Compare August 20, 2026 20:00

bbennett-ks approved these changes Aug 20, 2026

View reviewed changes

Conversation

aleitner commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Authentication flow

Configuration

Notes

Uh oh!

aleitner commented Feb 13, 2026

Uh oh!

necouchman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aleitner commented Feb 14, 2026

Uh oh!

Uh oh!

necouchman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aleitner commented May 7, 2026

Uh oh!

aleitner commented Jul 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bbennett-ks left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bbennett-ks left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aleitner commented Feb 13, 2026 •

edited

Loading