fix merge conflicts

Author: SHERMANOUKO

.openpublishing.redirection.msal-python-conceptual.json

@@ -4,6 +4,11 @@
       "source_path_from_root": "/msal-python-conceptual/overview-msal",
       "redirect_url": "/msal-python-conceptual/index",
       "redirect_document_id": true
+    },
+    {
+      "source_path_from_root": "/msal-python-conceptual/best-practices.md",
+      "redirect_url": "/entra/msal/python",
+      "redirect_document_id": true
     }
   ]
 }

msal-python-conceptual/advanced/best-practices.md

@@ -7,19 +7,16 @@ manager: CelesteDG
 ms.service: msal
 ms.subservice: msal-python
 ms.topic: conceptual
-ms.date: 02/07/2024
+ms.date: 04/24/2025
 ms.author: dmwendia
 ms.reviewer: shermanouko, rayluo
 ---
 
 # Using MSAL Python with Web Account Manager
 
-If you are building a Windows application, you might consider simplifying how users authenticate with the help of an _authentication broker_ - the [Web Account Manager](/windows/uwp/security/web-account-manager) (WAM).
+If you are building a Windows application, you might consider simplifying how users authenticate with the help of an *authentication broker*. [Web Account Manager](/windows/uwp/security/web-account-manager) (WAM) is an authentication broker that works with MSAL Python. WAM is only available on Windows 10 and above, as well as Windows Server 2019 and above.
 
