# 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][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 handle 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 don't accept MSA logins. This feature 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.
## Redirect URIs
Microsoft Entra applications rely on redirect URIs to determine where to send the authentication response after a user has logged in. To enable brokered authentication through WAM, a redirect URI matching the following pattern should be registered to the application:
```
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}
```
## Examples
### Authenticate with `InteractiveBrowserBrokerCredential`
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` module from the `pywin32` 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(parent_window_handle=current_window_handle)
client = BlobServiceClient(account_url, credential=credential)
```
To bypass the account selection dialog and use the default broker account, set the `use_default_broker_account` argument to `True`. The credential will attempt to silently use the default broker account. If using the default account fails, the credential will fall back to interactive authentication.
```python
credential = InteractiveBrowserBrokerCredential(
parent_window_handle=current_window_handle,
use_default_broker_account=True
)
```
## Troubleshooting
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
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
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
# Release History
## 1.2.0 (2024-10-08)
### Other Changes
- Stable release for the Proof-of-Possession (PoP) token support to `InteractiveBrowserBrokerCredential`.
## 1.2.0b1 (2024-09-20)
### Features Added
- `InteractiveBrowserBrokerCredential` now implements the `SupportsTokenInfo` protocol. It now has a `get_token_info` method which returns an `AccessTokenInfo` object. The `get_token_info` method is an alternative method to `get_token` that improves support for more complex authentication scenarios.
- Added Proof-of-Possession (PoP) token support to `InteractiveBrowserBrokerCredential`.
## 1.1.0 (2024-04-09)
### Features Added
- `InteractiveBrowserBrokerCredential` now supports a `use_default_broker_account` property to enable the use of the currently logged in operating system account for authentication rather than prompting for a credential.
- Added `enable_support_logging` as a keyword argument to `InteractiveBrowserBrokerCredential`. This allows additional support logging which may contain PII.
### Other Changes
- Python 3.7 is no longer supported. Please use Python version 3.8 or later.
- Bumped minimum dependency on `azure-identity` to `1.15.0`.
## 1.0.0 (2023-11-07)
### Features Added
- `enable_broker` is always on if running on Windows. Automatically fall back into non-broker mode if running on MacOS or Linux.
### Breaking Changes
- Removed `UsernamePasswordBrokerCredential`
## 1.0.0b1 (2023-10-12)
### Features Added
- Added `azure.identity.broker.InteractiveBrowserBrokerCredential`
and `azure.identity.broker.UsernamePasswordBrokerCredential` which have broker support.
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity-broker",
"name": "azure-identity-broker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "azure, azure sdk",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/8a/c7/28e9835cc2611bb9066fc4068a7081123b09e60b632f8d347f70d8b7134d/azure_identity_broker-1.2.0.tar.gz",
"platform": null,
"description": "\n\n# Azure Identity Broker plugin for Python\n\nThis package extends the [Azure Identity][azure_identity] library by providing supplemental credentials for authenticating via an authentication broker.\n\nAn authentication broker is an application that runs on a user\u2019s machine that manages the authentication handshakes and token maintenance for connected accounts. Currently, only the Windows authentication broker, Web Account Manager (WAM), is supported.\n\n[Source code][source_code] | [Package (PyPI)][azure_identity_broker] | [API reference documentation][ref_docs] | [Microsoft Entra ID documentation][entra_id]\n\n## Getting started\n\n### Install the package\n\nInstall the Azure Identity Broker plugin for Python with [pip][pip]:\n\n```bash\npip install azure-identity-broker\n```\n\n## Key concepts\n\nThis package enables broker support via `InteractiveBrowserBrokerCredential` which is a subclass of the `InteractiveBrowserCredential` of the Azure Identity library.\n\n### Parent window handles\n\nWhen 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 handle is an integer value that serves as a reference to a specific window.\n\n## Microsoft account (MSA) passthrough\n\nMicrosoft 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 don't accept MSA logins. This feature 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.\n\n## Redirect URIs\n\nMicrosoft Entra applications rely on redirect URIs to determine where to send the authentication response after a user has logged in. To enable brokered authentication through WAM, a redirect URI matching the following pattern should be registered to the application:\n\n```\nms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}\n```\n\n## Examples\n\n### Authenticate with `InteractiveBrowserBrokerCredential`\n\nThis 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` module from the `pywin32` package is used to get the current window.\n\n```python\nimport win32gui\nfrom azure.identity.broker import InteractiveBrowserBrokerCredential\nfrom azure.storage.blob import BlobServiceClient\n\n# Get the handle of the current window\ncurrent_window_handle = win32gui.GetForegroundWindow()\n\ncredential = InteractiveBrowserBrokerCredential(parent_window_handle=current_window_handle)\nclient = BlobServiceClient(account_url, credential=credential)\n```\n\nTo bypass the account selection dialog and use the default broker account, set the `use_default_broker_account` argument to `True`. The credential will attempt to silently use the default broker account. If using the default account fails, the credential will fall back to interactive authentication.\n\n```python\ncredential = InteractiveBrowserBrokerCredential(\n parent_window_handle=current_window_handle,\n use_default_broker_account=True\n)\n```\n\n## Troubleshooting\n\nSee the Azure Identity [troubleshooting guide][troubleshooting_guide] for details on how to diagnose various failure scenarios.\n\n## Next steps\n\n### Client library support\n\nClient 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.\n\n### Known issues\n\nThis library doesn't support [Azure AD B2C][b2c].\n\nFor 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).\n\n### Provide feedback\n\nIf you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-python/issues).\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen 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.\n\nThis 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.\n\n<!-- LINKS -->\n[azure_identity]: https://pypi.org/project/azure-identity\n[azure_identity_broker]: https://pypi.org/project/azure-identity-broker\n[azure_storage_blob]: https://pypi.org/project/azure-storage-blob\n[b2c]: https://learn.microsoft.com/azure/active-directory-b2c/overview\n[entra_id]: https://learn.microsoft.com/entra/identity/\n[pip]: https://pypi.org/project/pip\n[ref_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-identity-broker/latest/index.html\n[source_code]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity-broker\n[troubleshooting_guide]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TROUBLESHOOTING.md\n\n\n# Release History\n\n## 1.2.0 (2024-10-08)\n\n### Other Changes\n\n- Stable release for the Proof-of-Possession (PoP) token support to `InteractiveBrowserBrokerCredential`.\n\n## 1.2.0b1 (2024-09-20)\n\n### Features Added\n\n- `InteractiveBrowserBrokerCredential` now implements the `SupportsTokenInfo` protocol. It now has a `get_token_info` method which returns an `AccessTokenInfo` object. The `get_token_info` method is an alternative method to `get_token` that improves support for more complex authentication scenarios.\n- Added Proof-of-Possession (PoP) token support to `InteractiveBrowserBrokerCredential`.\n\n## 1.1.0 (2024-04-09)\n\n### Features Added\n\n- `InteractiveBrowserBrokerCredential` now supports a `use_default_broker_account` property to enable the use of the currently logged in operating system account for authentication rather than prompting for a credential.\n- Added `enable_support_logging` as a keyword argument to `InteractiveBrowserBrokerCredential`. This allows additional support logging which may contain PII.\n\n### Other Changes\n\n- Python 3.7 is no longer supported. Please use Python version 3.8 or later.\n- Bumped minimum dependency on `azure-identity` to `1.15.0`.\n\n## 1.0.0 (2023-11-07)\n\n### Features Added\n\n- `enable_broker` is always on if running on Windows. Automatically fall back into non-broker mode if running on MacOS or Linux.\n\n### Breaking Changes\n\n- Removed `UsernamePasswordBrokerCredential`\n\n## 1.0.0b1 (2023-10-12)\n\n### Features Added\n\n- Added `azure.identity.broker.InteractiveBrowserBrokerCredential`\n and `azure.identity.broker.UsernamePasswordBrokerCredential` which have broker support.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Identity Broker plugin for Python",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity-broker"
},
"split_keywords": [
"azure",
" azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "40d3ef0cdf79fd0fe530c550467504d5caadd6758d324e5788d5ba193cc06399",
"md5": "71f087679b9822c862a339f11c290f8d",
"sha256": "fe282311fb5d6f10ebc8fd1ef2b780bd1bca6b4771aee8b3a686d3e11d17e9e6"
},
"downloads": -1,
"filename": "azure_identity_broker-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71f087679b9822c862a339f11c290f8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10072,
"upload_time": "2024-10-08T15:51:38",
"upload_time_iso_8601": "2024-10-08T15:51:38.453473Z",
"url": "https://files.pythonhosted.org/packages/40/d3/ef0cdf79fd0fe530c550467504d5caadd6758d324e5788d5ba193cc06399/azure_identity_broker-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8ac728e9835cc2611bb9066fc4068a7081123b09e60b632f8d347f70d8b7134d",
"md5": "b7482adfe3cee9d02a8d5010b9a21e12",
"sha256": "487e4408982dc165e3c27afd727d7f5086841e5e6ed04990bc519f8329f1a8e5"
},
"downloads": -1,
"filename": "azure_identity_broker-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b7482adfe3cee9d02a8d5010b9a21e12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13017,
"upload_time": "2024-10-08T15:51:37",
"upload_time_iso_8601": "2024-10-08T15:51:37.284804Z",
"url": "https://files.pythonhosted.org/packages/8a/c7/28e9835cc2611bb9066fc4068a7081123b09e60b632f8d347f70d8b7134d/azure_identity_broker-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 15:51:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-identity-broker"
}
JSON
