Merge pull request #100 from MicrosoftDocs/main

Sync changes

Author: localden

README.md

@@ -15,7 +15,7 @@ If you would like to author an entirely new document (e.g., for a new scenario),
 
 ## API reference documentation automation
 
-Continuous Integration (CI) jobs for this repository are available in the [automation Azure DevOps instance](https://apidrop.visualstudio.com/Content%20CI/_build?definitionId=5247).
+Continuous Integration (CI) jobs for this repository are available in the [automation Azure DevOps instance](https://apidrop.visualstudio.com/Content%20CI/_build?definitionId=6169).
 
 >**Note**
 >The changes from the CI job will always be pushed to the `smoke-test` branch first. To propagate them to production, merge the changes into `main`, and then merge `main` to `live`. Ensure that all checks pass before merging changes.

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:

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:

python/docs-ref-autogen/msal/msal.application.PublicClientApplication.yml

@@ -7,38 +7,40 @@ inheritances:
 - msal.application.ClientApplication
 summary: "Same as <xref:ClientApplication.__init__>,\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:
     - <xref:boolean>
+  - 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:
+    - <xref:boolean>
   - name: client_id
     isRequired: true
   - name: client_credential
@@ -208,22 +220,14 @@ methods:
     types:
     - <xref:int>
   - 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:
     - <xref:int>

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

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<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
-  : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\",\
-  \ \"force\": false, \"linenos\": false} -->\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<!-- literal_block {\"ids\": [], \"classes\": [], \"names\"\
+  : [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\"\
+  : \"default\", \"force\": false, \"linenos\": false} -->\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: