[Identity] Documentation updates (#32691)

This fleshes out WAM/broker related documentation for
the identity libraries.

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>

sdk/identity/azure-identity-broker/README.md

@@ -2,37 +2,71 @@
 
 # Azure Identity Broker plugin for Python
 
+This package extends the [Azure Identity][azure_identity] library by providing supplemental credentials for authenticating via an authentication 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. Currently, only the Windows authentication broker, Web Account Manager (WAM), is supported.
+
+[Source code][source_code] | [Package (PyPI)][azure_identity_broker] | [API reference documentation][ref_docs] | [Microsoft Entra ID documentation][entra_id]
+
 ## Getting started
 
 ### Install the package
 
-Install the Azure Identity Broker plugin for Python with [pip](https://pypi.org/project/pip/):
+Install the Azure Identity Broker plugin for Python with [pip][pip]:
 
 ```bash
 pip install azure-identity-broker
 ```
 
+## Key concepts
+
+This package enables broker support via `InteractiveBrowserBrokerCredential` which is a subclass of the `InteractiveBrowserCredential` of the Azure Identity library.
+
+### Parent window handles
+
+When authenticating interactively via `InteractiveBrowserBrokerCredential`, a parent window handle is required to ensure that the authentication dialog is shown correctly over the requesting window. In the context of graphical user interfaces on devices, a window handle is a unique identifier that the operating system assigns to each window. For the Windows operating system, this is an integer value that serves as a reference to a specific window.
+
+## Microsoft account (MSA) passthrough
+
+Microsoft accounts (MSA) are personal accounts created by users to access Microsoft services. MSA- passthrough is a legacy configuration which enables users to get tokens to resources which normally do not accept MSA logins. This is only available to first-party applications. Users authenticating with an application that is configured to use MSA-passthrough can set `enable_msa_passthrough` to `True` inside `InteractiveBrowserBrokerCredential` to allow these personal accounts to be listed by WAM.
 
 ## Examples
 
-Now you can create `azure.identity.broker.InteractiveBrowserBrokerCredential` and `azure.identity.broker.UsernamePasswordBrokerCredential` with broker support.
+### Authenticate with `InteractiveBrowserBrokerCredential`
 
-```python
+This example demonstrates using `InteractiveBrowserBrokerCredential` as a broker-enabled credential for authenticating with the `BlobServiceClient` from the [azure-storage-blob][azure_storage_blob] library. Here, the `win32gui` package is used to get the current window.
 
+```python
 import win32gui
 from azure.identity.broker import InteractiveBrowserBrokerCredential
+from azure.storage.blob import BlobServiceClient
 
 # Get the handle of the current window
 current_window_handle = win32gui.GetForegroundWindow()
 
-credential = InteractiveBrowserBrokerCredential(allow_broker=True, parent_window_handle=current_window_handle)
+credential = InteractiveBrowserBrokerCredential(parent_window_handle=current_window_handle)
+client = BlobServiceClient(account_url, credential=default_credential)
 ```
 
-
 ## Troubleshooting
 
-This client raises exceptions defined in [Azure Core](https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python).
+See the Azure Identity [troubleshooting guide][troubleshooting_guide] for details on how to diagnose various failure scenarios.
+
+## Next steps
+
+### Client library support
+
+Client and management libraries listed on the [Azure SDK release page](https://azure.github.io/azure-sdk/releases/latest/python.html) that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is linked from the release page.
+
+### Known issues
 
+This library doesn't support [Azure AD B2C][b2c].
+
+For other open issues, refer to the library's [GitHub repository](https://github.com/Azure/azure-sdk-for-python/issues?q=is%3Aopen+is%3Aissue+label%3AAzure.Identity).
+
+### Provide feedback
+
+If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-python/issues).
 
 ## Contributing
 
@@ -41,3 +75,14 @@ This project welcomes contributions and suggestions.  Most contributions require
 When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+<!-- LINKS -->
+[azure_identity]: https://pypi.org/project/azure-identity
+[azure_identity_broker]: https://pypi.org/project/azure-identity-broker
+[azure_storage_blob]: https://pypi.org/project/azure-storage-blob
+[b2c]: https://learn.microsoft.com/azure/active-directory-b2c/overview
+[entra_id]: https://learn.microsoft.com/entra/identity/
+[pip]: https://pypi.org/project/pip
+[ref_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-identity-broker/latest/index.html
+[source_code]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity-broker
+[troubleshooting_guide]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md

sdk/identity/azure-identity/README.md

@@ -6,7 +6,7 @@ The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft
 | [Package (PyPI)](https://pypi.org/project/azure-identity/)
 | [Package (Conda)](https://anaconda.org/microsoft/azure-identity/)
 | [API reference documentation][ref_docs]
-| [Microsoft Entra ID documentation](https://learn.microsoft.com/azure/active-directory/)
+| [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity/)
 
 ## Getting started
 
@@ -20,7 +20,7 @@ pip install azure-identity
 
 ### Prerequisites
 
-- An [Azure subscription](https://azure.microsoft.com/free/)
+- An [Azure subscription](https://azure.microsoft.com/free/python)
 - Python 3.7 or a recent version of Python 3 (this library doesn't support end-of-life versions)
 
 ### Authenticate during local development
@@ -318,6 +318,10 @@ Token caching is a feature provided by the Azure Identity library that allows ap
 
 The Azure Identity library offers both in-memory and persistent disk caching. For more details, see the [token caching documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TOKEN_CACHING.md).
 
+## Brokered authentication
+
+An authentication broker is an application that runs on a user’s machine and manages the authentication handshakes and token maintenance for connected accounts. Currently, only the Windows Web Account Manager (WAM) is supported. To enable support, use the [`azure-identity-broker`][azure_identity_broker] package. For details on authenticating using WAM, see the [broker plugin documentation][azure_identity_broker_readme].
+
 ## Troubleshooting
 
 See the [troubleshooting guide][troubleshooting_guide] for details on how to diagnose various failure scenarios.
@@ -373,6 +377,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 [azure_cli]: https://learn.microsoft.com/cli/azure
 [azure_developer_cli]:https://aka.ms/azure-dev
 [azure_core_transport_doc]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport
+[azure_identity_broker]: https://pypi.org/project/azure-identity-broker
+[azure_identity_broker_readme]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity-broker
 [azure_eventhub]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/eventhub/azure-eventhub
 [azure_keyvault_secrets]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/azure-keyvault-secrets
 [azure_storage_blob]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/storage/azure-storage-blob

sdk/identity/azure-identity/TROUBLESHOOTING.md

@@ -294,17 +294,17 @@ Get-AzAccessToken -ResourceUrl "https://management.core.windows.net"
 |---|---|---|
 |The current credential is not configured to acquire tokens for tenant <tenant ID>|<p>The application must configure the credential to allow token acquisition from the requested tenant.|Make one of the following changes in your app:<ul><li>Add the requested tenant ID to `additionally_allowed_tenants` on the credential options.</li><li>Add `*` to `additionally_allowed_tenants` to allow token acquisition for any tenant.</li></ul></p><p>This exception was added as part of a breaking change to multi-tenant authentication in version 1.11.0. Users experiencing this error after upgrading can find details on the change and migration in [BREAKING_CHANGES.md](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/BREAKING_CHANGES.md#1110).</p> |
 
-## Troubleshoot WAM+MSA login issues
+## Troubleshoot Web Account Manager (WAM) and Microsoft account (MSA) login issues
 
-When using `InteractiveBrowserCredential`, by default, only the Microsoft Entra account is listed:
+When using `InteractiveBrowserBrokerCredential` via the `azure-identity-broker` package on Windows, only Microsoft Entra accounts are listed by default:
 
 ![MSA Microsoft Entra only](./images/MSA1.png)
 
-If you choose "Use another account" and type in an MSA outlook.com account, it fails:
+If you choose "Use another account", and type in an MSA outlook.com account, it fails:
 
 ![Fail on use another account](./images/MSA2.png)
 
-Since azure-identity 1.15.0b1, you can set `enable_msa_passthrough`` to `True`, and MSA outlook.com accounts that are logged in to Windows are automatically listed:
+When constructing the credential, you can set the `enable_msa_passthrough` keyword argument to `True`, and MSA outlook.com accounts that are logged in to Windows are automatically listed:
 
 ![Enable MSA](./images/MSA3.png)
 

sdk/identity/azure-identity/samples/README.md

@@ -12,7 +12,7 @@ urlFragment: identity-samples
 
 ## Prerequisites
 
-You must have an [Azure subscription](https://azure.microsoft.com/free) and an
+You must have an [Azure subscription](https://azure.microsoft.com/free/python) and an
 [Azure Key Vault](https://azure.microsoft.com/services/key-vault/) to run
 these samples. You can create a Key Vault in the
 [Azure Portal](https://portal.azure.com/#create/Microsoft.KeyVault) or with the