Skip to content

Commit e82a44c

Browse files
bgavrilMSbgavrilMS
authored
Merge pull request #641 from ploegert/docs-editor/linux-broker-net-1742324708
Create article linux-broker-net
2 parents e8a46f5 + c7c3eff commit e82a44c

11 files changed

Lines changed: 424 additions & 1 deletion

File tree

‎msal-dotnet-articles/TOC.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,11 @@
2626
- name: Acquiring tokens interactively
2727
href: acquiring-tokens/desktop-mobile/acquiring-tokens-interactively.md
2828
- name: Using MSAL.NET with Web Account Manager (WAM)
29-
href: acquiring-tokens/desktop-mobile/wam.md
29+
href: ./acquiring-tokens/desktop-mobile/wam.md
30+
- name: Using MSAL.Net with broker on Linux distributions
31+
href: ./acquiring-tokens/desktop-mobile/linux-dotnet-sdk.md
32+
- name: Using MSAL.Net with WSL
33+
href: ./acquiring-tokens/desktop-mobile/linux-dotnet-sdk-wsl.md
3034
- name: Xamarin
3135
href: acquiring-tokens/desktop-mobile/mobile-applications.md
3236
- name: Sign-in users with social identities

‎msal-dotnet-articles/acquiring-tokens/desktop-mobile/linux-dotnet-sdk-wsl.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Using MSAL.Net with Windows Subsystem for Linux
3+
description: Learn how to integrate Microsoft Entra ID authentication in WSL apps using MSAL.NET and the Microsoft Single Sign-on for Linux broker.
4+
author: ploegert
5+
ms.author: jploegert
6+
ms.service: msal
7+
ms.topic: how-to
8+
ms.date: 05/08/2025
9+
---
10+
11+
# Enable SSO in WSL (Windows Subsystem for Linux) apps using MSAL.NET and WAM
12+
13+
MSAL is able to call the Microsoft Single Sign-on to Linux, a Linux component that is shipped independent of the Linux Distribution, however it gets installed using a package manager using `sudo apt install microsoft-identity-broker` or `sudo dnf install microsoft-identity-broker`.
14+
15+
This component acts as an authentication broker allowing the users of your app to benefit from integration with accounts known to Linux, such as the account you signed into your Linux sessions for apps that consume from the broker. It's also bundled as a dependency of applications developed by Microsoft, such as [Company Portal](/mem/intune-service/user-help/enroll-device-linux). These applications are installed when a Linux computer is enrolled in a company's device fleet via an endpoint management solution like [Microsoft Intune](/mem/intune/fundamentals/what-is-intune).
16+
17+
> [!NOTE]
18+
> Microsoft single sign-on (SSO) for Linux authentication broker support is introduced with `Microsoft.Identity.Client` version v4.69.1.
19+
20+
Using an authentication broker on Linux enables you to simplify how your users authenticate with Microsoft Entra ID from your application, and take advantage of future functionality that protects Microsoft Entra ID refresh tokens from exfiltration and misuse.
21+
22+
To enable SSO in your WSL app using MSAL.NET, you must ensure the keychain is set up and unlocked, as MSAL uses `libsecret` to communicate with the keyring daemon.
23+
24+
## User sign-in experience
25+
26+
This video demonstrates the sign-in experience on brokered flows on Linux
27+
28+
![Demo of the Linux Login component component](../../media/linux/dotnet-msal-wsl.gif)
29+
30+
31+
## Update to the latest version of WSL
32+
33+
Ensure you have updated to the latest WSL release. The WAM Account Control dialog is supported in WSL versions 2.4.13 and above.
34+
35+
```powershell
36+
# To check what distros are available:
37+
wsl.exe --list --online
38+
39+
wsl.exe --install Ubuntu-22.04
40+
41+
# To check the WSL version:
42+
wsl --version
43+
44+
# To update WSL:
45+
wsl --update
46+
```
47+
48+
## Prerequisites
49+
50+
### .NET Installation
51+
Identity integration dependent on having dotnet 8 installed on the Linux distribution, and recommend installing via the [installation script](/dotnet/core/install/linux-scripted-manual#scripted-install).
52+
53+
```bash
54+
# Download the install script
55+
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
56+
chmod +x ./dotnet-install.sh
57+
./dotnet-install.sh --version latest
58+
59+
# To update the path if using bash (remember to reset your connection afterword):
60+
vi .bashrc
61+
export DOTNET_ROOT=~/.dotnet
62+
export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools
63+
```
64+
65+
### Package Dependencies
66+
67+
Install the following dependencies on your Linux platform:
68+
69+
- `libsecret-tools` is required to interface with the Linux keychain
70+
- `libx11-dev` package, where the `libx11` library is used to get the console window handle on Linux.
71+
72+
### [Ubuntu](#tab/ubuntudep)
73+
74+
To install on debian/Ubuntu based Linux distribution:
75+
76+
```bash
77+
sudo apt install libx11-6 libc++1 libc++abi1 libsecret-1-0 libwebkit2gtk-4.0-37 -y
78+
79+
#from Powershell, run
80+
wsl.exe --shutdown
81+
```
82+
83+
### [Red Hat Enterprise Linux](#tab/rheldep)
84+
85+
To install on Red Hat/Fedora based Linux distribution:
86+
87+
```bash
88+
sudo dnf install libx11-6 libc++1 libc++abi1 libsecret-1-0 libwebkit2gtk-4.0-37 -y
89+
90+
#from Powershell, run
91+
wsl.exe --shutdown
92+
```
93+
94+
---
95+
96+
> [!IMPORTANT]
97+
> In order for the keychain to work as intended, you should make sure you 1. install the dependencies, 2. Reboot/restart wsl, 3. Configure the keychain. Failure to do the steps in the correct order will result with the keychain missing the option for "Password Keychain".
98+
99+
100+
### Set up Keyring in WSL
101+
102+
MSAL uses `libsecret` on Linux. It's required to communicate with the `keyring` daemon. Users can use [Seahorse](https://wiki.gnome.org/Apps/Seahorse/) (a GNOME application for managing encryption keys and passwords) to manage the `keyring` contents through a Graphical User Interface (GUI).
103+
104+
On Debian-based distributions, you can install the package by running `sudo apt install seahorse` and then following these instructions:
105+
106+
1. Run `seahorse` in the terminal as a regular user (not as sudo)
107+
108+
![default keychain dialog](../../media/wam/wsl1.png)
109+
110+
2. In the top left corner, select **+** and create **Password** keyring.
111+
112+
![keychain dialog selecting password keyring](../../media/wam/wsl2.png)
113+
114+
3. Create a keyring named 'login'
115+
116+
![typing login to the prompt](../../media/wam/wsl3.png)
117+
118+
4. Set the password on the next dialog.
119+
![selecting a password and confirming](../../media/wam/wsl4.png)
120+
121+
5. Run `wsl.exe --shutdown` from your Windows Terminal.
122+
123+
6. Start a new WSL session and run the sample. You should be asked for the keyring password.
124+
125+
126+
## Run a Sample App
127+
128+
To use a broker on the Linux platform, make sure you set the `BrokerOptions` to `OperatingSystems.Linux` as shown in the below code snippet:
129+
130+
Reference the [Enable SSO in native Linux apps using MSAL.NET](./linux-dotnet-sdk.md) for information of how to configure the project.
131+
132+
To set up a test app, you use the sample app provided in [microsoft-authentication-library-for-dotnet](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) under the path [/tests/devapps/WAM/NetWSLWam/Class1.cs](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/tests/devapps/WAM/NetWSLWam/Class1.cs)
133+
134+
135+
To run the sample app:
136+
137+
```bash
138+
# Run From the root folder of microsoft-authentication-library-dotnet directory
139+
dotnet run --project tests/devapps/WAM/NetWSLWam/test.csproj
140+
```

0 commit comments

Comments
 (0)