Merge pull request #96229 from MicrosoftDocs/master

Merge master to live 4:15 AM

Author: ShannonLeavitt

articles/active-directory/develop/TOC.yml

@@ -241,7 +241,9 @@
           href: migrate-android-adal-msal.md
         - name: Migrate to MSAL.iOS and MacOS
           href: migrate-objc-adal-msal.md
-        - name: Migrate to MSAL Java
+        - name: Migrate to MSAL Python
+          href: migrate-python-adal-msal.md
+        - name: Migrate to MSAL for Java
           href: migrate-adal-msal-java.md
         - name: Migrate Xamarin apps using brokers from ADAL.NET to MSAL.NET
           href: msal-net-migration-ios-broker.md
@@ -452,7 +454,11 @@
               href: request-custom-claims.md
             - name: Redirect URI configuration
               href: redirect-uris-ios.md
-        - name: MSAL Java
+        - name: MSAL for Python
+          items:
+            - name: Token cache serialization
+              href: msal-python-token-cache-serialization.md
+        - name: MSAL for Java
           items:
             - name: Token cache serialization
               href: msal-java-token-cache-serialization.md

articles/active-directory/develop/migrate-adal-msal-java.md

@@ -1,5 +1,6 @@
 ---
-title: ADAL to MSAL migration guide for Java- Microsoft identity platform | Azure
+title: ADAL to MSAL migration guide for Java | Azure
+titleSuffix: Microsoft identity platform
 description: Learn how to migrate your Azure Active Directory Authentication Library (ADAL) Java app to the Microsoft Authentication Library (MSAL).
 services: active-directory
 author: sangonzal
@@ -64,7 +65,7 @@ The following table shows how ADAL4J functions map to the new MSAL4J functions:
 
 ADAL4J manipulated users. Although a user represents a single human or software agent, it can have one or more accounts in the Microsoft identity system. For example, a user may have several Azure AD, Azure AD B2C, or Microsoft personal accounts.
 
-MSAL4J defines the concept of Account via the `IAccount` interface. This is a breaking change from ADAL4J, but it is a good one because it captures the fact that that the same user can have several accounts, and perhaps even in different Azure AD directories. MSAL4J provides better information in guest scenarios because home account information is provided.
+MSAL4J defines the concept of Account via the `IAccount` interface. This is a breaking change from ADAL4J, but it is a good one because it captures the fact that the same user can have several accounts, and perhaps even in different Azure AD directories. MSAL4J provides better information in guest scenarios because home account information is provided.
 
 ## Cache persistence
 

articles/active-directory/develop/migrate-python-adal-msal.md