->[!NOTE]
->WAM is only available on Windows 10 and above, as well as Windows Server 2019 and above.
-
-To learn more about the benefits of using an authentication broker, refer to [What is a broker](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#what-is-a-broker) in the MSAL.NET documentation.
+For more information on the benefits of using an authentication broker, see [What is a broker](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#what-is-a-broker) in the MSAL.NET documentation.
 
 ## Usage
 
@@ -29,13 +26,9 @@ To use the broker, you will need to install the broker-related packages in addit
 pip install msal[broker]>=1.20,<2
 ```
 
->[!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.20,<2"`.
-
-Next, you will need to instantiate a new [`PublicClientApplication`](xref:msal.application.PublicClientApplication) and set `enable_broker_on_windows` to `True`. This will ensure that MSAL will try and communicate with WAM instead of popping up a new browser window.
+If broker-related packages aren't installed and you try to use the authentication broker, you will get the error *ImportError: You need to install dependency by: pip install "msal[broker]>=1.20,<2"*.
 
->[!IMPORTANT]
->If you are writing a cross-platform application, you will also need to use `enable_broker_on_mac`, as outlined in the [Using MSAL Python with an Authentication Broker on macOS](macos-broker.md) article.
+Next, instantiate a new [*PublicClientApplication*](xref:msal.application.PublicClientApplication) and set *enable_broker_on_windows* to `True`. This will ensure that MSAL will try and communicate with WAM instead of popping up a new browser window. If you are writing a cross-platform application, you will also need to use *enable_broker_on_mac*, as outlined in the [Using MSAL Python with an Authentication Broker on macOS](macos-broker.md) article.
 
 ```python
 from msal import PublicClientApplication
@@ -46,27 +39,26 @@ app = PublicClientApplication(
     enable_broker_on_windows=True)
 ```
 
-You can now acquire a token by calling [`acquire_token_interactive`](xref:msal.application.PublicClientApplication.acquire_token_interactive) and specifying a parent window handle through `parent_window_handle`:
+You can now acquire a token by calling [*acquire_token_interactive*](xref:msal.application.PublicClientApplication.acquire_token_interactive) and specifying a parent window handle through *parent_window_handle*:
 
 ```python
 result = app.acquire_token_interactive(["User.ReadBasic.All"],
          parent_window_handle=app.CONSOLE_WINDOW_HANDLE)
 ```
 
-A parent window handle is required by WAM to ensure that the dialog is shown correctly on top of the requesting window. MSAL does not infer this directly due to the fact that there are many variables that might influence what window WAM needs to bind to, and developers building applications are best suited to decide what window that should be.
+A parent window handle is required by WAM to ensure that the dialog is shown correctly on top of the requesting window. MSAL doesn't infer this directly due to the fact that there are many variables that might influence what window WAM needs to bind to, and developers building applications are best suited to decide what window that should be.
 
-For console applications, MSAL makes it easy by offering an out-of-the-box solution to getting the window handle for the terminal - [`CONSOLE_WINDOW_HANDLE`](xref:msal.application.PublicClientApplication.CONSOLE_WINDOW_HANDLE). For desktop applications, additional work with the Windows API might be required to [get the window handle](/windows/apps/develop/ui-input/retrieve-hwnd). Helper packages, like [pywin32](https://pypi.org/project/pywin32/) can help with API calls.
+For console applications, MSAL makes it easy by offering an out-of-the-box solution to getting the window handle for the terminal - [*CONSOLE_WINDOW_HANDLE*](xref:msal.application.PublicClientApplication.CONSOLE_WINDOW_HANDLE). For desktop applications, more work with the Windows API might be required to [get the window handle](/windows/apps/develop/ui-input/retrieve-hwnd). Helper packages, like [pywin32](https://pypi.org/project/pywin32/) can help with API calls.
 
 Before executing your application, make sure that you configure the redirect URL for the desktop app:
 
->[!IMPORTANT]
->To use the Windows broker, your application needs to have the correct redirect URL configured in the Azure Portal, in the shape of:
->
->```bash
->ms-appx-web://microsoft.aad.brokerplugin/YOUR_CLIENT_ID
->```
->
->If the redirect URL is not configured, you will get a `broker_error` similar to `(pii). Status: Response_Status.Status_ApiContractViolation, Error code: 3399614473, Tag: 557973642`.
+To use the Windows broker, your application needs to have the correct redirect URL configured in the Azure Portal, in the shape of:
+
+```bash
+ms-appx-web://microsoft.aad.brokerplugin/YOUR_CLIENT_ID
+```
+
+If the redirect URL isn't configured, you will get a *broker_error* similar to *(pii). Status: Response_Status.Status_ApiContractViolation, Error code: 3399614473, Tag: 557973642*.
 
 If configuration and instantiation was correct, once you run the application you should see the authentication broker kick in and allow the user to select the account they want to authenticate with.
 
@@ -78,32 +70,30 @@ Worth noting that if you switch to using broker-based authentication, if the use
 
 Depending on the authority specified when instantiating [`PublicClientApplication`](xref:msal.application.PublicClientApplication), the broker user interface may be different.
 
-### `/consumers`
+### /consumers
 
 Used for authenticating **only** with personal Microsoft accounts.
 
 ![WAM UI for consumers](../media/wam-consumers.png)
 
-### `/common`
+### /common
 
 Used for authenticating with personal Microsoft accounts as well as work and school accounts.
 
 ![WAM UI for personal and work accounts](../media/wam-common.png)
 
-### `/organizations`
+### /organizations
 
 Used for authenticating **only** with work and school accounts.
 
 ![WAM UI for work accounts only](../media/wam-organizations.png)
 
->[!NOTE]
->If `login_hint` is provided but the account is not yet registered in WAM, the hint will be automatically filled in the "Email or phone" field.
+If *login_hint* is provided, but the account isn't yet registered in WAM, the hint will be automatically filled in the *Email or phone* field.
 
-### `/TENANT_ID`
+### /TENANT_ID
 
 Used for authenticating **only** with work and school accounts within the specified tenant.
 
 ![WAM UI for tenant-specific accounts](../media/wam-tenant-specific.png)
 
->[!NOTE]
->If `login_hint` is provided but the account is not yet registered in WAM, the hint will be automatically filled in the "Email or phone" field.
+If *login_hint* is provided, but the account isn't yet registered in WAM, the hint will be automatically filled in the *Email or phone* field.

msal-python-conceptual/advanced/wam.md

@@ -7,7 +7,7 @@ manager: CelesteDG
 ms.service: msal
 ms.subservice: msal-python
 ms.topic: conceptual
-ms.date: 03/07/2024
+ms.date: 04/24/2025
 ms.author: shermanouko 
 ms.reviewer: dmwendia, rayluo
 ---
@@ -18,7 +18,7 @@ Microsoft Authentication Library (MSAL) Python supports two types of client appl
 
 ## Prerequisites
 
-This article doesn't go deep into defining what a public and confidential client applications are. Visit the identity platform docs to learn more about [public and confidential client applications](/entra/identity-platform/msal-client-applications).
+Understand the basic concepts of [public and confidential client applications](/entra/identity-platform/msal-client-applications).
 
 ## Instantiate an application
 
@@ -59,10 +59,10 @@ app = msal.ConfidentialClientApplication(
 
 ## Caching
 
-When you instantiate a client application, there are two parameters you can use to define your caching preferences. These parameters are: `token_cache` and `http_cache`.
+When you instantiate a client application, there are two parameters you can use to define your caching preferences. These parameters are: *token_cache* and *http_cache*.
 
-- `token_cache` sets the token cache used by the client application instance. By default, an in-memory cache is created and used. For more information, see [token caching in MSAL Python](../advanced/msal-python-token-cache-serialization.md).
-- `http_cache` is available in MSAL Python version 1.16+. This automatically caches some finite number of nontoken http responses, so that long-lived `PublicClientApplication` and `ConfidentialClientApplication` instances would be more performant and responsive in some situations. If the `http_cache` parameter isn't provided, MSAL uses an in-memory dict. If your app is a command-line app (CLI), you would want to persist your `http_cache` across different CLI runs. For more information, see the [reference guide](/python/api/msal/msal.application.clientapplication).
+- *token_cache* sets the token cache used by the client application instance. By default, an in-memory cache is created and used. For more information, see [token caching in MSAL Python](../advanced/msal-python-token-cache-serialization.md).
+- *http_cache* is available in MSAL Python version 1.16+. This automatically caches some finite number of nontoken http responses, so that long-lived *PublicClientApplication* and *ConfidentialClientApplication* instances would be more performant and responsive in some situations. If the *http_cache* parameter isn't provided, MSAL uses an in-memory dict. If your app is a command-line app (CLI), you would want to persist your *http_cache* across different CLI runs. For more information, see the [reference guide](/python/api/msal/msal.application.clientapplication).
 
 ## Next steps
 

msal-python-conceptual/getting-started/client-applications.md

@@ -7,7 +7,7 @@ manager: CelesteDG
 ms.service: msal
 ms.subservice: msal-python
 ms.topic: conceptual
-ms.date: 02/29/2024
+ms.date: 04/24/2025
 ms.author: shermanouko
 ms.reviewer: dmwendia, rayluo
 ---
@@ -31,7 +31,7 @@ pip install msal
 
 ## Identity concepts
 
-MSAL Python is part of the [Microsoft identity platform](/entra/identity-platform/v2-overview) ecosystem. It's important to familiarize yourself with the following concepts to effectively use MSAL Python to protect your applications and APIs:
+MSAL Python is part of the [Microsoft identity platform](/entra/identity-platform/v2-overview) ecosystem. Familiarize yourself with the following concepts to effectively use MSAL Python to protect your applications and APIs:
 
 - [Identity and access management](/entra/fundamentals/identity-fundamental-concepts)
 - [Authentication and authorization](/entra/identity-platform/authentication-vs-authorization)
@@ -43,7 +43,7 @@ MSAL Python is part of the [Microsoft identity platform](/entra/identity-platfor
 
 To use MSAL Python, register an application with the Microsoft identity platform. You'll need an Azure account with an active subscription. [Create a free account](https://signup.azure.com/) if you don't have one. You can register your app in a [customer tenant](/entra/external-id/customers/quickstart-tenant-setup) or [workforce tenant](/entra/identity-platform/scenario-web-app-sign-user-app-registration?tabs=python).
 
-Applications can use MSAL Python to acquire tokens for accessing protected APIs. Different app types acquire tokens using different auth flows. The supported app types include desktop applications, web applications, web APIs, and applications running on devices that don't have a browser (such as IoT devices). 
+Applications can use MSAL Python to acquire tokens for accessing protected APIs. Different app types acquire tokens using different auth flows. The supported app types include desktop applications, web applications, web APIs, and applications running on devices that don't have a browser (such as IoT devices).
 
 In MSAL Python, applications are categorized as follows:
 
@@ -90,7 +90,7 @@ Acquiring tokens with MSAL Python follows a three-step pattern. There will be so
         result = app.acquire_token_silent(["User.Read"], account=chosen)
     ```
 
-1. If there's no suitable token in the cache or you chose to skip the previous step, send a request to Microsoft Entra ID to get a token. There are different methods based on your client type and scenario, but for the purposes of the example we're showing how to use [`acquire_token_interactive`](xref:msal.application.PublicClientApplication.acquire_token_interactive), which prompts the user to provide their credentials.
+1. If there's no suitable token in the cache or you chose to skip the previous step, send a request to Microsoft Entra ID to get a token. There are different methods based on your client type and scenario, but for the purposes of the example we're showing how to use [*acquire_token_interactive*](xref:msal.application.PublicClientApplication.acquire_token_interactive), which prompts the user to provide their credentials.
 
    ```python
    if not result:
@@ -104,13 +104,21 @@ Acquiring tokens with MSAL Python follows a three-step pattern. There will be so
        print(result.get("correlation_id"))  # You may need this when reporting a bug
    ```
 
-1. Save the code into a Python file locally, such as `msaltest.py`.
+1. Save the code into a Python file locally, such as *msaltest.py*.
 1. Run the code by executing `python .\msalpytest.py`. The following visual shows the sign-in experience for this example.
 
     ![Example of an app prompting the user to sign in with their account](./media/basic-pca-app-prompt.gif)
 
 1. Once the authentication is completed and you closed the browser, you should be able to see the access token printed in the terminal.
 
+## Best practices for a robust enterprise ready application
+
+You can acquire a token for a protected Web API using MSAL Python. You also don't have to handle refreshing tokens yourself. However, to build robust, enterprise ready applications, you will need to do a bit more. For instance you'll want to:
+
+- [Handle exceptions](/azure/active-directory/develop/msal-handling-exceptions?tabs=python), both when you acquire a token, but also when you call the protected Web API. In particular, if your application runs in a Microsoft Entra tenant where the tenant admins have set [Conditional Access](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Conditional-Access-and-Claims-Challenges) policies to enforce Multiple Factor Authentication (MFA), you will need to handle a Claim challenge.
+
+- You might want to enable [Logging](/azure/active-directory/develop/msal-logging?tabs=python) to troubleshoot your application and help your users, while respecting their privacy and being compliant with GDPR.
+
 ## Samples
 
 There are several samples you can use to get started with MSAL Python.