diff --git a/msal-python-conceptual/TOC.yml b/msal-python-conceptual/TOC.yml index 12eb253..2ce2498 100644 --- a/msal-python-conceptual/TOC.yml +++ b/msal-python-conceptual/TOC.yml @@ -11,8 +11,12 @@ items: - name: Using MSAL Python with Web Account Manager href: advanced/wam.md - - name: Using MSAL Python with Authentication Brokers on macOS + - name: Using MSAL Python with Auth Brokers on macOS href: advanced/macos-broker.md + - name: Using MSAL Python with an Auth Broker on Linux + href: advanced/linux-broker-py.md + - name: Using MSAL Python with Windows Subsystem for Linux + href: advanced/linux-broker-py-wsl.md - name: Migrate to MSAL Python href: advanced/migrate-python-adal-msal.md - name: Logging diff --git a/msal-python-conceptual/advanced/linux-broker-py-wsl.md b/msal-python-conceptual/advanced/linux-broker-py-wsl.md new file mode 100644 index 0000000..9b48252 --- /dev/null +++ b/msal-python-conceptual/advanced/linux-broker-py-wsl.md @@ -0,0 +1,182 @@ +--- +title: Using MSAL Python with Windows Subsystem for Linux +description: Learn how to integrate Microsoft Entra ID authentication in WSL apps using MSAL Python and the Microsoft Single Sign-on for Linux broker. +author: ploegert +ms.author: jploegert +ms.service: msal +ms.topic: how-to +ms.date: 05/08/2025 +--- + +# Enable SSO in WSL (Windows Subsystem for Linux) apps using MSAL Python and WAM + +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`. + +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). + +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. + +To enable SSO in your WSL app using MSAL Python, you must ensure the keychain is set up and unlocked, as MSAL uses `libsecret` to communicate with the keyring daemon. + +## WSL Authentication Flow Example + +In a situation where you have a WSL app that needs to authenticate with Microsoft Entra ID, the authentication flow for an interactive request would look like this: + +![Auth Flow from within WSL](../media/python-msal-wsl.gif) + +## Update to the latest version of WSL + +Ensure you have updated to the latest WSL release. The WAM Account Control dialog is supported in WSL versions 2.4.13 and above. + +```powershell +# To check what distros are available: +wsl.exe --list --online + +wsl.exe --install Ubuntu-22.04 + +# To check the WSL version: +wsl --version + +# To update WSL: +wsl --update +``` + +## Linux Package Dependencies + +Install the following dependencies on your Linux platform: + +- `libsecret-tools` is required to interface with the Linux keychain + +### [Ubuntu](#tab/ubuntudep) + +To install on debian/Ubuntu based Linux distribution: + +```bash +sudo apt install libsecret-1-0 -y + +#from Powershell, run +wsl.exe --shutdown +``` + +### [Red Hat Enterprise Linux](#tab/rheldep) + +To install on Red Hat/Fedora based Linux distribution: + +```bash +sudo dnf install libsecret-1-0 -y + +#from Powershell, run +wsl.exe --shutdown +``` + +--- + +> [!IMPORTANT] +> 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". + +## Set up Keyring in WSL + +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). + +On Debian-based distributions, you can install the package by running `sudo apt install seahorse` and then following these instructions: + +1. Run `seahorse` in the terminal as a regular user (not as sudo) + + ![default keychain dialog](../media/wsl1.png) + +2. In the top left corner, select **+** and create **Password** keyring. + + ![keychain dialog selecting password keyring](../media/wsl2.png) + +3. Create a keyring named 'login' + + ![typing login to the prompt](../media/wsl3.png) + +4. Set the password on the next dialog. + ![selecting a password and confirming](../media/wsl4.png) + +5. Run `wsl.exe --shutdown` from your Windows Terminal. + +6. Start a new WSL session and run the sample. You should be asked for the keyring password. + +## Run a Sample App + +To use a broker on the Linux platform, make sure you set the `BrokerOptions` to `OperatingSystems.Linux` as shown in the below code snippet: + +Reference the [Enable SSO in native Linux apps using MSAL Python](./linux-broker-py.md) for information of how to configure the project. + +### **Python Dependencies** + +To use the broker, you will need to install the broker-related packages in addition to the core MSAL from PyPI: + +```python +pip install msal[broker]>=1.31,<2 +pip install pymsalruntime +``` + +### Run the Sample App + +Once configured, you can call `acquire_token_interactive` to acquire a token. Save the following as `wsl_broker.py`: + +```python +import sys # For simplicity, we'll read config file from 1st CLI param sys.argv[1] +import json +import logging +import requests +import msal + +# Optional logging +# logging.basicConfig(level=logging.DEBUG) + +var_authority = "https://login.microsoftonline.com/common" +var_client_id = " your-client-id-here" # Replace with your app's client ID +var_username = "your-username-here" # Replace with your username, e.g., " +var_scope = ["User.ReadBasic.All"] + +# Create a preferably long-lived app instance which maintains a token cache (Default cache is in memory only). +app = msal.PublicClientApplication( + var_client_id, + authority=var_authority, + enable_broker_on_windows=True, + enable_broker_on_wsl=True + ) + +# The pattern to acquire a token looks like this. +result = None + +# Firstly, check the cache to see if this end user has signed in before +accounts = app.get_accounts(username=var_username) +if accounts: + logging.info("Account(s) exists in cache, probably with token too. Let's try.") + result = app.acquire_token_silent(var_scope, account=accounts[0]) + +if not result: + logging.info("No suitable token exists in cache. Let's get a new one from AAD.") + + result = app.acquire_token_interactive(var_scope,parent_window_handle=app.CONSOLE_WINDOW_HANDLE) + +if "access_token" in result: + print("Access token is: %s" % result['access_token']) + +else: + print(result.get("error")) + print(result.get("error_description")) + print(result.get("correlation_id")) # You may need this when reporting a bug + if 65001 in result.get("error_codes", []): # Not mean to be coded programatically, but... + # AAD requires user consent for U/P flow + print("Visit this to consent:", app.get_authorization_request_url(config["scope"])) +``` + +### Run the Sample + +Run the sample app using the following command: + +```bash +python wsl_broker.py +``` + +You should see a prompt to: + +- enter your username/credentials +- enter your keyring password +- then the app will acquire a token and print it to the console diff --git a/msal-python-conceptual/advanced/linux-broker-py.md b/msal-python-conceptual/advanced/linux-broker-py.md new file mode 100644 index 0000000..26660fe --- /dev/null +++ b/msal-python-conceptual/advanced/linux-broker-py.md @@ -0,0 +1,210 @@ +--- +title: Using MSAL Python with an Auth Broker on Linux +description: MSAL is able to call Microsoft Single Sign-on for Linux, which is a component that ships as a dependency of Intune Portal. This component acts as an authentication broker allowing the users of your app to benefit from integration with accounts known to the broker. +author: ploegert +ms.author: jploegert +ms.service: msal +ms.topic: how-to +ms.date: 06/03/2025 +--- + +# Enable SSSO in native Linux using MSAL Python + +Microsoft Authentication Library (MSAL) is a Software Development Kit (SDK) that enables apps to call the Microsoft Single Sign-on to Linux broker, 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`. + +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. + +The broker is also bundled as a dependency of applications developed by Microsoft (such as [Company Portal](/mem/intune-service/user-help/enroll-device-linux))). An example of installation of the broker being installed is when a Linux computer is enrolled into a company's device fleet via an endpoint management solution like [Microsoft Intune](/mem/intune/fundamentals/what-is-intune). + +## What is a broker + +An authentication broker is an application that runs on a user’s machine that manages the authentication handshakes and token maintenance for connected accounts. The Linux operating system uses the Microsoft single sign-on for Linux as its authentication broker. It has many benefits for developers and customers alike, including: + +- **Enables Single Sign-On**: enables apps to simplify how users authenticate with Microsoft Entra ID and protects Microsoft Entra ID refresh tokens from exfiltration and misuse +- **Enhanced security.** Many security enhancements are delivered with the broker, without needing to update the application logic. +- **Feature support.** With the help of the broker developers can access rich OS and service capabilities. +- **System integration.** Applications that use the broker plug-and-play with the built-in account picker, allowing the user to quickly pick an existing account instead of reentering the same credentials over and over. +- **Token Protection.** Microsoft single sign-on for Linux ensures that the refresh tokens are device bound. + +## How to opt in to use broker? + +1. In the MSAL Python library, we've introduced the `enable_broker_on_linux` flag, which enables the broker on both WSL and standalone Linux. + - If your goal is to enable broker support solely on WSL for Azure CLI, you can consider modifying the Azure CLI app code to activate the `enable_broker_on_wsl` flag exclusively on WSL. + - If you are writing a cross-platform application, you will also need to use `enable_broker_on_windows`, as outlined in the [Using MSAL Python with Web Account Manager](wam.md) article. + - You can set any combination of the following opt-in parameters to true: + +| Opt-in flag | If app will run on | App has registered this as a Desktop platform redirect URI in Azure Portal | +| ------------------------ | --------------------------------- | -------------------------------------------------------------------------------- | +| enable_broker_on_windows | Windows 10+ | ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id | +| enable_broker_on_wsl | WSL | ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id | +| enable_broker_on_mac | Mac with Company Portal installed | msauth.com.msauth.unsignedapp://auth | +| enable_broker_on_linux | Linux with Intune installed | `https://login.microsoftonline.com/common/oauth2/nativeclient` (MUST be enabled) | + +2. Your application needs to support broker-specific redirect URIs. For `Linux` specifically, the URL for the redirect URI must be: + + ```text + https://login.microsoftonline.com/common/oauth2/nativeclient + ``` + +3. To use the broker, you will need to install the broker-related packages in addition to the core MSAL from PyPI: + + ```python + pip install msal[broker]>=1.31,<2 + pip install pymsalruntime + ``` + +4. Once configured, you can call `acquire_token_interactive` to acquire a token. + + ```python + result = app.acquire_token_interactive(["User.ReadBasic.All"], + parent_window_handle=app.CONSOLE_WINDOW_HANDLE) + ``` + +## Parameters for broker support + +The following parameters are available to configure broker support in MSAL Python. These parameters can be passed to the `PublicClientApplication` constructor or to the `acquire_token_interactive` method. + +| Parameters: | Type | Description | +|-------------|------|-------| +| enable_broker_on_windows | `boolean` | This setting is only effective if your app is running on Windows 10+. This parameter defaults to None, which means MSAL will not utilize a broker.