@@ -0,0 +1,103 @@
+---
+title: ADAL to MSAL migration guide for Python | Azure
+description: Learn how to migrate your Azure Active Directory Authentication Library (ADAL) Python app to the Microsoft Authentication Library (MSAL) for Python.
+services: active-directory
+titleSuffix: Microsoft identity platform
+author: rayluo
+manager: henrikm
+editor: twhitney
+
+ms.service: active-directory
+ms.subservice: develop
+ms.devlang: na
+ms.topic: conceptual
+ms.tgt_pltfrm: Python
+ms.workload: identity
+ms.date: 11/11/2019
+ms.author: rayluo
+ms.reviewer: 
+ms.custom: aaddev
+#Customer intent: As a Python application developer, I want to learn how to migrate my v1 ADAL app to v2 MSAL.
+ms.collection: M365-identity-device-management
+---
+
+# ADAL to MSAL migration guide for Python
+
+This article highlights changes you need to make to migrate an app that uses the Azure Active Directory Authentication Library (ADAL) to use the Microsoft Authentication Library (MSAL).
+
+## Difference highlights
+
+ADAL works with the Azure Active Directory v1.0 endpoint. The Microsoft Authentication Library (MSAL) works with the Microsoft identity platform--formerly known as the Azure Active Directory v2.0 endpoint. The Microsoft identity platform differs from Azure Active Directory v1.0 in that it:
+
+Supports:
+  - Work and school accounts (Azure AD provisioned accounts)
+  - Personal accounts (such as Outlook.com or Hotmail.com)
+  - Your customers who bring their own email or social identity (such as LinkedIn, Facebook, Google) via the Azure AD B2C offering
+
+- Is standards compatible with:
+  - OAuth v2.0
+  - OpenID Connect (OIDC)
+
+See [What's different about the Microsoft identity platform (v2.0) endpoint?](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) for more details.
+
+### Scopes not resources
+
+ADAL Python acquires tokens for resources, but MSAL Python acquires tokens for scopes. The API surface in MSAL Python does not have resource parameter anymore. You would need to provide scopes as a list of strings that declare the desired permissions and resources that are requested. To see some example of scopes, see [Microsoft Graph's scopes](https://docs.microsoft.com/graph/permissions-reference).
+
+### Error handling
+
+Azure Active Directory Authentication Library (ADAL) for Python uses the exception `AdalError` to indicate that there's been a problem. MSAL for  Python typically uses error codes, instead. For more information, see  [MSAL for Python error handling](msal-handling-exceptions.md#msal-for-python-error-handling).
+
+### API changes
+
+The following table lists an API in ADAL for Python, and the one to use in its place in MSAL for Python:
+
+| ADAL for Python API  | MSAL for Python API |
+| ------------------- | ---------------------------------- |
+| [AuthenticationContext](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext)  | [PublicClientApplication or ConfidentialClientApplication](https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.__init__)  |
+| N/A  | [get_authorization_request_url()](https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.get_authorization_request_url)  |
+| [acquire_token_with_authorization_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_authorization_code) | [acquire_token_by_authorization_code()](https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.acquire_token_by_authorization_code) |
+| [acquire_token()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token) | [acquire_token_silent()](https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.acquire_token_silent) |
+| [acquire_token_with_refresh_token()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_refresh_token) | N/A (See the section above) |
+| [acquire_user_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_user_code) | [initiate_device_flow()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.initiate_device_flow) |
+| [acquire_token_with_device_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_device_code) and [cancel_request_to_get_token_with_device_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.cancel_request_to_get_token_with_device_code) | [acquire_token_by_device_flow()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_by_device_flow) |
+| [acquire_token_with_username_password()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_username_password) | [acquire_token_by_username_password()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_by_username_password) |
+| [acquire_token_with_client_credentials()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_client_credentials) and [acquire_token_with_client_certificate()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_client_certificate) | [acquire_token_for_client()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_for_client) |
+| N/A | [acquire_token_on_behalf_of()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_on_behalf_of) |
+| [TokenCache()](https://adal-python.readthedocs.io/en/latest/#adal.TokenCache) | [SerializableTokenCache()](https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache) |
+| N/A | Cache with persistence, available from [MSAL Extensions](https://github.com/marstr/original-microsoft-authentication-extensions-for-python) |
+
+## Migrate existing refresh tokens for MSAL Python
+
+The Microsoft authentication library (MSAL) abstracts the concept of refresh tokens. MSAL Python provides an in-memory token cache by default so that you don't need to store, lookup, or update refresh tokens. Users will also see fewer sign-in prompts because refresh tokens can usually be updated without user intervention. For more information about the token cache, see [Custom token cache serialization in MSAL for Python](msal-python-token-cache-serialization.md).
+
+The following code will help you migrate your refresh tokens managed by another OAuth2 library (including but not limited to ADAL Python) to be managed by MSAL for Python. One reason for migrating those refresh tokens is to prevent existing users from needing to sign in again when you migrate your app to MSAL for Python.
+
+The method for migrating a refresh token is to use MSAL for Python to acquire a new access token using the previous refresh token. When the new refresh token is returned, MSAL for Python will store it in the cache. Here is an example of how to do it:
+
+```python
+from msal import PublicClientApplication
+
+def get_preexisting_rt_and_their_scopes_from_elsewhere(...):
+    raise NotImplementedError("You will need to implement this by yourself")
+
+app = PublicClientApplication(..., token_cache=...)
+
+for old_rt, old_scope in get_preexisting_rt_and_their_scopes_from_elsewhere(...):
+    # Assuming the old scope could be a space-delimited string.
+    # MSAL expects a list, like ["scope1", "scope2"].
+    scopes = old_scope.split()
+        # If your old refresh token came from ADAL for Python, 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
+
+    result = app.client.obtain_token_by_refresh_token(old_rt, scope=scopes)
+    # When this call returns the new token(s), a new refresh token is issued by the Microsoft identity platform and MSAL for Python
+    # stores it in the token cache.
+```
+
+## Next steps
+
+For more information, refer to [v1.0 and v2.0 comparison](active-directory-v2-compare.md).

articles/active-directory/develop/msal-handling-exceptions.md

@@ -14,7 +14,7 @@ ms.devlang: na
 ms.topic: conceptual
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 09/08/2019
+ms.date: 11/13/2019
 ms.author: twhitney
 ms.reviewer: saeeda
 ms.custom: aaddev
@@ -36,7 +36,7 @@ During silent or interactive token acquisition, apps may come across errors duri
 
 The complete list of errors is listed in [MSALError enum](https://github.com/AzureAD/microsoft-authentication-library-for-objc/blob/master/MSAL/src/public/MSALError.h#L128).
 
-All MSAL produced errors are returned with `MSALErrorDomain` domain. 
+All MSAL produced errors are returned with `MSALErrorDomain` domain.
 
 For system errors, MSAL returns the original `NSError` from the system API. For example, if token acquisition fails because of a lack of network connectivity, MSAL returns an error with the `NSURLErrorDomain` domain and `NSURLErrorNotConnectedToInternet` code.
 
@@ -238,6 +238,17 @@ Swift
     application.acquireTokenSilent(with: silentParameters, completionBlock: completionBlock)
 ```
 
+## MSAL for Python error handling
+
+In MSAL for Python, most errors are conveyed as a return value from the API call. The error is represented as a dictionary containing the JSON response from the Microsoft identity platform.
+
+* A successful response contains the `"access_token"` key. The format of the response is defined by the OAuth2 protocol. For more information, see [5.1 Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1)
+* An error response contains `"error"` and usually `"error_description"`. The format of the response is defined by the OAuth2 protocol. For more information, see [5.2 Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)
+
+When an error is returned, the `"error_description"` key contains a human-readable message; which in turn typically contains a Microsoft identity platform error code. For details about the various error codes, see [Authentication and authorization error codes](https://docs.microsoft.com/azure/active-directory/develop/reference-aadsts-error-codes).
+
+In MSAL for Python, exceptions are rare because most errors are handled by returning an error value. The `ValueError` exception is only thrown when there is an issue with how you are attempting to use the library--such as when API parameter(s) are malformed.
+
 ## .NET exceptions
 
 When processing exceptions, you can use the exception type itself and the `ErrorCode` member to distinguish between exceptions. `ErrorCode` values are constants of type [MsalError](/dotnet/api/microsoft.identity.client.msalerror?view=azure-dotnet).
@@ -341,7 +352,6 @@ catch (MsalUiRequiredException ex) when (ex.ErrorCode == MsalError.InvalidGrantE
 }
 ```
 
-
 ## JavaScript errors
 
 MSAL.js provides error objects that abstract and classify the different types of common errors. It also provides interface to access specific details of the errors such as error messages to handle them appropriately.

articles/active-directory/develop/msal-java-token-cache-serialization.md

@@ -1,7 +1,7 @@
 ---
 title: Custom token cache serialization in MSAL for Java
 titleSuffix: Microsoft identity platform
-description: Learn how to serializing the token cache for MSAL for Java
+description: Learn how to serialize the token cache for MSAL for Java
 services: active-directory
 documentationcenter: dev-center-name
 author: sangonzal
@@ -18,13 +18,14 @@ ms.date: 11/07/2019
 ms.author: sagonzal
 ms.reviewer: navyasri.canumalla
 ms.custom: aaddev
-#Customer intent: As an application developer using the Microsoft Authentication Library for Java (MSAL4J), I want to learn how to persist the token cache.
+#Customer intent: As an application developer using the Microsoft Authentication Library for Java (MSAL4J), I want to learn how to persist the token cache so that it is available to a new instance of my application.
+
 ms.collection: M365-identity-device-management
 ---
 
 # Custom token cache serialization in MSAL for Java (MSAL4J)
 
-To have a persistent token cache application, you will need to customize the serialization. The Java classes and interfaces involved in token cache serialization are the following:
+To persist the token cache between instances of your application, you will need to customize the serialization. The Java classes and interfaces involved in token cache serialization are the following:
 
 - [ITokenCache](https://static.javadoc.io/com.microsoft.azure/msal4j/0.5.0-preview/com/microsoft/aad/msal4j/ITokenCache.html):  Interface representing security token cache.
 - [ITokenCacheAccessAspect](https://static.javadoc.io/com.microsoft.azure/msal4j/0.5.0-preview/com/microsoft/aad/msal4j/ITokenCacheAccessAspect.html): Interface representing operation of executing code before and after access. You would @Override *beforeCacheAccess* and *afterCacheAccess* with the logic responsible for serializing and deserializing the cache.