Clarify ACS secret renewal after principal creation streamline

Author: jansenbe

docs/sp-add-ins/add-ins-and-azure-acs-retirements-faq.md

@@ -77,7 +77,7 @@ No, both CSOM (client-side object model) and JSOM (JavaScript object model) will
 
 ## When I use appregnew.aspx the created ACS principals show up in Entra
 
-As of December 2024 we've streamlined the app creation flow and as a result ACS principals created using appregnew.aspx now show are created as "regular" Entra app principal versus previously service principals with `legacyServicePrincipal` property set to `Legacy`. These app principals are detected by the [Microsoft 365 Assessment tool](https://aka.ms/microsoft365assessmenttool), however you need version 1.10.0 to ensure the principal validity is correctly reported.
+As of December 2024 we've streamlined the app creation flow and as a result ACS principals created using appregnew.aspx now show are created as "regular" Entra app principal versus previously service principals with `legacyServicePrincipal` property set to `Legacy`. These app principals are detected by the [Microsoft 365 Assessment tool](https://aka.ms/microsoft365assessmenttool), however you need version 1.10.0 to ensure the principal validity is correctly reported. Note, if you want to renew the secret of these principals ensure you're using the right approach as described in [Replace an expiring client secret in a SharePoint Add-in](replace-an-expiring-client-secret-in-a-sharepoint-add-in.md).
 
 ## Do I need to delete Azure ACS principals that are not needed anymore?
 

docs/sp-add-ins/replace-an-expiring-client-secret-in-a-sharepoint-add-in.md

@@ -1,7 +1,7 @@
 ---
 title: Replace an expiring client secret in a SharePoint Add-in
 description: Add a new client secret for a SharePoint Add-in that is registered with AppRegNew.aspx.
-ms.date: 09/09/2024
+ms.date: 04/16/2025
 ms.localizationpriority: high
 ms.service: sharepoint
 ---
@@ -30,7 +30,14 @@ Ensure the following before you begin:
 - You have installed Microsoft Graph Powershell SDK: [Install the Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation)
 - You're a tenant administrator (or having **Application.ReadWrite.All** permission) for the Microsoft 365 tenant where the add-in was registered with the **AppRegNew.aspx** page.
 
-## Generate a new secret
+## Understand the type of your ACS principal before renewing the secret
+
+Historically ACS principals were created as Microsoft Entra service principals having the `servicePrincipalType` set to `Legacy`. As of December 2024 the Microsoft Entra principal creation has been streamlined and ACS principals are now created as application principals in Microsoft Entra. If you browse the Microsoft Entra applications you'll now be able to see the ACS principal you've created as of December 2024. ACS principal creation typically is done using `appregnew.aspx`.
+
+> [!Important]
+> Due to this alternate creation the renewal of ACS principals also differs, below two chapters show both approaches, for the ACS service principals and for the ACS application principals. Ensure you use the correct approach.
+
+## Generate a new secret - for ACS service principals, created before December 2024
 
 1. Create a client ID variable with the following line, using the client ID of the SharePoint Add-in as the parameter:
 
@@ -97,6 +104,47 @@ Ensure the following before you begin:
 > [!IMPORTANT]
 > Wait at least 24 hours for the propagation of the new ClientSecret to SharePoint.
 
+## Generate a new secret - for ACS application principals, created from December 2024 onwards
+
+```PowerShell
+Connect-Graph -Scopes "Application.ReadWrite.All,Directory.ReadWrite.All"
+$applicationId = '<your client id>' # replace with your app id
+$appPrincipal = Get-MgApplication -Filter "AppId eq '$applicationId'"
+$params = @{
+    PasswordCredential = @{
+        DisplayName = "NewSecret" # Replace with a friendly name.
+    }
+}
+$result = Add-MgApplicationPassword -ApplicationId $appPrincipal.Id -BodyParameter $params
+$base64Secret = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($result.SecretText))
+$dtStart = $result.StartDateTime
+$dtEnd = $result.EndDateTime
+$keyCredentials = @(
+    @{
+        Type = "Symmetric"
+        Usage = "Verify"
+        Key = [System.Text.Encoding]::UTF8.GetBytes($result.SecretText)
+        StartDateTime = $dtStart
+        EndDateTime = $dtEnd
+    },
+    @{
+        Type = "Symmetric"
+        Usage = "Sign"
+        Key = [System.Text.Encoding]::UTF8.GetBytes($result.SecretText)
+        StartDateTime = $dtStart
+        EndDateTime = $dtEnd
+    }
+)
+# Add existing valid key credentials to the $keyCredentials
+$appPrincipal.KeyCredentials |%{if ($_.EndDateTime -gt [DateTime]::UtcNow) {$keyCredentials += @($_)}}
+Update-MgApplication -ApplicationId $appPrincipal.Id -KeyCredentials $keyCredentials # Update keys
+$result.SecretText # Print secret text
+$base64Secret # Print base64 secret
+$result.EndDateTime # Print the end date.
+```
+
+> [!IMPORTANT]
+> Wait at least 24 hours for the propagation of the new ClientSecret to SharePoint.
 
 ## Update the remote web application in Visual Studio to use the new secret