Skip to content

Ubuntu on WSL broker setup

Jump to bottom
Jiri Formacek edited this page Sep 5, 2026 · 4 revisions

Broker authentication on Ubuntu in WSL

This guide configures broker-based authentication for AadAuthenticationFactory running in PowerShell 7 on Ubuntu under Windows Subsystem for Linux (WSL).

The instructions were verified with Ubuntu 26.04 on WSL. The module includes the MSAL native runtime, but Linux must provide the runtime libraries on which it depends.

Prerequisites

  • Windows 11 with WSL 2 and WSLg enabled
  • Ubuntu installed as a WSL distribution
  • PowerShell 7 for Linux
  • AadAuthenticationFactory 4.0.0 or later
  • An interactive desktop session; broker authentication is not intended for a headless WSL session

Update WSL from Windows PowerShell, then restart it:

wsl --update
wsl --shutdown

Start Ubuntu again and verify that WSLg exported a display:

printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\nXDG_RUNTIME_DIR=%s\n' \
  "$DISPLAY" "$WAYLAND_DISPLAY" "$XDG_RUNTIME_DIR"

At least DISPLAY or WAYLAND_DISPLAY should have a value.

Install the Linux runtime dependency

The MSAL Linux runtime depends on WebKitGTK. Install it from Ubuntu:

sudo apt update
sudo apt install --yes libwebkit2gtk-4.1-0

If the runtime package is not available directly, install the development package, which also pulls in the runtime:

sudo apt install --yes libwebkit2gtk-4.1-dev

The native library is distributed with AadAuthenticationFactory. It is normally located under:

~/.local/share/powershell/Modules/AadAuthenticationFactory/<version>/runtimes/linux-x64/native/libmsalruntime.so

Verify native dependencies

Find the installed module and inspect the native runtime from PowerShell:

$module = Get-Module -ListAvailable AadAuthenticationFactory |
    Sort-Object Version -Descending |
    Select-Object -First 1

$runtime = Join-Path $module.ModuleBase 'runtimes/linux-x64/native/libmsalruntime.so'
$runtime
Test-Path $runtime

Check the runtime's dynamic dependencies from Bash:

MSAL_RUNTIME="$HOME/.local/share/powershell/Modules/AadAuthenticationFactory/4.0.0/runtimes/linux-x64/native/libmsalruntime.so"
ldd "$MSAL_RUNTIME" | grep "not found" || echo "All native dependencies resolved"

Adjust 4.0.0 if a different module version is installed.

You can also test loading the library directly in PowerShell:

$runtime = "$HOME/.local/share/powershell/Modules/AadAuthenticationFactory/4.0.0/runtimes/linux-x64/native/libmsalruntime.so"
[System.Runtime.InteropServices.NativeLibrary]::Load($runtime)

A non-zero handle means that the native runtime loaded successfully.

Acquire a token through the broker

Create a named broker factory:

Import-Module AadAuthenticationFactory -Force

New-AadAuthenticationFactory `
    -Name me `
    -TenantId mytenant.com `
    -AuthMode Broker `
    -UserNameHint Joe.Doek@mytenant.com `
    -DefaultScopes 'https://graph.microsoft.com/.default'

Request the token:

$token = Get-AadToken -Factory me -Verbose
$token.AccessToken | Test-AadToken -PayloadOnly

The first request can show an interactive broker prompt. Later requests can use the account and token state maintained by the broker.

Browser-based interactive authentication

-AuthMode Interactive is different from -AuthMode Broker. Interactive mode launches a system browser for sign-in and listens on a temporary http://localhost address for the authentication response.

In WSL, MSAL needs a URL-opening tool and a registered browser that can handle HTTPS URLs.

Install xdg-utils

Install xdg-utils, which provides the xdg-open command used by MSAL:

sudo apt update
sudo apt install --yes xdg-utils

Start a new PowerShell process after installation, then verify that PowerShell can find the command:

Get-Command xdg-open -ErrorAction Stop

Test the complete URL-opening path before running authentication:

command -v xdg-open
xdg-settings get default-web-browser
xdg-open https://login.microsoftonline.com

xdg-utils provides the opener, but not a browser. The test URL must open successfully in a graphical browser available to the WSL session. If no browser opens, install or configure a WSLg-compatible Linux browser and make it the default HTTPS handler before continuing.

After the test succeeds, create an interactive factory and request a token:

Import-Module AadAuthenticationFactory -Force

New-AadAuthenticationFactory `
    -Name interactive `
    -TenantId mytenant.com `
    -AuthMode Interactive `
    -UserNameHint Joe.Doe@mytenant.com `
    -DefaultScopes 'https://graph.microsoft.com/.default'

