edits

Author: ktoliver

docs/pipelines/library/connect-to-azure.md

@@ -25,15 +25,15 @@ You have multiple options for connecting to Azure by using Azure Resource Manage
 * Service principal with secret
 * Agent-assigned managed identity
 
-> To learn about other types of connections and for general information about creating and using connections, see [Service connections for builds and releases](service-endpoints.md).
+To learn about other types of connections and for general information about creating and using connections, see [Service connections for builds and releases](service-endpoints.md).
 
 ::: moniker range="azure-devops"
 
 <a name="create-an-azure-resource-manager-service-connection-using-workload-identity-federation"></a>
 
 ## Create an Azure Resource Manager service connection that uses workload identity federation
 
-[Workload identity federation](/azure/active-directory/workload-identities/workload-identity-federation) uses OpenID Connect to authenticate with Microsoft Entra protected resources without needing to manage secrets.
+[Workload identity federation](/azure/active-directory/workload-identities/workload-identity-federation) uses OpenID Connect (OIDC) to authenticate with Microsoft Entra protected resources without using secrets.
 
 We recommend that you use this approach if all the following items are true for your scenario:
 
@@ -44,15 +44,17 @@ We recommend that you use this approach if all the following items are true for
 
 ### Create a new workload identity federation service connection
 
