Merge branch 'release-windows-2302' of https://github.com/MicrosoftDocs/windows-docs-pr into CIUpdateInfo-6544872

education/windows/configure-aad-google-trust.md

@@ -1,7 +1,7 @@
 ---
 title: Configure federation between Google Workspace and Azure AD
 description: Configuration of a federated trust between Google Workspace and Azure AD, with Google Workspace acting as an identity provider (IdP) for Azure AD.
-ms.date: 02/10/2023
+ms.date: 02/24/2023
 ms.topic: how-to
 ---
 
@@ -24,7 +24,8 @@ To test federation, the following prerequisites must be met:
 
 1. A Google Workspace environment, with users already created
     > [!IMPORTANT]
-    > Users require an email address defined in Google Workspace, which is used to match the users in Azure AD
+    > Users require an email address defined in Google Workspace, which is used to match the users in Azure AD.
+    > For more information about identity matching, see [Identity matching in Azure AD](federated-sign-in.md#identity-matching-in-azure-ad).
 1. Individual Azure AD accounts already created: each Google Workspace user will require a matching account defined in Azure AD. These accounts are commonly created through automated solutions, for example:
     - School Data Sync (SDS)
     - Azure AD Connect sync for environment with on-premises AD DS
@@ -38,14 +39,14 @@ To test federation, the following prerequisites must be met:
 1. Select **Add app > Search for apps** and search for *microsoft*
 1. In the search results page, hover over the *Microsoft Office 365 - Web (SAML)* app and select **Select**
    :::image type="content" source="images/google/google-admin-search-app.png" alt-text="Screenshot showing Google Workspace and the search button for Microsoft Office 365 SAML app.":::
-1. On the *Google Identity Provider details* page, select **Download Metadata** and take note of the location where the **IdP metadata** - *GoogleIDPMetadata.xml* - file is saved, as it will be used to setup Azure AD later
-1. On the *Service provider details* page
+1. On the **Google Identity Provider details** page, select **Download Metadata** and take note of the location where the **IdP metadata** - *GoogleIDPMetadata.xml* - file is saved, as it will be used to setup Azure AD later
+1. On the **Service provider detail*s** page
       - Select the option **Signed response**
       - Verify that the Name ID format is set to **PERSISTENT**
       - Depending on how the Azure AD users have been provisioned in Azure AD, you may need to adjust the **Name ID** mapping.\
         If using Google auto-provisioning, select **Basic Information > Primary email**
       - Select **Continue**
-1. On the *Attribute mapping* page, map the Google attributes to the Azure AD attributes
+1. On the **Attribute mapping** page, map the Google attributes to the Azure AD attributes
 
     |Google Directory attributes|Azure AD attributes|
     |-|-|

education/windows/federated-sign-in.md

@@ -1,7 +1,7 @@
 ---
 title: Configure federated sign-in for Windows devices
 description: Description of federated sign-in feature for the Education SKUs of Windows 11 and how to configure it via Intune or provisioning packages.
-ms.date: 02/10/2023
+ms.date: 02/24/2023
 ms.topic: how-to
 appliesto:
   - ✅ <a href="https://learn.microsoft.com/windows/release-health/supported-versions-windows-client" target="_blank">Windows 11</a>
@@ -13,7 +13,9 @@ ms.collection:
 
 # Configure federated sign-in for Windows devices
 
-Starting in Windows 11 SE, version 22H2 and Windows 11 Pro Edu/Education, version 22H2 with [KB5022913][KB-1], you can enable your users to sign-in using a federated identity provider (IdP) via web sign-in. This feature is called *federated sign-in*. Federated sign-in is a great way to simplify the sign-in process for your users: instead of having to remember a username and password defined in Azure AD, they can sign-in using their existing credentials from the IdP. For example, students and educators can use QR code badges to sign-in.
+Starting in Windows 11 SE, version 22H2 and Windows 11 Pro Edu/Education, version 22H2 with [KB5022913][KB-1], you can enable your users to sign-in using a federated identity provider (IdP) via web sign-in.\
+This feature is called *federated sign-in*.\
+Federated sign-in is a great way to simplify the sign-in process for your users: instead of having to remember a username and password defined in Azure AD, they can sign-in using their existing credentials from the IdP. For example, students and educators can use QR code badges to sign-in.
 
 ## Benefits of federated sign-in
 
@@ -38,18 +40,25 @@ To implement federated sign-in, the following prerequisites must be met:
     - [Azure AD Connect sync][AZ-3] for environment with on-premises AD DS
     - PowerShell scripts that call the [Microsoft Graph API][GRAPH-1]
     - provisioning tools offered by the IdP
+    
+    For more information about identity matching, see [Identity matching in Azure AD](#identity-matching-in-azure-ad).
 1. Licenses assigned to the Azure AD user accounts. It's recommended to assign licenses to a dynamic group: when new users are provisioned in Azure AD, the licenses are automatically assigned. For more information, see [Assign licenses to users by group membership in Azure Active Directory][AZ-2]
-1. Enable federated sign-in on the Windows devices that the users will be using
-    > [!IMPORTANT]
-    > This feature is exclusively available for Windows Education SKUs, including Windows 11 SE, Windows 11 Pro Education and Windows Education.
+1. Enable federated sign-in on the Windows devices
 
 To use federated sign-in, the devices must have Internet access. This feature won't work without it, as the authentication is done over the Internet.
 
 > [!IMPORTANT]
-> WS-Fed is the only supported federated protocol to join a device to Azure AD. If you have a SAMl 2.0 IdP, it's recommended to complete the Azure AD join process using one of the following methods:
+> WS-Fed is the only supported federated protocol to join a device to Azure AD. If you have a SAML 2.0 IdP, it's recommended to complete the Azure AD join process using one of the following methods:
 > - provisioning packages (PPKG)
 > - Windows Autopilot self-deploying mode
 
+### System requirements
+
+Federated sign-in is supported on the following Windows SKUs and versions:
+
+- Windows 11 SE, version 22H2 and later
+- Windows 11 Pro Edu/Education, version 22H2 with [KB5022913][KB-1]
+
 ## Configure federated sign-in
 
 To use web sign-in with a federated identity provider, your devices must be configured with different policies. Follow the instructions below to configure your devices using either Microsoft Intune or a provisioning package (PPKG).
@@ -81,7 +90,7 @@ To configure federated sign-in using a provisioning package, use the following s
 | <li> Path: **`FederatedAuthentication/EnableWebSignInForPrimaryUser`** </li><li>Value: **Enabled**</li>|
 | <li> Path: **`Policies/Authentication/ConfigureWebSignInAllowedUrls`** </li><li>Value: Semicolon separated list of domains, for example: **`samlidp.clever.com;clever.com;mobile-redirector.clever.com`**</li>|
 | <li> Path: **`Policies/Education/IsEducationEnvironment`** </li><li>Value: **Enabled**</li>|
-| <li> Path: **`Policies/Authentication/ConfigureWebCamAccessDomainNames`** </li><li>Value: This setting is optional, and it should be configured if you need to use the webcam during the sign-in process. Specify the list of domains that are allowed to use the webcam during he sign-in process, separated by a semicolon. For example: **`clever.com`**</li>|
+| <li> Path: **`Policies/Authentication/ConfigureWebCamAccessDomainNames`** </li><li>Value: This setting is optional, and it should be configured if you need to use the webcam during the sign-in process. Specify the list of domains that are allowed to use the webcam during the sign-in process, separated by a semicolon. For example: **`clever.com`**</li>|
 
 :::image type="content" source="images/federated-sign-in-settings-ppkg.png" alt-text="Custom policy showing the settings to be configured to enable federated sign-in" lightbox="images/federated-sign-in-settings-ppkg.png" border="true":::
 
@@ -109,7 +118,39 @@ Federated sign-in doesn't work on devices that have the following settings enabl
 
 - **EnableSharedPCMode**, which is part of the [SharedPC CSP][WIN-1]
 - **Interactive logon: do not display last signed in**, which is a security policy part of the [Policy CSP][WIN-2]
-- **Take a Test**, since it leverages the security policy above
+- **Take a Test**, since it uses the security policy above
+
+### Identity matching in Azure AD
+
+When an Azure AD user is federated, the user's identity from the IdP must match an existing user object in Azure AD.
+After the token sent by the IdP is validated, Azure AD searches for a matching user object in the tenant by using an attribute called *ImmutableId*.
+
+> [!NOTE]
+> The ImmutableId is a string value that **must be unique** for each user in the tenant, and it shouldn't change over time. For example, the ImmutableId could be the student ID or SIS ID. The ImmutableId value should be based on the federation setup and configuration with your IdP, so confirm with your IdP before setting it.
+
+If the matching object is found, the user is signed-in. If not, the user is presented with an error message. The following picture shows that a user with the ImmutableId *260051* can't be found:
+
+:::image type="content" source="images/federation/user-match-lookup-failure.png" alt-text="Azure AD sign-in error: a user with a matching ImmutableId can't be found in the tenant." lightbox="images/federation/user-match-lookup-failure.png":::
+
+> [!IMPORTANT]
+> The ImmutableId matching is case-sensitive.
+
+The ImmutableId is typically configured when the user is created in Azure AD, but it can also be updated later.\
+In a scenario where a user is federated and you want to change the ImmutableId, you must:
+
+1. Convert the federated user to a cloud-only user (update the UPN to a non-federated domain)
+1. Update the ImmutableId
+1. Convert the user back to a federated user
+
+Here's a PowerShell example to update the ImmutableId for a federated user:
+
+```powershell
+#1. Convert the user from federated to cloud-only
+Get-AzureADUser -SearchString alton@example.com | Set-AzureADUser -UserPrincipalName alton@example.onmicrosoft.com
+
+#2. Convert the user back to federated, while setting the immutableId
+Get-AzureADUser -SearchString alton@example.onmicrosoft.com | Set-AzureADUser -UserPrincipalName alton@example.com -ImmutableId '260051'
+```
 
 ## Troubleshooting
 
@@ -119,21 +160,20 @@ Federated sign-in doesn't work on devices that have the following settings enabl
 <!--links-->
 
 [AZ-1]: /azure/active-directory/hybrid/whatis-fed
-[AZ-4]: /azure/active-directory/hybrid/how-to-connect-fed-saml-idp
 [AZ-2]: /azure/active-directory/enterprise-users/licensing-groups-assign
 [AZ-3]: /azure/active-directory/hybrid/how-to-connect-sync-whatis
+[AZ-4]: /azure/active-directory/hybrid/how-to-connect-fed-saml-idp
 
 [GRAPH-1]: /graph/api/user-post-users?tabs=powershell
 
+[EXT-1]: https://support.clever.com/hc/s/articles/000001546
 [MEM-1]: /mem/intune/configuration/custom-settings-windows-10
 
 [MSFT-1]: https://www.microsoft.com/download/details.aspx?id=56843
 
 [SDS-1]: /schooldatasync
 
-[WIN-1]: /windows/client-management/mdm/sharedpc-csp
-[WIN-2]: /windows/client-management/mdm/policy-csp-localpoliciessecurityoptions#localpoliciessecurityoptions-interactivelogon-donotdisplaylastsignedin
-
 [KB-1]: https://support.microsoft.com/kb/5022913
 
-[EXT-1]: https://support.clever.com/hc/s/articles/000001546
+[WIN-1]: /windows/client-management/mdm/sharedpc-csp
+[WIN-2]: /windows/client-management/mdm/policy-csp-localpoliciessecurityoptions#localpoliciessecurityoptions-interactivelogon-donotdisplaylastsignedin