Switch import_refresh_token() to acquire_token_by_refresh_token()

Remove distracting test setup from sample

Demonstrate the migration-in-batch pattern

Author: rayluo

msal/application.py

@@ -700,27 +700,35 @@ def _validate_ssh_cert_input_data(self, data):
                     "you must include a string parameter named 'key_id' "
                     "which identifies the key in the 'req_cnf' argument.")
 
-    def import_refresh_token(self, refresh_token, scopes):
-        """Import an RT from elsewhere into MSAL's token cache.
+    def acquire_token_by_refresh_token(self, refresh_token, scopes):
+        """Acquire token(s) based on a refresh token (RT) obtained from elsewhere.
+
+        You use this method only when you have old RTs from elsewhere,
+        and now you want to migrate them into MSAL.
+        Calling this method results in new tokens automatically storing into MSAL.
+
+        You do NOT need to use this method if you are already using MSAL.
+        MSAL maintains RT automatically inside its token cache,
+        and an access token can be retrieved
+        when you call :func:`~acquire_token_silent`.
 
         :param str refresh_token: The old refresh token, as a string.
 
         :param list scopes:
             The scopes associate with this old RT.
             Each scope needs to be in the Microsoft identity platform (v2) format.
-            https://docs.microsoft.com/en-us/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources
+            See `Scopes not resources <https://docs.microsoft.com/en-us/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources>`_.
 
         :return:
             * A dict contains "error" and some other keys, when error happened.
-            * A dict contains no "error" key.
+            * A dict contains no "error" key means migration was successful.
         """
-        result = self.client.obtain_token_by_refresh_token(
+        return self.client.obtain_token_by_refresh_token(
             refresh_token,
             decorate_scope(scopes, self.client_id),
             rt_getter=lambda rt: rt,
             on_updating_rt=False,
             )
-        return {} if "error" not in result else result  # Returns NO token
 
 
 class PublicClientApplication(ClientApplication):  # browser app or mobile app

sample/migrate_rt.py

@@ -25,51 +25,43 @@
 # logging.basicConfig(level=logging.DEBUG)  # Enable DEBUG log for entire script
 # logging.getLogger("msal").setLevel(logging.INFO)  # Optionally disable MSAL DEBUG logs
 
+def get_preexisting_rt_and_their_scopes_from_elsewhere():
+    # Maybe you have an ADAL-powered app like this
+    #   https://github.com/AzureAD/azure-activedirectory-library-for-python/blob/1.2.3/sample/device_code_sample.py#L72
+    # which uses a resource rather than a scope,
+    # you need to convert your v1 resource into v2 scopes
+    # See https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison#scopes-not-resources
+    # You may be able to append "/.default" to your v1 resource to form a scope
+    # See https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#the-default-scope
+
+    # Or maybe you have an app already talking to Microsoft identity platform v2,
+    # powered by some 3rd-party auth library, and persist its tokens somehow.
+
+    # Either way, you need to extract RTs from there, and return them like this.
+    return [
+        ("old_rt_1", ["scope1", "scope2"]),
+        ("old_rt_2", ["scope3", "scope4"]),
+        ]
+
+
+# We will migrate all the old RTs into a new app powered by MSAL
 config = json.load(open(sys.argv[1]))
-
-def get_rt_via_old_app():
-    # Let's pretend this is an old app powered by ADAL
-    app = msal.PublicClientApplication(
-        config["client_id"], authority=config["authority"])
-    flow = app.initiate_device_flow(scopes=config["scope"])
-    if "user_code" not in flow:
-        raise ValueError(
-            "Fail to create device flow. Err: %s" % json.dumps(flow, indent=4))
-    print(flow["message"])
-    sys.stdout.flush()  # Some terminal needs this to ensure the message is shown
-
-    # Ideally you should wait here, in order to save some unnecessary polling
-    # input("Press Enter after signing in from another device to proceed, CTRL+C to abort.")
-
-    result = app.acquire_token_by_device_flow(flow)  # By default it will block
-    assert "refresh_token" in result, "We should have a successful result"
-    return result["refresh_token"]
-
-try:  # For easier testing, we try to reload a RT from previous run
-    old_rt = json.load(open("rt.json"))[0]
-except:  # If that is not possible, we acquire a RT
-    old_rt = get_rt_via_old_app()
-    json.dump([old_rt], open("rt.json", "w"))
-
-# Now we will try to migrate this old_rt into a new app powered by MSAL
-
-token_cache = msal.SerializableTokenCache()
-assert token_cache.serialize() == '{}', "Token cache is initially empty"
 app = msal.PublicClientApplication(
-    config["client_id"], authority=config["authority"], token_cache=token_cache)
-result = app.import_refresh_token(old_rt, config["scope"])
-if "error" in result:
-    print("Migration unsuccessful. Error: ", json.dumps(result, indent=2))
-else:
-    print("Migration is successful")
-    logging.debug("Token cache contains: %s", token_cache.serialize())
-
-# From now on, the RT is saved inside MSAL's cache,
-# and becomes available in normal MSAL coding pattern. For example:
-accounts = app.get_accounts()
-if accounts:
-    account = accounts[0]  # Assuming end user pick this account
-    result = app.acquire_token_silent(config["scope"], account)
-    if "access_token" in result:
-        print("RT is available in MSAL's cache, and can be used to acquire new AT")
-
+    config["client_id"], authority=config["authority"],
+    # token_cache=...  # Default cache is in memory only.
+                       # You can learn how to use SerializableTokenCache from
+                       # https://msal-python.rtfd.io/en/latest/#msal.SerializableTokenCache
+    )
+
+# We choose a migration strategy of migrating all RTs in one loop
+for old_rt, scopes in get_preexisting_rt_and_their_scopes_from_elsewhere():
+    result = app.acquire_token_by_refresh_token(old_rt, scopes)
+    if "error" in result:
+        print("Discarding unsuccessful RT. Error: ", json.dumps(result, indent=2))
+
+print("Migration completed")
+
+# From now on, those successfully-migrated RTs are saved inside MSAL's cache,
+# and becomes available in normal MSAL coding pattern, which is NOT part of migration.
+# You can refer to:
+#   https://github.com/AzureAD/microsoft-authentication-library-for-python/blob/1.2.0/sample/device_flow_sample.py#L42-L60