-1. In the Azure DevOps project, go to **Project settings** > **Service connections** [project settings page](../../project/navigation/go-to-service-page.md#open-project-settings).
+1. In the Azure DevOps project, go to **Project settings** > **Service connections**.
+
+   For more information, see [Open project settings](../../project/navigation/go-to-service-page.md#open-project-settings).
 
 1. Select **New service connection**, and then select **Azure Resource Manager**.
 
-   ![Screenshot that shows choosing a workload identity service connection type.](media/new-service-connection-azure-resource-manager.png)
+   :::image type="content" source="media/new-service-connection-azure-resource-manager.png" alt-text="Screenshot that shows choosing a workload identity service connection type.":::
 
 1. Select **Workload identity federation (automatic)**.
 
-   ![Screenshot that shows selecting a workload identity service connection type.](media/select-workload-identity-service.png)
+   :::image type="content" source="media/select-workload-identity-service.png" alt-text="Screenshot that shows selecting a workload identity service connection type.":::
 
 1. Specify the following parameters:
 
@@ -103,7 +105,7 @@ To revert a service connection:
 
 1. Select **Revert conversion to the original scheme**.
 
-    :::image type="content" source="media/federated-revert-credential.png" alt-text="Screenshot that shows selecting revert for a federated credential.":::
+   :::image type="content" source="media/federated-revert-credential.png" alt-text="Screenshot that shows selecting revert for a federated credential.":::
 
 1. Select **Revert** again to confirm your choice.
 
@@ -130,7 +132,7 @@ To create the service connection:
 
 1. Select **New service connection**, and then select **Azure Resource Manager**.
 
-   ![Screenshot that shows choosing a service connection type.](media/new-service-endpoint-2.png)
+   :::image type="content" source="media/new-service-endpoint-2.png" alt-text="Screenshot that shows choosing a service connection type.":::
 
 1. Enter or select the following parameters:
 
@@ -156,7 +158,7 @@ To create the service connection:
 >
 > When you follow this approach, Azure DevOps *connects with Microsoft Entra ID and creates an app registration with a secret that's valid for three months*. When the service connection is about to expire, Microsoft Entra ID displays this prompt: **A certificate or secret is expiring soon. Create a new one**. In this scenario, you must refresh the service connection.
 >
-> To refresh a service connection, in the Azure DevOps portal, edit the connection and then select **Verify**. After you save the edit, the service connection is valid for another three months.
+> To refresh a service connection, in the Azure DevOps portal, edit the connection, and then select **Verify**. After you save the edit, the service connection is valid for another three months.
 >
 > We recommend that you use workload identity federation instead of creating a secret. If you use workload identity federation, you don't need to rotate secrets, and app registration maintains its intended purpose. To start using workload identity federation, go to the service connection details page and select **Convert**. The service connection is converted to use workload identity federation instead of a secret. For more information, see [Convert an existing Azure Resource Manager service connection to use workload identity federation](#convert-an-existing-azure-resource-manager-service-connection-to-use-workload-identity-federation).
 >
@@ -184,11 +186,11 @@ If you have problems using this approach (such as no subscriptions shown in the
 
 1. Select **New service connection**, and then select **Azure Resource Manager**.
 
-   ![Screenshot that shows choosing a service connection type.](media/new-service-endpoint-2.png)
+   :::image type="content" source="media/new-service-endpoint-2.png" alt-text="Screenshot that shows choosing a service connection type.":::
 
 1. Select the **Service Principal (manual)** option, and then enter the service principal details.
 
-   ![Screenshot that shows opening the full version of the service dialog.](media/rm-endpoint-link.png)
+   :::image type="content" source="media/rm-endpoint-link.png" alt-text="Screenshot that shows opening the full version of the service dialog.":::
 
 1. For **Connection name**, enter a display name to use to refer to this service connection.
 
@@ -226,7 +228,7 @@ For more information, see [Troubleshoot Azure Resource Manager service connectio
 
 <a name="use-msi"></a>
 
-## Create an Azure Resource Manager service connection to a virtual machine that uses a managed service identity
+## Create an Azure Resource Manager service connection to a VM that uses a managed service identity
 
 > [!NOTE]
 >
@@ -242,11 +244,11 @@ You can configure Azure VM-based agents to use an [Azure Managed Service Identit
 
 1. Select **New service connection**, and then select **Azure Resource Manager**.
 
-   ![Screenshot that shows choosing a service connection type.](media/new-service-endpoint-2.png)
+   :::image type="content" source="media/new-service-endpoint-2.png" alt-text="Screenshot that shows choosing a service connection type.":::
 
 1. Select the **Managed Identity Authentication** option.
 
-   ![Screenshot that shows going to the managed service identity settings.](media/rm-endpoint-msi.png)
+   :::image type="content" source="media/rm-endpoint-msi.png" alt-text="Screenshot that shows going to the managed service identity settings.":::
 
 1. For **Connection name**,  enter a display name to use when you refer to this service connection.
 
@@ -270,13 +272,13 @@ You can configure Azure VM-based agents to use an [Azure Managed Service Identit
    For more information, see [How can I use managed identities for Azure resources?](/azure/active-directory/managed-identities-azure-resources/overview#how-can-i-use-managed-identities-for-azure-resources) and
    [Use role-based access control to manage access to your Azure subscription resources](/azure/role-based-access-control/role-assignments-portal).
 
-For more information, see [Troubleshoot Azure Resource Manager service connections](../release/azure-rm-endpoint.md).
+For more information about the process, see [Troubleshoot Azure Resource Manager service connections](../release/azure-rm-endpoint.md).
 
 <a name="connect-govt"></a>
 
 ## Connect to an Azure Government Cloud
 
-For information about connecting to an Azure Government Cloud, see [Connecting from Azure Pipelines (Azure Government Cloud)](/azure/azure-government/documentation-government-get-started-connect-with-vsts).
+For information about connecting to an Azure Government Cloud, see [Connect from Azure Pipelines (Azure Government Cloud)](/azure/azure-government/documentation-government-get-started-connect-with-vsts).
 
 <a name="connect-stack"></a>
 
@@ -285,7 +287,7 @@ For information about connecting to an Azure Government Cloud, see [Connecting f
 For information about connecting to Azure Stack, see these articles:
 
 * [Connect to Azure Stack](/azure/azure-stack/azure-stack-connect-azure-stack)
-* [Connect Azure Stack to Azure by using VPN](/azure/azure-stack/azure-stack-connect-vpn)
-* [Connect Azure Stack to Azure by using ExpressRoute](/azure/azure-stack/azure-stack-connect-expressroute)
+* [Connect Azure Stack to Azure by using a VPN](/azure/azure-stack/azure-stack-connect-vpn)
+* [Connect Azure Stack to Azure by using Azure ExpressRoute](/azure/azure-stack/azure-stack-connect-expressroute)
 
 [!INCLUDE [rm-help-support-shared](../includes/rm-help-support-shared.md)]

docs/pipelines/release/approvals/media/access-control-resource-group.png

@@ -12,13 +12,13 @@ monikerRange: '>= azure-devops'
 
 # Manually set an Azure Resource Manager workload identity service connection
 
-When you [troubleshoot an Azure Resource Manager workload identity service connection](troubleshoot-workload-identity.md#i-dont-have-permissions-to-create-a-service-principal-in-the-micrososft-entra-tenant), you might need to manually configure the connection instead of using the automated tool.
+When you [troubleshoot an Azure Resource Manager workload identity service connection](troubleshoot-workload-identity.md#i-dont-have-permissions-to-create-a-service-principal-in-the-micrososft-entra-tenant), you might need to manually configure the connection instead of using the automated tool that's available in Azure DevOps.
 
 We recommend that you [try the automated approach](../library/connect-to-azure.md#create-an-azure-resource-manager-service-connection-that-uses-workload-identity-federation) before you begin a manual configuration.
 
 There are two options for authentication: use a managed identity or use a service principal. The advantage of the managed identity option is that you can use it if you don't have permissions to create service principals or if you're using a different Microsoft Entra tenant than your Azure DevOps user.
 
-## Workload identity by using managed identity authentication
+## Set a workload identity service connection to use managed identity authentication
 
 You might need to manually create a managed identity that uses federated credentials, and then grant the required permissions. You can also use the REST API for this process.
 
@@ -111,7 +111,7 @@ You might need to manually create a managed identity that uses federated credent
 
 1. In Azure DevOps, select **Verify and save**.
 
-## Workload identity by using service principal authentication
+## Set a workload identity service connection to use service principal authentication
 
 You might need to manually create a service principal that has federated credentials, and then grant the required permissions. You can also use the REST API for this process.
 
@@ -192,7 +192,7 @@ You might need to manually create a service principal that has federated credent
 
     :::image type="content" source="approvals/media/federated-credentials-devops.png" alt-text="Screenshot that shows DevOps credentials for federated authentication.":::
 
-1. In the Azure portal, return to your app registration federated credential.
+1. In the Azure portal, return to your app registration federated credentials.
 
 1. Paste the values for **Issuer** and **Subject identifier** that you copied from your Azure DevOps project into your federated credentials in the Azure portal.
 

docs/pipelines/release/approvals/media/new-app-registration.png

@@ -17,11 +17,19 @@ Get help debugging common issues with workload identity service connections. You
 
 ## Troubleshooting checklist
 
-Use the following checklist to troubleshoot issues with workload identity service connections.
+Use the following checklist to troubleshoot issues with workload identity service connections:
+
+- Review pipeline tasks to ensure that they support workload identity.
+- Verify that workload identity federation is active for the tenant.
+- Check the issuer URL and federation subject for accuracy.
+
+The following sections describe the issues and how to resolve them.
 
 ### Review pipeline tasks
 
-Not all pipelines tasks support workload identity. During the preview, no Azure Marketplace tasks support workload identity service connections. The following tasks don't currently support workload identity federation:
+Not all pipelines tasks support workload identity. During the preview, no Azure Marketplace tasks support workload identity service connections.
+
+The following tasks currently don't support workload identity federation:
 
 - AzureCloudPowerShellDeploymentV1
 - AzCopy (AzureFileCopyV1, AzureFileCopyV2, AzureFileCopyV3, AzureFileCopyV4, AzureFileCopyV5)
@@ -39,9 +47,9 @@ Verify that there are no Microsoft Entra policies in place that block federated
 
 ### Check the issuer URL for accuracy
 
-If you see a message that indicates `no matching federated identity record found`, either the issuer URL or the federation subject doesn't match. The correct issuer URL starts with `https://vstoken.dev.azure.com`.
+If you see a message that indicates **no matching federated identity record found**, either the issuer URL or the federation subject don't match. The correct issuer URL starts with `https://vstoken.dev.azure.com`.
 
-You can fix the issuer URL by editing and saving the service connection to update the issuer URL. If Azure DevOps didn't create the identity, the issuer must be updated manually. For Azure identities, the issuer URL automatically updates.  
+You can fix the issuer URL by editing and saving the service connection to update the issuer URL. If Azure DevOps didn't create the identity, the issuer URL must be updated manually. For Azure identities, the issuer URL automatically updates.  
 
 ## Common issues
 
@@ -57,23 +65,23 @@ You must either have permissions in Microsoft Entra ID to create app registratio
 
 You have two options to resolve the issue:
 
-- [Solution 1: Manually configure workload identity by using managed identity authentication](configure-workload-identity.md#workload-identity-by-using-managed-identity-authentication)
-- [Solution 2: Manually configure workload identity by using service principal authentication](configure-workload-identity.md#workload-identity-by-using-service-principal-authentication)
+- [Solution 1: Manually configure workload identity by using managed identity authentication](configure-workload-identity.md#set-a-workload-identity-service-connection-to-use-managed-identity-authentication)
+- [Solution 2: Manually configure workload identity by using service principal authentication](configure-workload-identity.md#set-a-workload-identity-service-connection-to-use-service-principal-authentication)
 
 ### I use a container resource that specifies an instance of Azure Container Registry
 
 [Container resources](/azure/devops/pipelines/process/resources?view#define-a-containers-resource) that are pulled from Azure Container Registry don't support a workload identity federation service connection that's specified in `azureSubscription`.
 
 ## Error messages
 
-The following table identifies common error messages and an issue that might generate each message:
+The following table identifies common error messages and issues that might generate them:
 
-| Message | Plausible issue |
+| Message | Possible issue |
 |---------|-----------------|
 | **cannot request token: Get `?audience=api://AzureADTokenExchange: unsupported protocol scheme`** | The task doesn't support workload identity federation. |
 | **Identity not found** | The task doesn't support workload identity federation. |
 | **Could not fetch access token for Azure** | The task doesn't support workload identity federation. |
-| **AADSTS700016: Application with identifier '****' wasn't found** | The identity that is used for the service connection no longer exists or it might have been removed independently from the service connection. Create a new service connection. |
+| **AADSTS700016: Application with identifier '****' wasn't found** | The identity that is used for the service connection no longer exists or it might have been removed from the service connection. In this scenario, create a new service connection. |
 | **AADSTS7000215:  Invalid client secret provided.** | You're using a service connection that has an expired secret. [Convert the service connection to workload identity federation](https://aka.ms/azdo-rm-workload-identity-conversion) and replace the expired secret with federated credentials. |
 | **AADSTS700024: Client assertion is not within its valid time range** | This error might occur in the following cases:<br />- You're using an AzureCLI task with `addSpnToEnvironment` set to `true` to consume the `idToken` environment variable. The `idToken` environment variable expires after 10 minutes.<br />- Some Azure data plane (non-Azure Resource Manager) operations require a separate bearer token to authenticate. You request a bearer token in the Azure CLI by using `az account get-access-token` or in Azure PowerShell by using Get-AzAccessToken. These tokens have a lifetime of one hour. Using the token after one hour results in an `AADSTS700024` error. Some tools and SDKs (for example, [Azure GO SDK](https://github.com/Azure/azure-sdk-for-go) and [Azure Python SDK](/azure/developer/python/sdk/azure-sdk-overview)) use the Azure CLI and `az account get-access-token` indirectly to obtain a bearer token. If you have tasks that (directly or indirectly) obtain a bearer token and run longer than one hour, use a service connection with a secret instead. |
 | **AADSTS70021: No matching federated identity record found for presented assertion. Assertion Issuer: `https://app.vstoken.visualstudio.com`.** | The issuer URL isn't correct. The correct issuer URL has the format `https://vstoken.dev.azure.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`. You can fix the issuer URL by editing and then saving a service connection. If Azure DevOps didn't create your identity, you must manually update the issuer. You can find the correct issuer in the edit dialog of the service connection or in the response (under authorization parameters) if you use the REST API. |