PM-fine-tuning

shlipsey3 · shlipsey3 · commit 1ec44e2c6ba2 · 2023-03-06T11:39:38.000-07:00
diff --git a/articles/active-directory/reports-monitoring/howto-use-recommendations.md b/articles/active-directory/reports-monitoring/howto-use-recommendations.md
@@ -42,6 +42,7 @@ Some recommendations may require a P2 or other license. For more information, se
 ## How to read a recommendation
 
 To view the details of a recommendation:
+
 1. Sign in to Azure using the appropriate least-privilege role.
 1. Go to **Azure AD** > **Recommendations** and select a recommendation from the list.
 
@@ -69,7 +70,7 @@ Each recommendation provides the same set of details that explain what the recom
 
 - The **Action plan** provides step-by-step instructions to implement a recommendation. The Action plan may include links to relevant documentation or direct you to other pages in the Azure AD portal.
 
-- If the impacted resource type is applications, a list of the **Impacted resources** appears at the bottom of the recommendation. The resource's name, ID, date it was first detected, and status are provided.
+- The **Impacted resources** table contains a list of resources identified by the recommendation. The resource's name, ID, date it was first detected, and status are provided. The resource could be an application or resource service principal, for example. 
 
 ## How to update a recommendation
 
@@ -105,7 +106,7 @@ Continue to monitor the recommendations in your tenant for changes.
 
 ### How to use Microsoft Graph with Azure Active Directory recommendations
 
-Azure Active Directory recommendations can be viewed and managed using Microsoft Graph on the `/beta` endpoint. You can view recommendations along with their impacted resources, mark a recommendation as completed by a user, postpone a recommendation for later, and more. 
+Azure Active Directory recommendations can be viewed and managed using Microsoft Graph on the `/beta` endpoint. You can view recommendations along with their impacted resources, postpone a recommendation for later, and more. 
 
 To get started, follow these instructions to work with recommendations using Microsoft Graph in Graph Explorer. The example uses the "Migrate apps from Active Directory Federated Services (ADFS) to Azure AD" recommendation.
 
diff --git a/articles/active-directory/reports-monitoring/overview-recommendations.md b/articles/active-directory/reports-monitoring/overview-recommendations.md
@@ -53,11 +53,11 @@ The recommendations listed in the following table are currently available in pub
 | [Convert per-user MFA to Conditional Access MFA](recommendation-turn-off-per-user-mfa.md) | Users | All licenses | Generally available |
 | [Migrate applications from AD FS to Azure AD](recommendation-migrate-apps-from-adfs-to-azure-ad.md) | Applications | All licenses | Generally available |
 | [Migrate to Microsoft Authenticator](recommendation-migrate-to-authenticator.md) | Users | All licenses | Preview |
-| [Minimize MFA prompts from known devices](recommendation-migrate-apps-from-adfs-to-azure-ad.md)  | Users | All licenses | Generally available |
-| [Remove unused applications](recommendation-remove-unused-apps.md) | Applications | P2 | Preview |
-| [Remove unused credentials from applications](recommendation-remove-unused-credential-from-apps.md) | Applications | P2 | Preview |
-| [Renew expiring application credentials](recommendation-renew-expiring-application-credential.md) | Applications | P2 | Preview |
-| [Renew expiring service principal credentials](recommendation-renew-expiring-service-principal-credential.md) | Applications | P2 | Preview |
+| [Minimize MFA prompts from known devices](recommendation-mfa-from-known-devices.md)  | Users | All licenses | Generally available |
+| [Remove unused applications](recommendation-remove-unused-apps.md) | Applications | Azure AD Premium P2 | Preview |
+| [Remove unused credentials from applications](recommendation-remove-unused-credential-from-apps.md) | Applications | Azure AD Premium P2 | Preview |
+| [Renew expiring application credentials](recommendation-renew-expiring-application-credential.md) | Applications | Azure AD Premium P2 | Preview |
+| [Renew expiring service principal credentials](recommendation-renew-expiring-service-principal-credential.md) | Applications | Azure AD Premium P2 | Preview |
 
 Azure AD only displays the recommendations that apply to your tenant, so you may not see all supported recommendations listed.
 
diff --git a/articles/active-directory/reports-monitoring/recommendation-remove-unused-apps.md b/articles/active-directory/reports-monitoring/recommendation-remove-unused-apps.md
@@ -20,7 +20,7 @@ This article covers the recommendation to investigate unused applications. This
 
 ## Description
 
-This recommendation shows up if your tenant has applications that haven't been used in more than 30 days, so haven't been issued any tokens. Applications or service principals that were added but never used will show up as unused apps, which will also trigger this recommendation.
+This recommendation shows up if your tenant has applications that haven't been used in more than 30 days, so haven't been issued any tokens. Applications or service principals that were added but never used show up as unused apps, which will also trigger this recommendation.
 
 ## Value 
 
