Merging changes synced from https://github.com/MicrosoftDocs/azure-do…

…cs-pr (branch live)

.github/workflows/stale.yml

@@ -19,7 +19,8 @@ jobs:
         close-pr-label: auto-close
         exempt-pr-labels: keep-open
         operations-per-run: 1200
-        ascending: false
+        ascending: true
+        start-date: '2019-12-19' 
         stale-pr-message: >
           This pull request has been inactive for at least 14 days.
           If you are finished with your changes, don't forget to sign off. See the [contributor guide](https://review.docs.microsoft.com/help/contribute/contribute-how-to-write-pull-request-automation) for instructions.

articles/active-directory/app-provisioning/how-provisioning-works.md

@@ -77,7 +77,11 @@ You can use scoping filters to define attribute-based rules that determine which
 It's possible to use the Azure AD user provisioning service to provision B2B (or guest) users in Azure AD to SaaS applications. 
 However, for B2B users to sign in to the SaaS application using Azure AD, the SaaS application must have its SAML-based single sign-on capability configured in a specific way. For more information on how to configure SaaS applications to support sign-ins from B2B users, see [Configure SaaS apps for B2B collaboration](../external-identities/configure-saas-apps.md).
 
-Note that the userPrincipalName for a guest user is often stored as "alias#EXT#@domain.com". when the userPrincipalName is included in your attribute mappings as a source attribute, the #EXT# is stripped from the userPrincipalName. If you require the #EXT# to be present, replace userPrincipalName with originalUserPrincipalName as the source attribute. 
+> [!NOTE]
+The userPrincipalName for a guest user is often displayed as "alias#EXT#@domain.com". When the userPrincipalName is included in your attribute mappings as a source attribute, the #EXT# is stripped from the userPrincipalName. If you require the #EXT# to be present, replace userPrincipalName with originalUserPrincipalName as the source attribute. 
+
+userPrincipalName = [email protected]
+originalUserPrincipalName = alias#EXT#@domain.com
 
 ## Provisioning cycles: Initial and incremental
 

articles/active-directory/develop/msal-net-migration-confidential-client.md

@@ -35,7 +35,7 @@ For app registrations:
    - A `resourceId` string. This variable is the app ID URI of the web API that you want to call.
    - An instance of `IClientAssertionCertificate` or `ClientAssertion`. This instance provides the client credentials for your app to prove the identity of your app.
 
-1. After you've identified that you have apps that are using ADAL.NET, install the MSAL.NET NuGet package [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) and update your project library references. For more information, see [Install a NuGet package](https://www.bing.com/search?q=install+nuget+package). If you want to use token cache serializers, also install [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web).
+1. After you've identified that you have apps that are using ADAL.NET, install the MSAL.NET NuGet package [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) and update your project library references. For more information, see [Install a NuGet package](https://www.bing.com/search?q=install+nuget+package). If you want to use token cache serializers, also install [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache).
 
 1. Update the code according to the confidential client scenario. Some steps are common and apply across all the confidential client scenarios. Other steps are unique to each scenario. 
 

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

@@ -10,7 +10,7 @@ ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 08/28/2021
+ms.date: 09/30/2021
 ms.author: jmprieur
 ms.reviewer: mmacy
 ms.custom: "devx-track-csharp, aaddev, has-adal-ref"
@@ -24,15 +24,15 @@ After it [acquires a token](msal-acquire-cache-tokens.md), Microsoft Authenticat
 ## Quick summary
 
 The recommendation is:
