Merge pull request #120 from SHERMANOUKO/freshness-updates-1

Update MSAL Python conceptual docs for freshness

Author: Dickson-Mwendia

.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/advanced/best-practices.md",
+      "redirect_url": "/entra/msal/python/",
+      "redirect_document_id": false
     }
   ]
 }

msal-python-conceptual/TOC.yml

@@ -39,8 +39,6 @@
     href: advanced/instance-metadata-caching.md
   - name: Client capabilities
     href: advanced/client-capabilities.md
-  - name: Best practices
-    href: advanced/best-practices.md
 
 - name: Additional resources
   items:

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

@@ -6,7 +6,7 @@ manager: CelesteDG
 ms.service: msal
 ms.subservice: msal-python
 ms.topic: conceptual
-ms.date: 03/06/2024
+ms.date: 04/24/2025
 ms.author: shermanouko
 ms.reviewer: dmwendia, rayluo
 # zone_pivot_groups: msal-python-acquire-token
@@ -122,9 +122,9 @@ else:
 
 ### Username and password
 
-It's also possible (but not recommended) to get a token with a [username and password](/entra/identity-platform/v2-oauth-ropc). MSAL Python provides the [`acquire_token_by_username_password`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-acquire-token-by-username-password) method for this use case.
+We don't recommend using this approach. It's also possible to get a token with a [username and password](/entra/identity-platform/v2-oauth-ropc). MSAL Python provides the [`acquire_token_by_username_password`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-acquire-token-by-username-password) method for this use case. It's not recommended because the application will be asking a user for their password directly, which is an insecure pattern.
 
-Microsoft does not recommend the username and password flow because the application will be asking a user for their password directly, which is an insecure pattern. In most scenarios, there exist more secure flows that you can use. Learn more in the [username and password authentication flow](../advanced/username-password-authentication.md) guidance.
+Microsoft doesn't recommend the username and password flow because the application will be asking a user for their password directly, which is an insecure pattern. In most scenarios, there exist more secure flows that you can use. Learn more in the [username and password authentication flow](../advanced/username-password-authentication.md) guidance.
 
 ```python
 result = app.acquire_token_by_username_password(
@@ -155,7 +155,7 @@ else:
 
 ### Acquire token on behalf of
 
-In the case of web apps or web APIs calling another downstream Web API in the name of the user, use the [On Behalf Of flow](/entra/identity-platform/v2-oauth2-on-behalf-of-flow) to acquire a token based on a user assertion (for example, SAML, JWT). The current app is a middle-tier service that was called with a token representing an end user. The current app can use such token, also known as a user assertion, to request another token to access downstream web API on behalf of that user. The middle-tier app has no user interaction to obtain consent. For information on gaining consent upfront for your middle-tier app, see the [documentation](/entra/identity-platform/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application).
+In the case of web apps or web APIs calling another downstream Web API in the name of the user, use the [On Behalf Of flow](/entra/identity-platform/v2-oauth2-on-behalf-of-flow) to acquire a token based on a user assertion. For example, SAML and JWT. The current app is a middle-tier service that was called with a token representing an end user. The current app can use such token, also known as a user assertion, to request another token to access downstream web API on behalf of that user. The middle-tier app has no user interaction to obtain consent. For information on gaining consent upfront for your middle-tier app, see the [documentation](/entra/identity-platform/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application).
 
 Here's an example of code that acquires an access token using the [`acquire_token_on_behalf_of`](/python/api/msal/msal.application.confidentialclientapplication#msal-application-confidentialclientapplication-acquire-token-on-behalf-of) method.
 
@@ -183,11 +183,11 @@ def get(self, request): # a web service endpoint receiving a request
         print(result.get("error")) 
 ```
 
-## Acquire token by authorization code flow
+### Acquire token by authorization code flow
 
 For web apps authenticating in the name of a user, acquire tokens through [authorization code](/entra/identity-platform/v2-oauth2-auth-code-flow) after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application that lets the user sign-in and access web APIs for this particular user.
 
-You'll first need to initiate auth code flow using the [`initiate_auth_code_flow`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-initiate-auth-code-flow). This method takes in among other parameters a redirect URI and state string. The value of the state parameter is also included in token response. If this value is absent, MSAL Python will automatically generate one internally. The redirect URI provided must match the redirect URI registered in the Microsoft Entra admin center. This method returns the auth code flow that is a dictionary containing auth_uri and a state. The auth_uri is the URL that the user needs to visit to sign in.
+You'll first need to initiate auth code flow using the [`initiate_auth_code_flow`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-initiate-auth-code-flow). This method takes in among other parameters a redirect URI and state string. The value of the state parameter is also included in token response. If this value is absent, MSAL Python will automatically generate one internally. The redirect URI provided must match the redirect URI registered in the Microsoft Entra admin center. This method returns the auth code flow that is a dictionary containing `auth_uri` and `state`. The `auth_uri` is the URL that the user needs to visit to sign in.
 
 ```python
 flow = app.initiate_auth_code_flow(
@@ -202,7 +202,7 @@ session["auth_flow"] = flow
 # At this point, the app should guide the user to visit the auth ur (session["auth_flow"]["auth_uri"])
 ```
 
-The response from visiting the auth_uri endpoints is used in the [`acquire_token_by_auth_code_flow`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-acquire-token-by-auth-code-flow) method. The state is a unique identifier that you can use to verify the response from the authorization server. The user should consent to scopes during sign-in.
+The response from visiting the auth uri endpoints is used in the [`acquire_token_by_auth_code_flow`](/python/api/msal/msal.application.clientapplication#msal-application-clientapplication-acquire-token-by-auth-code-flow) method. The state is a unique identifier that you can use to verify the response from the authorization server. The user should consent to scopes during sign-in.
 
 ```python
 # The uth_response value from visiting the auth_uri endpoint is passed as a query string
@@ -220,6 +220,6 @@ except ValueError:  # Usually caused by CSRF
 
 ## MSAL Python token caching
 
-Both public and confidential client applications support token caching, handled direct by MSAL Python. Applications should try to get a token from the cache first before relying on any other means. Take a look at the [recommended token acquisition pattern](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python) to learn more.
+Both public and confidential client applications support token caching, handled direct by MSAL Python. Applications should try to get a token from the cache first before relying on any other means. For more information, see [recommended token acquisition pattern](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python).
 
 To be able to persist the cache, the developers need to configure the [token cache serialization](/azure/active-directory/develop/msal-python-token-cache-serialization) logic.