acquire_token_by_refresh_token() for RT migration

[rayluo]

This PR implements the right-hand side of this comparison. We can go with this direction, and then this PR will close #191.

The API calling pattern is largely the same as #191, if we do not really need to use its return value:

app = msal.PublicClientApplication(
    "client_id", ...)

# Proposal B
result = app.acquire_token_by_refresh_token(
    old_rt, ["scope1", "scope2"])
if "error" in result:
    print(
        "Error in Migration:",
        json.dumps(result))
else:
    print("Migration is successful")
    # The new RT is saved inside MSAL's cache.
    # You could use the new AT, IDT from result at this point

There are still two higher level RT migration strategies:

• One approach is to migrate RTs IN A BATCH within minutes, when a newer version of app (Azure CLI) is run for its first time on an end user's machine and detects a legacy RT persistence.

  if os.path.exists("adal_token_cache.bin"):
      for rt, scopes in get_legacy_rt(...):
          app.acquire_token_by_refresh_token(rt, scopes)
      os.rename("adal_token_cache.bin", "legacy_cache_to_be_deleted.bin")
      # Migration completed. From now on,
      # everything follows the normal MSAL way,
      # i.e. acquire_token_silent(scopes)
  main_program(...)  # Main program starts

  With this strategy, you may safely discard the return value of each acquire_token_by_refresh_token() call, DURING the migration.

  The comparison: acquire_token_by_refresh_token() ≈ MSAL .Net's it is not readily accessible with the IConfidentialClientApplication without first casting it to IByRefreshToken. + acquire_token_by_refresh_token()

• Another approach is to migrate RTs GRADUALLY across many days or even weeks, when the end user is using our app (such as Azure CLI) frequently. But then you would have to use acquire_token_by_refresh_token() in your normal code path. The following demo is copied from here.

  try
  {
         // if this works, migration is not needed or it already happened
         AcquireTokenSilent (...)
  }
  catch UIRequiredException
  {
      try
      {
             // migration path ... can be removed after some time
             var rt = GetLegacyRefreshToken(...)
             AcquireTokenByRefershToken(...)
      }
      catch UIRequiredException
      {
            // no RT available, get a new one
            AcquireTokenByXyz(...)
      }
  }

[henrik-me]

this one gets my vote

[henrik-me]

In normal MSAL scenarios, you do NOT need to use this method. [](start = 8, length = 61)

https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/1cef43d185bb0a1dcc013d2ec232ae9d4c6c053a/src/client/Microsoft.Identity.Client/IByRefreshToken.cs:
/// Acquires an access token from an existing refresh token and stores it, and the refresh token, in
/// the user token cache, where it will be available for further AcquireTokenSilent calls.
/// This method can be used in migration to MSAL from ADAL v2, and in various integration
/// scenarios where you have a RefreshToken available.
/// See https://aka.ms/msal-net-migration-adal2-msal2.

You can also get inspiration on the text from the Java API. Should be similar.

Please add aka.ms links to and create a wiki page allowing you to explain this in more details as well as updating content and linking to it easily when customers have questions.

[rayluo]

We probably do not need to create yet another wiki page. After this PR is released, we can modify the existing doc accordingly.

[rayluo]

After this PR is released, we can modify the existing doc accordingly.

UPDATE:
A new doc PR for the migration docs has been created just now.

[rayluo]

Quoted a test feedback from @qianwens:

I have tried your PR and it works perfectly. I can use an ADAL refresh token to generate the MSAL token cache with your method and CLI command works well with the generated MSAL token.

Thanks very much for implementing this function in such a short time.

[abhidnya13]

🚢