Expose and document AutoRefresher, deprecate client_assertion as a string

This addresses 705 and 746

Author: rayluo

msal/__init__.py

@@ -45,4 +45,5 @@
 # 1. officially part of the MSAL public API, and
 # 2. can still be caught by the user code even if we change the module structure.
 from .oauth2cli.oauth2 import BrowserInteractionTimeoutError
+from .oauth2cli.assertion import AutoRefresher
 

msal/application.py

@@ -304,7 +304,30 @@ def __init__(
 
             .. admonition:: Supporting raw assertion obtained from elsewhere
 
+                *Added in version 1.32.0*:
+
+                MSAL Python accepts a callback which shall obtain an assertion::
+
+                    import msal
+
+                    def assertion_callback():
+                        return '''A fresh JWT with claims:
+                            aud, exp, iss, jti, nbf, and sub'''
+
+                    smart_callback = msal.AutoRefresher(
+                        assertion_callback,
+                        expires_in=3600,  # Whatever value that you see fit
+                    )  # This ensures the original callback will be cached
+
+                    app = msal.ConfidentialClientApplication(
+                       ...,
+                       client_credential={"client_assertion": smart_callback},
+                    )
+
                 *Added in version 1.13.0*:
+
+                Deprecated.
+
                 It can also be a completely pre-signed assertion that you've assembled yourself.
                 Simply pass a container containing only the key "client_assertion", like this::
 
@@ -757,6 +780,11 @@ def _build_client(self, client_credential, authority, skip_regional_client=False
             # Use client_credential.get("...") rather than "..." in client_credential
             # so that we can ignore an empty string came from an empty ENV VAR.
             if client_credential.get("client_assertion"):
+                if isinstance(client_credential["client_assertion"], str):
+                    warnings.warn(
+                        "Please use a callback instead of a string. See also "
+                        "https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.params.client_credential",
+                        DeprecationWarning)
                 client_assertion = client_credential['client_assertion']
             else:
                 headers = {}

tests/test_e2e.py

@@ -692,14 +692,16 @@ def _test_acquire_token_obo(self, config_pca, config_cca,
         result = cca.acquire_token_silent(config_cca["scope"], account)
         self.assertEqual(cca_result["access_token"], result["access_token"])
 
-    def _test_acquire_token_by_client_secret(
-            self, client_id=None, client_secret=None, authority=None, scope=None,
+    def _test_acquire_token_for_client(
+            self, client_id=None, client_credential=None, authority=None, scope=None,
             oidc_authority=None,
             **ignored):
-        assert client_id and client_secret and scope and (
+        assert client_id and client_credential and scope and (
             authority or oidc_authority)
         self.app = msal.ConfidentialClientApplication(
-            client_id, client_credential=client_secret, authority=authority,
+            client_id,
+            client_credential=client_credential,
+            authority=authority,
             oidc_authority=oidc_authority,
             http_client=MinimalHttpClient())
         result = self.app.acquire_token_for_client(scope)
@@ -936,9 +938,9 @@ def test_acquire_token_by_client_secret(self):
         # Vastly different than ArlingtonCloudTestCase.test_acquire_token_by_client_secret()
         _app = self.get_lab_app_object(
             publicClient="no", signinAudience="AzureAdMyOrg")
-        self._test_acquire_token_by_client_secret(
+        self._test_acquire_token_for_client(
             client_id=_app["appId"],
-            client_secret=self.get_lab_user_secret(
+            client_credential=self.get_lab_user_secret(
                 _app["clientSecret"].split("/")[-1]),
             authority="{}{}.onmicrosoft.com".format(
                 _app["authority"], _app["labName"].lower().rstrip(".com")),
@@ -1047,9 +1049,9 @@ def test_ciam_acquire_token_for_client(self):
         else:  # Ciam6 era has a URL path that ends with the secret name
             secret_name = secret_url.path.split("/")[-1]
         logger.info('Detected secret name "%s" from "%s"', secret_name, raw_url)
-        self._test_acquire_token_by_client_secret(
+        self._test_acquire_token_for_client(
             client_id=self.app_config["appId"],
-            client_secret=self.get_lab_user_secret(secret_name),
+            client_credential=self.get_lab_user_secret(secret_name),
             authority=self.app_config.get("authority"),
             oidc_authority=self.app_config.get("oidc_authority"),
             scope=self.app_config["scopes"],  # It shall ends with "/.default"
@@ -1212,8 +1214,8 @@ def test_acquire_token_by_ropc(self):
 
     def test_acquire_token_by_client_secret(self):
         config = self.get_lab_user(usertype="cloud", azureenvironment=self.environment, publicClient="no")
-        config["client_secret"] = self.get_lab_user_secret("ARLMSIDLAB1-IDLASBS-App-CC-Secret")
-        self._test_acquire_token_by_client_secret(**config)
+        config["client_credential"] = self.get_lab_user_secret("ARLMSIDLAB1-IDLASBS-App-CC-Secret")
+        self._test_acquire_token_for_client(**config)
 
     def test_acquire_token_obo(self):
         config_cca = self.get_lab_user(