From 4fc6646e2cdb982a4b22e26686457ec867c6b973 Mon Sep 17 00:00:00 2001 From: "apexvss@microsoft.com" Date: Sat, 7 Sep 2024 07:12:39 +0000 Subject: [PATCH] CI Update Build.Reason:Manual by Den Delimarsky Build.Url:https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=455259&view=results --- .../msal.application.ClientApplication.yml | 10 +- ...lication.ConfidentialClientApplication.yml | 10 +- ...al.application.PublicClientApplication.yml | 100 +++++++++--------- ...managed_identity.ManagedIdentityClient.yml | 29 ++++- ...sal.token_cache.SerializableTokenCache.yml | 28 ++--- 5 files changed, 109 insertions(+), 68 deletions(-) diff --git a/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml b/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml index e60c09e..713e3da 100644 --- a/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml +++ b/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml @@ -205,11 +205,15 @@ constructor: For example, if client is capable to handle *claims challenge*, - STS can then issue CAE access tokens to resources + STS may issue - knowing when the resource emits *claims challenge* + [Continuous Access Evaluation (CAE)](https://learn.microsoft.com/entra/identity/conditional-access/concept-continuous-access-evaluation) - the client will be capable to handle. + access tokens to resources, + + knowing that when the resource emits a *claims challenge* + + the client will be able to handle those challenges. Implementation details: diff --git a/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml b/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml index 8b53c19..a3d9e0f 100644 --- a/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml +++ b/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml @@ -205,11 +205,15 @@ constructor: For example, if client is capable to handle *claims challenge*, - STS can then issue CAE access tokens to resources + STS may issue - knowing when the resource emits *claims challenge* + [Continuous Access Evaluation (CAE)](https://learn.microsoft.com/entra/identity/conditional-access/concept-continuous-access-evaluation) - the client will be capable to handle. + access tokens to resources, + + knowing that when the resource emits a *claims challenge* + + the client will be able to handle those challenges. Implementation details: diff --git a/python/docs-ref-autogen/msal/msal.application.PublicClientApplication.yml b/python/docs-ref-autogen/msal/msal.application.PublicClientApplication.yml index 43aaf57..2b6c407 100644 --- a/python/docs-ref-autogen/msal/msal.application.PublicClientApplication.yml +++ b/python/docs-ref-autogen/msal/msal.application.PublicClientApplication.yml @@ -7,38 +7,40 @@ inheritances: - msal.application.ClientApplication summary: "Same as ,\nexcept that `client_credential`\ \ parameter shall remain `None`.\n\n> [!NOTE]\n> You may set enable_broker_on_windows\ - \ to True.\n>\n> \n>\n> What is a broker, and why use it?\n>\n> \n>\n> A broker\ - \ is a component installed on your device.\n>\n> Broker implicitly gives your device\ - \ an identity. By using a broker,\n>\n> your device becomes a factor that can satisfy\ - \ MFA (Multi-factor authentication).\n>\n> This factor would become mandatory\n\ - >\n> if a tenant's admin enables a corresponding Conditional Access (CA) policy.\n\ - >\n> The broker's presence allows Microsoft identity platform\n>\n> to have higher\ - \ confidence that the tokens are being issued to your device,\n>\n> and that is\ - \ more secure.\n>\n> \n>\n> An additional benefit of broker is,\n>\n> it runs as\ - \ a long-lived process with your device's OS,\n>\n> and maintains its own cache,\n\ - >\n> so that your broker-enabled apps (even a CLI)\n>\n> could automatically SSO\ - \ from a previously established signed-in session.\n>\n> \n>\n> You shall only enable\ - \ broker when your app:\n>\n> \n>\n> is running on supported platforms,\n>\n> and\ - \ already registered their corresponding redirect_uri\n>\n> \n>\n> ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id\n\ - >\n> if your app is expected to run on Windows 10+\n>\n> \n>\n> installed broker\ - \ dependency,\n>\n> e.g. pip install msal[broker]>=1.25,<2.\n>\n> \n>\n> tested\ - \ with acquire_token_interactive() and acquire_token_silent().\n>\n> \n>\n> The\ - \ fallback behaviors of MSAL Python's broker support\n>\n> \n>\n> MSAL will either\ - \ error out, or silently fallback to non-broker flows.\n>\n> \n>\n> MSAL will ignore\ - \ the enable_broker_... and bypass broker\n>\n> on those auth flows that are known\ - \ to be NOT supported by broker.\n>\n> This includes ADFS, B2C, etc..\n>\n> For\ - \ other \"could-use-broker\" scenarios, please see below.\n>\n> \n>\n> MSAL errors\ - \ out when app developer opted-in to use broker\n>\n> but a direct dependency \"\ - mid-tier\" package is not installed.\n>\n> Error message guides app developer to\ - \ declare the correct dependency\n>\n> msal[broker].\n>\n> We error out here because\ - \ the error is actionable to app developers.\n>\n> \n>\n> MSAL silently \"deactivates\"\ - \ the broker and fallback to non-broker,\n>\n> when opted-in, dependency installed\ - \ yet failed to initialize.\n>\n> We anticipate this would happen on a device whose\ - \ OS is too old\n>\n> or the underlying broker component is somehow unavailable.\n\ - >\n> There is not much an app developer or the end user can do here.\n>\n> Eventually,\ - \ the conditional access policy shall\n>\n> force the user to switch to a different\ - \ device.\n>\n> \n>\n> MSAL errors out when broker is opted in, installed, initialized,\n\ - >\n> but subsequent token request(s) failed.\n>" + \ and/or enable_broker_on_mac to True.\n>\n> \n>\n> What is a broker, and why use\ + \ it?\n>\n> \n>\n> A broker is a component installed on your device.\n>\n> Broker\ + \ implicitly gives your device an identity. By using a broker,\n>\n> your device\ + \ becomes a factor that can satisfy MFA (Multi-factor authentication).\n>\n> This\ + \ factor would become mandatory\n>\n> if a tenant's admin enables a corresponding\ + \ Conditional Access (CA) policy.\n>\n> The broker's presence allows Microsoft identity\ + \ platform\n>\n> to have higher confidence that the tokens are being issued to your\ + \ device,\n>\n> and that is more secure.\n>\n> \n>\n> An additional benefit of broker\ + \ is,\n>\n> it runs as a long-lived process with your device's OS,\n>\n> and maintains\ + \ its own cache,\n>\n> so that your broker-enabled apps (even a CLI)\n>\n> could\ + \ automatically SSO from a previously established signed-in session.\n>\n> \n>\n\ + > You shall only enable broker when your app:\n>\n> \n>\n> is running on supported\ + \ platforms,\n>\n> and already registered their corresponding redirect_uri\n>\n\ + > \n>\n> ms-appx-web://Microsoft.AAD.BrokerPlugin/your_client_id\n>\n> if your app\ + \ is expected to run on Windows 10+\n>\n> \n>\n> msauth.com.msauth.unsignedapp://auth\n\ + >\n> if your app is expected to run on Mac\n>\n> \n>\n> installed broker dependency,\n\ + >\n> e.g. pip install msal[broker]>=1.31,<2.\n>\n> \n>\n> tested with acquire_token_interactive()\ + \ and acquire_token_silent().\n>\n> \n>\n> The fallback behaviors of MSAL Python's\ + \ broker support\n>\n> \n>\n> MSAL will either error out, or silently fallback to\ + \ non-broker flows.\n>\n> \n>\n> MSAL will ignore the enable_broker_... and bypass\ + \ broker\n>\n> on those auth flows that are known to be NOT supported by broker.\n\ + >\n> This includes ADFS, B2C, etc..\n>\n> For other \"could-use-broker\" scenarios,\ + \ please see below.\n>\n> \n>\n> MSAL errors out when app developer opted-in to\ + \ use broker\n>\n> but a direct dependency \"mid-tier\" package is not installed.\n\ + >\n> Error message guides app developer to declare the correct dependency\n>\n>\ + \ msal[broker].\n>\n> We error out here because the error is actionable to app developers.\n\ + >\n> \n>\n> MSAL silently \"deactivates\" the broker and fallback to non-broker,\n\ + >\n> when opted-in, dependency installed yet failed to initialize.\n>\n> We anticipate\ + \ this would happen on a device whose OS is too old\n>\n> or the underlying broker\ + \ component is somehow unavailable.\n>\n> There is not much an app developer or\ + \ the end user can do here.\n>\n> Eventually, the conditional access policy shall\n\ + >\n> force the user to switch to a different device.\n>\n> \n>\n> MSAL errors out\ + \ when broker is opted in, installed, initialized,\n>\n> but subsequent token request(s)\ + \ failed.\n>" constructor: syntax: PublicClientApplication(client_id, client_credential=None, **kwargs) parameters: @@ -53,6 +55,16 @@ constructor: isRequired: true types: - + - name: enable_broker_on_mac + description: 'This setting is only effective if your app is running on Mac. + + This parameter defaults to None, which means MSAL will not utilize a broker. + + + New in MSAL Python 1.31.0.' + isRequired: true + types: + - - name: client_id isRequired: true - name: client_credential @@ -208,22 +220,14 @@ methods: types: - - name: parent_window_handle - description: 'Required if your app is running on Windows and opted in to use broker. - - - If your app is a GUI app, - - you are recommended to also provide its window handle, - - so that the sign in UI window will properly pop up on top of your window. - - - If your app is a console app (most Python scripts are console apps), - - you can use a placeholder value `msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE`. - - - New in version 1.20.0.' + description: "OPTIONAL.\n\n* If your app does not opt in to use broker, you do\ + \ not need to provide a `parent_window_handle` here. \n\n* If your app opts\ + \ in to use broker, `parent_window_handle` is required. \n\n * If your app\ + \ is a GUI app running on Windows or Mac system, you are required to also provide\ + \ its window handle, so that the sign-in window will pop up on top of your window.\ + \ \n\n * If your app is a console app running on Windows or Mac system, you\ + \ can use a placeholder `PublicClientApplication.CONSOLE_WINDOW_HANDLE`. \n\n\ + Most Python scripts are console apps.\n\nNew in version 1.20.0." defaultValue: None types: - diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml b/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml index 50ca2c6..df1d65f 100644 --- a/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml +++ b/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml @@ -87,7 +87,34 @@ methods: \ is a service-side behavior that cannot be changed by this library.\n>\n> [Azure\ \ VM docs](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http)\n\ >" - signature: acquire_token_for_client(*, resource) + signature: 'acquire_token_for_client(*, resource: str, claims_challenge: str | None + = None)' + parameters: + - name: resource + description: The resource for which the token is acquired. + isRequired: true + - name: claims_challenge + description: 'Optional. + + It is a string representation of a JSON object + + (which contains lists of claims being requested). + + + The tenant admin may choose to revoke all Managed Identity tokens, + + and then a *claims challenge* will be returned by the target resource, + + as a *claims_challenge* directive in the *www-authenticate* header, + + even if the app developer did not opt in for the "CP1" client capability. + + Upon receiving a *claims_challenge*, MSAL will skip a token cache read, + + and will attempt to acquire a new token.' + isRequired: true keywordOnlyParameters: - name: resource isRequired: true + - name: claims_challenge + isRequired: true diff --git a/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml b/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml index 34990d1..65b1073 100644 --- a/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml +++ b/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml @@ -7,19 +7,21 @@ inheritances: - msal.token_cache.TokenCache summary: "This serialization can be a starting point to implement your own persistence.\n\ \nThis class does NOT actually persist the cache on disk/db/etc..\nDepending on\ - \ your need,\nthe following simple recipe for file-based persistence may be sufficient:\n\ - \n\n\n````default\n\n import os, atexit,\ - \ msal\n cache_filename = os.path.join( # Persist cache into this file\n \ - \ os.getenv(\"XDG_RUNTIME_DIR\", \"\"), # Automatically wipe out the cache from\ - \ Linux when user's ssh session ends. See also https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/690\n\ - \ \"my_cache.bin\")\n cache = msal.SerializableTokenCache()\n if os.path.exists(cache_filename):\n\ - \ cache.deserialize(open(cache_filename, \"r\").read())\n atexit.register(lambda:\n\ - \ open(cache_filename, \"w\").write(cache.serialize())\n # Hint: The\ - \ following optional line persists only when state changed\n if cache.has_state_changed\ - \ else None\n )\n app = msal.ClientApplication(..., token_cache=cache)\n\ - \ ...\n ````" + \ your need,\nthe following simple recipe for file-based, unencrypted persistence\ + \ may be sufficient:\n\n\n\n````default\n\n import\ + \ os, atexit, msal\n cache_filename = os.path.join( # Persist cache into this\ + \ file\n os.getenv(\n # Automatically wipe out the cache from Linux\ + \ when user's ssh session ends.\n # See also https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/690\n\ + \ \"XDG_RUNTIME_DIR\", \"\"),\n \"my_cache.bin\")\n cache = msal.SerializableTokenCache()\n\ + \ if os.path.exists(cache_filename):\n cache.deserialize(open(cache_filename,\ + \ \"r\").read())\n atexit.register(lambda:\n open(cache_filename, \"w\"\ + ).write(cache.serialize())\n # Hint: The following optional line persists\ + \ only when state changed\n if cache.has_state_changed else None\n )\n\ + \ app = msal.ClientApplication(..., token_cache=cache)\n ...\n ````\n\nAlternatively,\ + \ you may use a more sophisticated cache persistence library,\n[MSAL Extensions](https://github.com/AzureAD/microsoft-authentication-extensions-for-python),\n\ + which provides token cache persistence with encryption, and more." constructor: syntax: SerializableTokenCache() variables: