From f9341e97c02d29544f15f25cac5eca8681ad7073 Mon Sep 17 00:00:00 2001 From: Paul Van Eck Date: Mon, 25 Sep 2023 14:17:27 -0700 Subject: [PATCH 1/2] [Identity] Add docstrings for WAM/MSA params Signed-off-by: Paul Van Eck --- .../azure/identity/_credentials/browser.py | 11 +++++++++++ .../azure/identity/_credentials/device_code.py | 8 ++++++++ .../azure/identity/_credentials/user_password.py | 6 ++++++ 3 files changed, 25 insertions(+) diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/browser.py b/sdk/identity/azure-identity/azure/identity/_credentials/browser.py index 3760613e6601..a2068a33db99 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/browser.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/browser.py @@ -43,6 +43,17 @@ class InteractiveBrowserCredential(InteractiveCredential): will cache tokens in memory. :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions :keyword int timeout: seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes). + :keyword bool allow_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 Windows operating system uses + the Web Account Manager (WAM) as its authentication broker. If this parameter is set to True, the broker will + be used when possible. Defaults to False. + Check https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam for more + information about WAM. + :keyword int parent_window_handle: If your app is a GUI app running on a modern Windows system, + and your app opts in to use broker via `allow_broker`, you are required to also provide its window handle, + so that the sign in UI window will properly pop up on top of your window. + :keyword bool enable_msa_passthrough: Determines whether Microsoft Account (MSA) passthrough is enabled. Note, this + is only needed for select legacy first-party applications. Defaults to False. :keyword bool disable_instance_discovery: Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached, such as in diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py b/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py index 7a69d26a37d5..5ba32dc6e72b 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py @@ -33,6 +33,7 @@ class DeviceCodeCredential(InteractiveCredential): authenticate work or school accounts. **Required for single-tenant applications.** :keyword int timeout: seconds to wait for the user to authenticate. Defaults to the validity period of the device code as set by Azure Active Directory, which also prevails when **timeout** is longer. + :keyword prompt_callback: A callback enabling control of how authentication instructions are presented. Must accept arguments (``verification_uri``, ``user_code``, ``expires_on``): @@ -41,12 +42,19 @@ class DeviceCodeCredential(InteractiveCredential): - ``expires_on`` (datetime.datetime) the UTC time at which the code will expire If this argument isn't provided, the credential will print instructions to stdout. :paramtype prompt_callback: Callable[str, str, ~datetime.datetime] + :keyword AuthenticationRecord authentication_record: :class:`AuthenticationRecord` returned by :func:`authenticate` :keyword bool disable_automatic_authentication: if True, :func:`get_token` will raise :class:`AuthenticationRequiredError` when user interaction is required to acquire a token. Defaults to False. :keyword cache_persistence_options: configuration for persistent token caching. If unspecified, the credential will cache tokens in memory. :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions + :keyword bool allow_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 Windows operating system uses + the Web Account Manager (WAM) as its authentication broker. If this parameter is set to True, the broker will + be used when possible. Defaults to False. + Check https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam for more + information about WAM. :keyword bool disable_instance_discovery: Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached, such as in diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py b/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py index 18b87de0c859..10327e11cd7b 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py @@ -41,6 +41,12 @@ class UsernamePasswordCredential(InteractiveCredential): https://login.microsoft.com/ to validate the authority. By setting this to **True**, the validation of the authority is disabled. As a result, it is crucial to ensure that the configured authority host is valid and trustworthy. + :keyword bool allow_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 Windows operating system uses + the Web Account Manager (WAM) as its authentication broker. If this parameter is set to True, the broker will + be used when possible. Defaults to False. + Check https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam for more + information about WAM. :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id" for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for any tenant the application can access. From 32639cfb0033ff1a6e2a089b005319767072ba6b Mon Sep 17 00:00:00 2001 From: Paul Van Eck Date: Tue, 3 Oct 2023 10:26:40 -0700 Subject: [PATCH 2/2] Remove device code docstring for broker Signed-off-by: Paul Van Eck --- .../azure/identity/_credentials/device_code.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py b/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py index 5ba32dc6e72b..06f02d7667a7 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/device_code.py @@ -49,12 +49,6 @@ class DeviceCodeCredential(InteractiveCredential): :keyword cache_persistence_options: configuration for persistent token caching. If unspecified, the credential will cache tokens in memory. :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions - :keyword bool allow_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 Windows operating system uses - the Web Account Manager (WAM) as its authentication broker. If this parameter is set to True, the broker will - be used when possible. Defaults to False. - Check https://learn.microsoft.com/azure/active-directory/develop/scenario-desktop-acquire-token-wam for more - information about WAM. :keyword bool disable_instance_discovery: Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached, such as in