`New in MSAL Python 1.25.0.` | +| enable_broker_on_wsl | `boolean` | This setting is only effective if your app is running on WSL. This parameter defaults to None, which means MSAL will not utilize a broker.

`New in MSAL Python 1.25.0`. | +| enable_broker_on_mac | `boolean` | This setting is only effective if your app is running on Mac with Company Portal installed. This parameter defaults to None, which means MSAL will not utilize a broker.

`New in MSAL Python 1.31.0`.| +| enable_broker_on_linux | `boolean` | This setting is only effective if your app is running on Linux with Intune installed. This parameter defaults to None, which means MSAL will not utilize a broker.

`New in MSAL Python 1.33.0`. | +| parent_window_handle | `int` | OPTIONAL

+ +### Notes regarding parent_window_handle + +The `parent_window_handle` parameter is required even though on Linux it is not used. For GUI applications, the login prompt location will be determined ad-hoc and currently cannot be bound to a specific window. In a future update, this parameter will be used to determine the _actual_ parent window. + +| Condition | Description | +|---|---| +|App does not want to utilize a broker|no need to specify a parent_window_handle| +|App opts to use a broker|parent_window_handle is required| +|App is a GUI app running on Windows or Mac system|required to provide its window handle, so that the sign-in window will pop up on top of your window| +|App is a console app running on Windows or Mac system|can use a placeholder `PublicClientApplication.CONSOLE_WINDOW_HANDLE`| +|App is intended to be a cross-platform application| App needs to use `enable_broker_on_windows`, as outlined in the [Using MSAL Python with Web Account Manager](wam.md) article.| + +## The fallback behaviors of MSAL Python’s broker support + +MSAL will either error out, or silently fallback to non-broker flows. + +1. MSAL will ignore the enable_broker_… and bypass broker on those auth flows that are known to be NOT supported by broker. This includes ADFS, B2C, etc.. For other “could-use-broker” scenarios, please see below. + +2. MSAL errors out when app developer opted-in to use broker but a direct dependency “mid-tier” package is not installed. Error message guides app developer to declare the correct dependency msal[broker]. We error out here because the error is actionable to app developers. + +3. MSAL silently “deactivates” the broker and fallback to non-broker, when opted-in, dependency installed yet failed to initialize. We anticipate this would happen on a device whose OS is too old or the underlying broker component is somehow unavailable. There is not much an app developer or the end user can do here. Eventually, the conditional access policy shall force the user to switch to a different device. + +4. MSAL errors out when broker is opted in, installed, initialized, but subsequent token request(s) failed. + +>[!IMPORTANT] +>If broker-related packages are not installed and you will try to use the authentication broker, you will get an error: `ImportError: You need to install dependency by: pip install "msal[broker]>=1.31,<2"`. + +>[!NOTE] +>The `parent_window_handle` parameter is required even though on Linux it is not used. For GUI applications, the login prompt location will be determined ad-hoc and currently cannot be bound to a specific window. In a future update, this parameter will be used to determine the _actual_ parent window. + +## Token caching + +The authentication broker handles refresh and access token caching. You do not need to set up custom caching. + +## Building an example app + +You can find a sample app that demonstrates how to use MSAL Python with the authentication broker on Linux in the [MSAL Python GitHub repository](https://github.com/AzureAD/microsoft-authentication-library-for-python/). The sample app is located in the `samples/console_app` directory and includes examples of how to use the broker for authentication. + +### **App Registration** + +Update your App registration in the Azure portal to include the broker-specific redirect URI for Linux: + +```text +https://login.microsoftonline.com/common/oauth2/nativeclient +``` + +### **Linux Dependencies** + +First, check if you have python3 installed on your Linux distribution. + +```bash +python3 --version +``` + +If not, install it using the package manager for your distribution. + +#### [Ubuntu](#tab/ubuntudep) + +To install on debian/Ubuntu based Linux distribution: + +```bash +sudo apt install python3 python3-pip -y +``` + +#### [Red Hat Enterprise Linux](#tab/rheldep) + +To install on Red Hat/Fedora based Linux distribution: + +```bash +sudo dnf install python3 python3-pip -y +``` + +--- + +### **Python Dependencies** + +To use the broker, you will need to install the broker-related packages in addition to the core MSAL from PyPI: + +```python +pip install msal[broker]>=1.31,<2 +pip install pymsalruntime +``` + +### Create Project +Once configured, you can call `acquire_token_interactive` to acquire a token. + +```python +import sys # For simplicity, we'll read config file from 1st CLI param sys.argv[1] +import json +import logging +import requests +import msal + +# Optional logging +# logging.basicConfig(level=logging.DEBUG) + +var_authority = "https://login.microsoftonline.com/common" +var_client_id = "your-client-id-here" # Replace with your app's client ID +var_username = "your-username-here" # Replace with your username, e.g., " +var_scope = ["User.ReadBasic.All"] +# Removed unused variable to avoid confusion + + +# Create a preferably long-lived app instance which maintains a token cache (Default cache is in memory only). +app = msal.PublicClientApplication( + var_client_id, + authority=var_authority, + enable_broker_on_windows=True, + enable_broker_on_wsl=True + ) + +# The pattern to acquire a token looks like this. +result = None + +# Firstly, check the cache to see if this end user has signed in before +accounts = app.get_accounts(username=var_username) +if accounts: + logging.info("Account(s) exists in cache, probably with token too. Let's try.") + result = app.acquire_token_silent(var_scope, account=accounts[0]) + +if not result: + logging.info("No suitable token exists in cache. Let's get a new one from AAD.") + + result = app.acquire_token_interactive(var_scope,parent_window_handle=app.CONSOLE_WINDOW_HANDLE) + +if "access_token" in result: + print("Access token is: %s" % result['access_token']) + +else: + print(result.get("error")) + print(result.get("error_description")) + print(result.get("correlation_id")) # You may need this when reporting a bug + if 65001 in result.get("error_codes", []): # Not mean to be coded programatically, but... + # AAD requires user consent for U/P flow + print("Visit this to consent:", app.get_authorization_request_url(config["scope"])) +``` diff --git a/msal-python-conceptual/advanced/macos-broker.md b/msal-python-conceptual/advanced/macos-broker.md index 50445bd..592cf29 100644 --- a/msal-python-conceptual/advanced/macos-broker.md +++ b/msal-python-conceptual/advanced/macos-broker.md @@ -1,5 +1,5 @@ --- -title: Using MSAL Python with an Authentication Broker on macOS +title: Using MSAL Python with an Auth Broker on macOS description: "Using an authentication broker on macOS enables you to simplify how your users authenticate with Microsoft Entra ID from your application, as well as take advantage of advanced functionality such as token binding, protecting any issued tokens from exfiltration and misuse." author: localden manager: CelesteDG diff --git a/msal-python-conceptual/media/python-msal-wsl.gif b/msal-python-conceptual/media/python-msal-wsl.gif new file mode 100644 index 0000000..2a4a724 Binary files /dev/null and b/msal-python-conceptual/media/python-msal-wsl.gif differ diff --git a/msal-python-conceptual/media/wsl1.png b/msal-python-conceptual/media/wsl1.png new file mode 100644 index 0000000..f24f6a1 Binary files /dev/null and b/msal-python-conceptual/media/wsl1.png differ diff --git a/msal-python-conceptual/media/wsl2.png b/msal-python-conceptual/media/wsl2.png new file mode 100644 index 0000000..122ef6b Binary files /dev/null and b/msal-python-conceptual/media/wsl2.png differ diff --git a/msal-python-conceptual/media/wsl3.png b/msal-python-conceptual/media/wsl3.png new file mode 100644 index 0000000..5541af4 Binary files /dev/null and b/msal-python-conceptual/media/wsl3.png differ diff --git a/msal-python-conceptual/media/wsl4.png b/msal-python-conceptual/media/wsl4.png new file mode 100644 index 0000000..f3edb54 Binary files /dev/null and b/msal-python-conceptual/media/wsl4.png differ diff --git a/msal-python-conceptual/media/wsl5.png b/msal-python-conceptual/media/wsl5.png new file mode 100644 index 0000000..537ebf9 Binary files /dev/null and b/msal-python-conceptual/media/wsl5.png differ diff --git a/msal-python-conceptual/media/wsl6.png b/msal-python-conceptual/media/wsl6.png new file mode 100644 index 0000000..0e5e84e Binary files /dev/null and b/msal-python-conceptual/media/wsl6.png differ