@@ -35,22 +35,25 @@ Applications that the recommendation identified appear in the list of **Impacted
 
     ![Screenshot of the Azure AD app registration area, with the App registrations menu item highlighted.](media/recommendation-remove-unused-apps/app-registrations-list.png)
 
-1. We suggest you take appropriate steps to ensure the application is not used in longer intervals of more than 30 days. If so, we recommend updating the frequency of access such that the application’s last used time is within 30 days from its last access date.
+1. Determine if the identified application is needed.
+    - If the application is no longer needed, remove it from your tenant.
+    - If the application is needed, we suggest you take appropriate steps to ensure the application isn't used in intervals of more than 30 days.
+    - We recommend updating the frequency of access such that the application’s last used time is within 30 days from its last access date.
 
 ## Known limitations
 
 Take note of the following common scenarios or known limitations of the "Remove unused applications" recommendation.
 
-* The time frame for application usage that triggers this recommendation cannot be customized.
+* The time frame for application usage that triggers this recommendation can't be customized.
 
-* The following apps will not show up as a part of this recommendation, but are currently under review for future enhancements: 
+* The following apps won't show up as a part of this recommendation, but are currently under review for future enhancements: 
     - Microsoft-owned applications
     - Password single sign-on
     - Linked single sign-on
     - App proxy
     - Add-in apps
 
-* This recommendation currently surfaces applications that were created within the past 30 days *and* shows as unused. Updates to the recommendation to filter out newly-created apps so that they can complete a full cycle are in progress.
+* This recommendation currently surfaces applications that were created within the past 30 days *and* shows as unused. Updates to the recommendation to filter out recently created apps so that they can complete a full cycle are in progress.
 
 ## Next steps
 
diff --git a/articles/active-directory/reports-monitoring/recommendation-remove-unused-credential-from-apps.md b/articles/active-directory/reports-monitoring/recommendation-remove-unused-credential-from-apps.md
@@ -47,11 +47,20 @@ Applications that the recommendation identified appear in the list of **Impacted
 
     ![Screenshot of the Certificates & secrets area of app registrations.](media/recommendation-remove-unused-credential-from-apps/app-certificates-secrets.png)
 