-- In web apps and web APIs, use [token cache serializers from "Microsoft.Identity.Web"](https://github.com/AzureAD/microsoft-identity-web/wiki/token-cache-serialization). They even provide distributed database or cache system to store tokens.
-  - In ASP.NET Core [web apps](scenario-web-app-call-api-overview.md) and [web API](scenario-web-api-call-api-overview.md), use Microsoft.Identity.Web as a higher-level API in ASP.NET Core.
-  - In ASP.NET classic, .NET Core, .NET framework, use MSAL.NET directly with [token cache serialization adapters for MSAL]() provided in Microsoft.Identity.Web. 
+- In web apps and web APIs, use [token cache serializers from "Microsoft.Identity.Web.TokenCache"](https://github.com/AzureAD/microsoft-identity-web/wiki/token-cache-serialization). They even provide distributed database or cache system to store tokens.
+  - In ASP.NET Core [web apps](scenario-web-app-call-api-overview.md) and [web API](scenario-web-api-call-api-overview.md), use [Microsoft.Identity.Web](microsoft-identity-web.md) as a higher-level API in ASP.NET Core.
+  - In ASP.NET classic, .NET Core, .NET framework, use MSAL.NET directly with [token cache serialization adapters for MSAL](msal-net-token-cache-serialization.md?tabs=aspnet) provided in the Microsoft.Identity.Web.TokenCache NuGet package. 
 - In desktop applications (which can use file system to store tokens), use [Microsoft.Identity.Client.Extensions.Msal](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/wiki/Cross-platform-Token-Cache) with MSAL.Net.
 - In mobile applications (Xamarin.iOS, Xamarin.Android, Universal Windows Platform) don't do anything, as MSAL.NET handles the cache for you: these platforms have a secure storage.
 
 ## [ASP.NET Core web apps and web APIs](#tab/aspnetcore)
 
-The [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) library provides a NuGet package [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) containing token cache serialization:
+The [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) library provides a NuGet package [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache) containing token cache serialization:
 
 | Extension Method | Description  |
 | ---------------- | ------------ |
@@ -116,11 +116,11 @@ Their usage is featured in the [ASP.NET Core web app tutorial](/aspnet/core/tuto
 
 ## [Non ASP.NET Core web apps and web APIs](#tab/aspnet)
 
-Even when you use MSAL.NET, you can benefit from token cache serializers brought in Microsoft.Identity.Web 
+Even when you use MSAL.NET, you can benefit from token cache serializers brought in Microsoft.Identity.Web.TokenCache 
 
 ### Referencing the NuGet package
 
-Add the [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) NuGet package to your project in addition to MSAL.NET
+Add the [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache) NuGet package to your project in addition to MSAL.NET
 
 ### Configuring the token cache
 
@@ -145,7 +145,7 @@ public static async Task<AuthenticationResult> GetTokenAsync(string clientId, X5
        .Build();
 
      // Add a static in-memory token cache. Other options available: see below
-     app.AddInMemoryTokenCache();  // Microsoft.Identity.Web 1.16+
+     app.AddInMemoryTokenCache();  // Microsoft.Identity.Web.TokenCache 1.17+
    
      // Make the call to get a token for client_credentials flow (app to app scenario) 
      return await app.AcquireTokenForClient(scopes).ExecuteAsync();
@@ -280,18 +280,6 @@ var app = ConfidentialClientApplicationBuilder
 	.WithCacheSynchronization(false)
 	.Build();
 ```
-
-### Monitor cache hit ratios and cache performance
-
-MSAL exposes important metrics as part of [AuthenticationResult.AuthenticationResultMetadata](/dotnet/api/microsoft.identity.client.authenticationresultmetadata) object: 
-
-| Metric       | Meaning     | When to trigger an alarm?    |
-| :-------------: | :----------: | :-----------: |
-|  `DurationTotalInMs` | Total time spent in MSAL, including network calls and cache   | Alarm on overall high latency (> 1 s). Value depends on token source. From the cache: one cache access. From AAD: two cache accesses + one HTTP call. First ever call (per-process) will take longer because of one extra HTTP call. |
-|  `DurationInCacheInMs` | Time spent loading or saving the token cache, which is customized by the app developer (for example, save to Redis).| Alarm on spikes. |
-|  `DurationInHttpInMs`| Time spent making HTTP calls to AAD.  | Alarm on spikes.|
-|  `TokenSource` | Indicates the source of the token. Tokens are retrieved from the cache much faster (for example, ~100 ms versus ~700 ms). Can be used to monitor and alarm the cache hit ratio. | Use with `DurationTotalInMs` |
-
 ### Samples
 
 - Using the token cache serializers in a .NET Framework and .NET Core applications is showed-cased in this sample [ConfidentialClientTokenCache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache) 
@@ -339,6 +327,24 @@ cacheHelper.RegisterCache(pca.UserTokenCache);
 
 ```
 
+
+##### Plain text fallback mode
+
+The cross platform token cache allows you to store unencrypted tokens in clear text. This is intended for use in development environments for debugging purposes only. 
+You can use the plain text fallback mode using the following code pattern.
+
+```csharp
+storageProperties =
+    new StorageCreationPropertiesBuilder(
+        Config.CacheFileName + ".plaintext",
+        Config.CacheDir)
+    .WithUnprotectedFile()
+    .Build();
+
+var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties).ConfigureAwait(false);
+```
+
+
 ## [Mobile apps](#tab/mobile)
 
 In MSAL.NET, an in-memory token cache is provided by default. Serialization is provided by default for platforms where secure storage is available for a user as part of the platform: Universal Windows Platform (UWP), Xamarin.iOS, and Xamarin.Android.
@@ -592,21 +598,17 @@ namespace CommonCacheMsalV3
 
 ---
 
-## Plain text fallback mode
+## Monitor cache hit ratios and cache performance
 
-MSAL allows you to store unencrypted tokens in clear text. This is intended for use in development environments for debugging purposes only. 
-You can use the plain text fallback mode using the following code pattern.
+MSAL exposes important metrics as part of [AuthenticationResult.AuthenticationResultMetadata](/dotnet/api/microsoft.identity.client.authenticationresultmetadata) object. You can log these metrics to assess the health of your application.
 
-```csharp
-storageProperties =
-    new StorageCreationPropertiesBuilder(
-        Config.CacheFileName + ".plaintext",
-        Config.CacheDir)
-    .WithUnprotectedFile()
-    .Build();
+| Metric       | Meaning     | When to trigger an alarm?    |
+| :-------------: | :----------: | :-----------: |
+|  `DurationTotalInMs` | Total time spent in MSAL, including network calls and cache   | Alarm on overall high latency (> 1 s). Value depends on token source. From the cache: one cache access. From AAD: two cache accesses + one HTTP call. First ever call (per-process) will take longer because of one extra HTTP call. |
+|  `DurationInCacheInMs` | Time spent loading or saving the token cache, which is customized by the app developer (for example, save to Redis).| Alarm on spikes. |
+|  `DurationInHttpInMs`| Time spent making HTTP calls to AAD.  | Alarm on spikes.|
+|  `TokenSource` | Indicates the source of the token. Tokens are retrieved from the cache much faster (for example, ~100 ms versus ~700 ms). Can be used to monitor and alarm the cache hit ratio. | Use with `DurationTotalInMs` |
 
-var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties).ConfigureAwait(false);
-```
 
 ## Next steps
 

articles/active-directory/hybrid/reference-connect-version-history.md

@@ -53,6 +53,26 @@ However, if you'd like all the latest features and updates, the best way to see
  - If you are still using an older version of Windows Server you should use Azure AD Connect V1.6. You can download the latest version of Azure AD Connect V1 using [this link](https://www.microsoft.com/download/details.aspx?id=103336). 
  - We are only applying critical changes to the V1 versions going forward, and you may not find some of the features and fixes for V2 in the V1 releases - so you should upgrade to the V2 version as soon as possible.
 
+## 2.0.28.0
+
+>[!NOTE] 
+> This is a maintenance update release of Azure AD Connect. This release requires Windows Server 2016 or newer.
+
+### Release status
+9/30/2021: Released for download only, not available for auto upgrade.
+
+### Bug fixes
+ - On the Group Writeback Permissions page in the Wizard we removed a download button for a PowerShell script and changed the text on the wizard page to include a learn more link, which links to an online article where the PowerShell script can be found.
+
+ - We fixed a bug where the wizard was incorrectly blocking the installation when the .NET version on the server was greater than 4.6, due to missing registry keys. Those registry keys are not required and should only block installation if they are intentionally set to false.
+
+- We fixed a bug where an error would be thrown if phantom objects are found during during the initialization of a sync step. This would block the sync step or remove transient objects. The phantom objects are now ignored.
+Note: A phantom object is a placeholder for an object which is not there or has not been seen yet, for example if a source object has a reference for a target object which is not there then we create the target object as a phantom.
+
+### Functional changes
+
+ - A change was made that allows a user to deselect objects and attributes from the inclusion list, even if they are in use. Instead of blocking this, we now provide a warning. 
+
 ## 1.6.14.2
 >[!NOTE] 
 >This is an update release of Azure AD Connect. This version is intended to be used by customers who are running an older version of Windows Server and cannot upgrade their server to Windows Server 2016 or newer at this time. You cannot use this version to update an Azure AD Connect V2.0 server.

articles/active-directory/hybrid/tshoot-connect-sso.md

@@ -123,8 +123,12 @@ If troubleshooting didn't help, you can manually reset the feature on your tenan
    >The domain administrator account used must not be a member of the Protected Users group. If so, the operation will fail.
 
 2. Call `Disable-AzureADSSOForest -OnPremCredentials $creds`. This command removes the `AZUREADSSOACC` computer account from the on-premises domain controller for this specific Active Directory forest.
-3. Repeat the preceding steps for each Active Directory forest where you’ve set up the feature.
 
+   >[!NOTE]
+   >If for any reason you can't access your AD on-premises, you can skip **steps 3.1** and **3.2** and instead call `Disable-AzureADSSOForest -DomainFqdn <Domain name from the output list in step 2>`. 
+   
+3. Repeat the preceding steps for each Active Directory forest where you’ve set up the feature.
+
 ### Step 4: Enable Seamless SSO for each Active Directory forest
 
 1. Call `Enable-AzureADSSOForest`. When prompted, enter the domain administrator credentials for the intended Active Directory forest.

articles/active-directory/hybrid/whatis-azure-ad-connect-v2.md

@@ -73,7 +73,7 @@ This upgrade is especially important since we have had to update our prerequisit
 No – this release does not contain any new functionality. This release only contains updates of some of the foundational components on Azure AD Connect. 
 
 **Can I upgrade from any previous version to V2.0?** </br>
-Yes – upgrades from any previous version of Azure AD Connect to Azure AD Connect V2.0 is supported. Please follow the guidance in this article to determine what is the best upgrade strategy for you. 
+Yes – upgrades from any previous version of Azure AD Connect to Azure AD Connect V2.0 is supported. Please follow the guidance in [this article](how-to-upgrade-previous-version.md) to determine what is the best upgrade strategy for you. 
 
 **Can I export the configuration of my current server and import it in Azure AD Connect V2.0?** </br>
 Yes, you can do that, and it is a great way to migrate to Azure AD Connect V2.0 – especially if you are also upgrading to a new operating system version. You can read more about the Import/export configuration feature and how you can use it in this [article](how-to-connect-import-export-config.md). 

articles/aks/upgrade-cluster.md

@@ -173,6 +173,13 @@ az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrad
 
 If you are using Planned Maintenance as well as Auto-Upgrade, your upgrade will start during your specified maintenance window. For more details on Planned Maintenance, see [Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster (preview)][planned-maintenance].
 
+## Special considerations for node pools that span multiple Availability Zones
+
+AKS uses best-effort zone balancing in node groups. During an Upgrade surge, zone(s) for the surge node(s) in VMSS is unknown ahead of time. This can temporarily cause an unbalanced zone configuration during an upgrade. However, AKS deletes the surge node(s) once the upgrade has been completed and preserves the original zone balance. If you desire to keep your zones balanced during upgrade, increase the surge to a multiple of 3 nodes. VMSS will then balance your nodes across Availability Zones with best-effort zone balancing.
+
+If you have PVCs backed by Azure LRS Disks, they will be bound to a particular zone and may fail to recover immediately if the surge node does not match the zone of the PVC. This could cause downtime on your application when the Upgrade operation continues to drain nodes but the PVs are bound to a zone. To handle this case and maintain high availability, configure a [Pod Disruption Budget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) on your application. This allows Kubernetes to respect your availability requirements during Upgrade's drain operation. 
+
+
 ## Next steps
 
 This article showed you how to upgrade an existing AKS cluster. To learn more about deploying and managing AKS clusters, see the set of tutorials.

articles/app-service/configure-authentication-provider-openid-connect.md

@@ -12,7 +12,7 @@ ms.reviewer: mahender
 
 This article shows you how to configure Azure App Service or Azure Functions to use a custom authentication provider that adheres to the [OpenID Connect specification](https://openid.net/connect/). OpenID Connect (OIDC) is an industry standard used by many identity providers (IDPs). You do not need to understand the details of the specification in order to configure your app to use an adherent IDP.
 
-Your can configure your app to use one or more OIDC providers. Each must be given a unique name in the configuration, and only one can serve as the default redirect target.
+You can configure your app to use one or more OIDC providers. Each must be given a unique name in the configuration, and only one can serve as the default redirect target.
 
 > [!CAUTION]
 > Enabling an OpenID Connect provider will disable management of the App Service Authentication / Authorization feature for your application through some clients, such as the Azure portal, Azure CLI, and Azure PowerShell. The feature relies on a new API surface which, during preview, is not yet accounted for in all management experiences.