$token = Get-AadToken -Factory interactive -Verbose

The configured browser should open. After sign-in, the browser posts the response to the temporary loopback listener in PowerShell and displays an authentication-complete page.

Troubleshooting

libwebkit2gtk-4.1.so.0: cannot open shared object file

Install the missing WebKitGTK runtime:

sudo apt update
sudo apt install --yes libwebkit2gtk-4.1-0

Open a new PowerShell process after installation and retry the command.

Unable to open a web page using xdg-open, gnome-open, kfmclient or wslview tools

This error applies to browser-based interactive authentication. It means MSAL could not find or execute a supported URL opener.

  1. Install xdg-utils:

    sudo apt update
sudo apt install --yes xdg-utils

  2. Check that xdg-open is visible and that a default browser is registered:

    command -v xdg-open
xdg-settings get default-web-browser

  3. Verify that the opener can launch the configured browser:

    xdg-open https://login.microsoftonline.com

  4. Close and reopen PowerShell. Confirm that the new process can find the opener:

    Get-Command xdg-open -ErrorAction Stop

  5. Retry Get-AadToken. Creating the factory does not launch the browser; token acquisition does.

If step 3 fails, xdg-open is installed but does not have a working browser handler. Install or configure a graphical Linux browser under WSLg, then repeat the test. If the session cannot run a graphical browser, use -AuthMode DeviceCode instead:

New-AadAuthenticationFactory `
    -Name deviceCode `
    -TenantId mytenant.com `
    -AuthMode DeviceCode `
    -UserNameHint Joe.Doe@mytenant.com `
    -DefaultScopes 'https://graph.microsoft.com/.default'

$token = Get-AadToken -Factory deviceCode -Verbose

Do not solve this error by copying an authentication URL from verbose logs into another machine. Authentication URLs can contain request-specific security values and should be handled as sensitive data.

Browser opens, but authentication does not return to PowerShell

Interactive authentication uses a temporary loopback redirect. Check the following:

  • The app registration is configured as a Mobile and desktop application.
  • http://localhost is registered as a redirect URI when using a custom client ID.
  • A firewall, VPN, proxy, or endpoint-security product is not blocking Windows-to-WSL localhost forwarding.
  • Only one token request is active for that factory.

Update and restart WSL if localhost or WSLg integration is not working:

wsl --update
wsl --shutdown

Then reopen Ubuntu, start a new PowerShell process, and retry.

Find other missing native libraries

ldd "$MSAL_RUNTIME" | grep "not found"

Install the Ubuntu packages that provide any listed libraries. Useful diagnostic commands include:

apt-file search path/to/missing-library.so
dpkg -S path/to/library.so

Install apt-file and update its index if needed:

sudo apt install --yes apt-file
sudo apt-file update

No broker window appears

Confirm that the session has WSLg display variables:

env | grep -E '^(DISPLAY|WAYLAND_DISPLAY|XDG_RUNTIME_DIR)='

If they are absent, update and restart WSL from Windows:

wsl --update
wsl --shutdown

Then reopen Ubuntu and PowerShell.

Confirm WSL and architecture

grep -i microsoft /proc/version
uname -m

The module currently distributes the Linux broker runtime for x86_64 (linux-x64). Linux ARM64 is not supported by the bundled MSAL native runtime.

Security notes

  • Do not place access tokens, refresh tokens, or client secrets in scripts or shell history.
  • Broker authentication is intended for interactive user authentication. Use workload identity federation, a certificate, or a managed identity for unattended automation.
  • Keep WSL, Ubuntu packages, PowerShell, and AadAuthenticationFactory updated.

Clone this wiki locally