-To remove a credential from a service principal resource, use the MS Graph Service Principal API service action `removePassword`.
- 
+### Use Microsoft Graph to remove an unused credential
+
+To get started, see [How to use Microsoft Graph with Azure AD recommendations](howto-use-recommendations.md#how-to-use-microsoft-graph-with-azure-active-directory-recommendations).
+
+- Remove a **credential** from a service principal resource:
+    - Use the Microsoft Graph Service Principal API service action `removePassword`
+    - [servicePrincipal: removePassword MS Graph API documentation](/graph/api/serviceprincipal-removepassword?view=graph-rest-beta&preserve-view=true)
+- Remove a **key credential** from a service principal resource:
+    - Use the Microsoft Graph Service Principal API service action `removeKey`
+    - [servicePrincipal: removeKey MS Graph API documentation](/graph/api/serviceprincipal-removekey?view=graph-rest-beta&preserve-view=true)
+
 ## Next steps
 
 - [Review the Azure AD recommendations overview](overview-recommendations.md)
 - [Learn how to use Azure AD recommendations](howto-use-recommendations.md)
-- [Explore the Microsoft Graph API properties for recommendations](/graph/api/resources/recommendation)
+- [Explore the Microsoft Graph API properties for recommendations](/graph/api/resources/recommendations-api-overview)
 - [Learn about app and service principal objects in Azure AD](../develop/app-objects-and-service-principals.md)
diff --git a/articles/active-directory/reports-monitoring/recommendation-renew-expiring-application-credential.md b/articles/active-directory/reports-monitoring/recommendation-renew-expiring-application-credential.md
@@ -46,8 +46,9 @@ Applications that the recommendation identified appear in the list of **Impacted
 
     ![Screenshot of the Certificates & secrets area of app registrations.](media/recommendation-renew-expiring-application-credential/app-certificates-secrets.png)
 
-1. Once the certificate or secret is successfully added, update the service code to ensure it works with the new credential and has no negative customer impact. You should use Azure AD’s sign-in logs to validate that the thumbprint of the certificate matches the one that was just uploaded.
-1. After validating the new credential, navigate back to the Certificates and Secrets blade for the app and remove the old credential.
+1. Once the certificate or secret is successfully added, update the service code to ensure it works with the new credential and doesn't negatively affect customers.
+1. Use the Azure AD sign-in logs to validate that the thumbprint of the certificate matches the one that was recently uploaded.
+1. After validating the new credential, navigate back to **Azure AD** > **App registrations** > **Certificates and Secrets** for the app and remove the old credential.
  
 ## Known limitations
 
diff --git a/articles/active-directory/reports-monitoring/recommendation-renew-expiring-service-principal-credential.md b/articles/active-directory/reports-monitoring/recommendation-renew-expiring-service-principal-credential.md
@@ -21,7 +21,7 @@ This article covers the recommendation to renew expiring service principal crede
 
 ## Description
 
-An Azure Active Directory (Azure AD) service principal is the local representation of an application object in a single tenant or directory. The service principal defines who can access an application and what resources the application can access. Authentication of service principals is often completed using certificate credentials, which have a lifespan. If the credentials expire, the application will not be able to authenticate with your tenant. 
+An Azure Active Directory (Azure AD) service principal is the local representation of an application object in a single tenant or directory. The service principal defines who can access an application and what resources the application can access. Authentication of service principals is often completed using certificate credentials, which have a lifespan. If the credentials expire, the application won't be able to authenticate with your tenant. 
 
 This recommendation shows up if your tenant has service principals with credentials that will expire soon.
 
@@ -42,20 +42,41 @@ Renewing the service principal credential(s) before expiration ensures the appli
     
     ![Screenshot of the edit single-sign-on process.](media/recommendation-renew-expriring-service-principal-credential/recommendation-edit-sso.png)
 
-1. After adding the certificate, change its properties to make the certificate active. This will make the other certificate inactive.
-1. Once the certificate is successfully added and activated, update the service code to ensure it works with the new credential and has no negative customer impact. You should use Azure AD’s sign-in logs to validate that the thumbprint of the certificate matches the one that was just uploaded.
-1. After validating the new credential, navigate back to the **Certificates and Secrets** area for the app and remove the old credential.
+1. After adding the certificate, change its properties to make the certificate active, which makes the other certificate inactive.
+1. Once the certificate is successfully added and activated, update the service code to ensure it works with the new credential and doesn't negatively affect customers.
+1. Use the Azure AD sign-in logs to validate that the thumbprint of the certificate matches the one that was recently uploaded.
+1. After validating the new credential, navigate back to the **Single sign-on** area for the app and remove the old credential.
+
+### Use Microsoft Graph to renew expiring service principal credentials
+
+To get started, see [How to use Microsoft Graph with Azure AD recommendations](howto-use-recommendations.md#how-to-use-microsoft-graph-with-azure-active-directory-recommendations).
+
+When renewing service principal credentials using Microsoft Graph, you need to run a query to get the password credentials on a service principal, add a new password credential, then remove the old credentials. 
+
+1. Run the following query in Microsoft Graph to get the password credentials on a service principal:
+    - https://graph.microsoft.com/v1.0/servicePrincipals/{id}?$select=passwordCredentials
+    - Replace {id} with the service principal ID.
+
+1. Add a new password credential.
+    - Use the Microsoft Graph Service Principal API service action `addPassword`
+    - [servicePrincipal: addPassword MS Graph API documentation](/graph/api/serviceprincipal-addpassword?view=graph-rest-beta&preserve-view=true)
+
+1. Remove the old/original credentials.
+    - Use the Microsoft Graph Service Principal API service action `removePassword`
+    - [servicePrincipal: removePassword MS Graph API documentation](/graph/api/serviceprincipal-removepassword?view=graph-rest-beta&preserve-view=true) 
 
 ## Known limitations
 
-Service principals that expire before the recommendation is completed by a user will be marked complete by the system. This recommendation identifies service principal credentials that are about to expire, so if they do expire, the recommendation doesn't distinguish between the credential expiring on its own or being addressed by the user.
+- This recommendation identifies service principal credentials that are about to expire, so if they do expire, the recommendation doesn't distinguish between the credential expiring on its own or being addressed by the user.
+
+- Service principal credentials that expire before the recommendation is completed will be marked complete by the system.
+
+- The recommendation currently doesn't display the password secret credential in service principal when you select the impacted resource from the list.
+
 
-You can see the recommendation but won't be able to see the service principal credential when you click on the impacted resource. Credentials are not displayed on the Enterprise applications area. You can use Microsoft Graph to pull this information programmatically. 
- 
 ## Next steps
 
 - [Review the Azure AD recommendations overview](overview-recommendations.md)
 - [Learn how to use Azure AD recommendations](howto-use-recommendations.md)
 - [Explore the Microsoft Graph API properties for recommendations](/graph/api/resources/recommendation)
-- [Learn about securing service principals](../fundamentals/service-accounts-principal.md)
-
+- [Learn about securing service principals](../fundamentals/service-accounts-principal.md)
