improve, update, create include for PAT reduction, recommend Microsoft entra usage

Author: chcomley

docs/boards/github/connect-on-premises-to-github.md

@@ -297,10 +297,10 @@ Consider the following resolutions:
 	Delete and recreate the connection to the GitHub repository. This recreated connection causes GitHub to prompt to reauthorize Azure Boards.   
 
 - **If the connection is using a PAT:**
-  - The PAT might be revoked or the required permission scopes changed and are insufficient.
+  - The PAT  was revoked or the required permission scopes changed and are insufficient.
   - The user perhaps lost administrative permissions on the GitHub repository.  
 
-	Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`.
+	Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. For more information, see [Best practices for using PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#best-practices-for-using-pats).
 
 <a id="update-wits"></a>
 

docs/boards/github/connect-to-github.md

@@ -124,7 +124,9 @@ To change the configuration or manage the Azure Boards app for GitHub, see  [Cha
 
 ## Add a GitHub connection using PAT   
 
-We recommend using your GitHub account credentials to connect to your GitHub repository. If you need to use a PAT, do the following steps.
+[!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)]
+
+We recommend using your GitHub account credentials to connect to your GitHub repository.
 
 > [!TIP]  
 > When you create your GitHub PAT, make sure that you include these scopes: `repo, read:user, user:email, admin:repo_hook`. 
@@ -343,10 +345,10 @@ To resolve this issue, consider the following items:
 	Delete and recreate the connection to the GitHub repository. This recreated connection causes GitHub to prompt to reauthorize Azure Boards.   
 
 - **If the connection is using a PAT:**
-  - The PAT might be revoked or the required permission scopes changed and are insufficient.
+  - The PAT was revoked or the required permission scopes changed and are insufficient.
   - The user might not have admin permissions on the GitHub repo.  
 
-	Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. 
+	Recreate the PAT and ensure the scope for the token includes the required permissions: `repo, read:user, user:email, admin:repo_hook`. For more information, see [Best practices for using PATs](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md#best-practices-for-using-pats).
 
 <a id="ghe-dataimport"></a>
 

docs/cli/log-in-via-pat.md

@@ -8,7 +8,7 @@ ms.manager: mijacobs
 ms.author: chcomley  
 author: chcomley
 monikerRange: 'azure-devops'
-ms.date: 08/10/2023
+ms.date: 01/08/2025
 ---
 
 # Sign in with a personal access token (PAT)
@@ -17,6 +17,8 @@ ms.date: 08/10/2023
 
 You can sign in using an Azure DevOps personal access token (PAT). To create a PAT, see [Use personal access tokens](../organizations/accounts/use-personal-access-tokens-to-authenticate.md#create-a-pat).
 
+[!INCLUDE [use-microsoft-entra-reduce-pats](../includes/use-microsoft-entra-reduce-pats.md)]
+
 To use a PAT with the Azure DevOps CLI, use one of these options:
 
 * Use `az devops login` and be [prompted for the PAT token](#user-prompted-to-use-az-devops-login).

docs/extend/develop/upload-tasks.md

@@ -31,6 +31,7 @@ To upload tasks to project collection, you need prerequisites:
     npm install -g tfx-cli
    ```
 - Permissions to update required project collection, PAT generated with scope **Environment (Read & Write)** to be able to upload tasks to the project collection.
+  [!INCLUDE [use-microsoft-entra-reduce-pats](../../includes/use-microsoft-entra-reduce-pats.md)]
 
 ## Tfx-cli sign in with personal access token
 

docs/includes/use-microsoft-entra-reduce-pats.md

@@ -0,0 +1,7 @@
+---
+ms.topic: include
+---
+
+> [!IMPORTANT]
+> We recommend using [Microsoft Entra tokens](../integrate/get-started/authentication/entra.md). For more information about our efforts to reduce PAT usage, see [our blog](https://devblogs.microsoft.com/devops/reducing-pat-usage-across-azure-devops/).
+> Review our [authentication guidance](../integrate/get-started/authentication/authentication-guidance.md) to choose the appropriate authentication mechanism for your needs.

docs/integrate/get-started/authentication/entra-oauth.md

@@ -1,49 +1,59 @@
 ---
-ms.topic: how-to
-title: Building a Microsoft Entra OAuth app for Azure DevOps
+title: Building Azure DevOps integrations with Microsoft Entra OAuth apps
 description: Use Microsoft Entra authentication to integrate with Azure DevOps Services.
 ms.assetid: 19285121-1805-4421-B7C4-63784C9A7CFA
 ms.subservice: azure-devops-security
+ms.topic: conceptual
 monikerRange: 'azure-devops'
 ms.author: chcomley
 author: chcomley
-ms.date: 10/28/2024
+ms.date: 01/08/2025
 ---
 
-# Building for Azure DevOps with Microsoft Entra OAuth Apps
+# Build Azure DevOps integrations with Microsoft Entra OAuth apps
 
-## Entra OAuth Tokens
-The Microsoft Identity platform offers many ways to authenticate users via [the OAuth 2.0 protocol](/entra/identity-platform/v2-protocols). In these docs, we use OAuth tokens to colloquially refer to [on-behalf-of user flows](/entra/identity-platform/v2-oauth2-on-behalf-of-flow), also known as [delegated flows](/entra/identity-platform/delegated-access-primer), for apps that request tokens to perform actions for their users. The rest of this guide offers helpful resources for these app developers. 
+[!INCLUDE [version-eq-azure-devops](../../../includes/version-eq-azure-devops.md)]
+
+This guide provides information and links to more information on building a Microsoft Entra OAuth app for Azure DevOps. Microsoft Entra ID offers robust identity and access management capabilities, which allow you to authenticate users and perform actions on their behalf using OAuth tokens. Use this information to apply Microsoft Entra OAuth tokens for various app flows, including delegated access and service principal-based access.
+
+## Use Microsoft Entra OAuth tokens
+
+The Microsoft identity platform offers many ways to authenticate users via [the OAuth 2.0 protocol](/entra/identity-platform/v2-protocols). In these docs, we use OAuth tokens to colloquially refer to [on-behalf-of user flows](/entra/identity-platform/v2-oauth2-on-behalf-of-flow), also known as [delegated flows](/entra/identity-platform/delegated-access-primer), for apps that request tokens to perform actions for their users. The rest of this guide offers helpful resources for these app developers. 
 
 Another common app flow we support is building [on-behalf-of app using service principals and managed identities](service-principal-managed-identity.md).
-Entra tokens can also be used for [ad-hoc requests with the Azure CLI](entra.md#acquire-user-tokens-in-azure-cli) or [git operations through the Git Credential Manager](entra.md#git-operations-with-git-credential-manager).
+Microsoft Entra tokens can also be used for [ad-hoc requests with the Azure CLI](entra.md#acquire-user-tokens-in-azure-cli) or [git operations through the Git Credential Manager](entra.md#git-operations-with-git-credential-manager).
 
 > [!IMPORTANT]
 > When creating a new OAuth 2.0 app, start here with Microsoft Entra OAuth apps, as [Azure DevOps OAuth apps](azure-devops-oauth.md) are planned for deprecation in 2026. [Learn more in our blog post](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/).
 
-## Helpful resources
+## Resources for developers
 
-### For developers
-* [Quickstart: Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app)
-* [Add permissions to access Microsoft Graph](/entra/identity-platform/quickstart-configure-app-access-web-apis#add-permissions-to-access-microsoft-graph): Useful to learn how to add delegated permissions from an Azure resource. Instead of Microsoft Graph, select `Azure DevOps` from the list of resources instead.
-* [Scopes and permissions in the Microsoft identity platform](/entra/identity-platform/scopes-oidc): Read up on the `.default` scope. See the scopes available for Azure DevOps in [our list of scopes](oauth.md#scopes).
-* [Requesting permissions through consent](/entra/identity-platform/consent-types-developer)
-* [Authentication libraries](/entra/identity-platform/reference-v2-libraries) and [code samples](/entra/identity-platform/sample-v2-code?tabs=apptype)
-* [Manage personal access tokens via API](../../../organizations/accounts/manage-personal-access-tokens-via-api.md): Using the PAT lifecycle management APIs requires Microsoft Entra tokens and our docs and the [associated sample app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) might be a helpful example for setting up a Microsoft Entra app to use Azure DevOps REST APIs.
-* [Support and help options for developers](/entra/identity-platform/developer-support-help-options)
+* [Register an application with the Microsoft identity platform](/entra/identity-platform/quickstart-register-app)
+* [Add permissions for access to Microsoft Graph](/entra/identity-platform/quickstart-configure-app-access-web-apis#add-permissions-to-access-microsoft-graph): Learn how to add delegated permissions from an Azure resource. Instead of Microsoft Graph, select `Azure DevOps` from the list of resources.
+* [Read about scopes and permissions in the Microsoft identity platform](/entra/identity-platform/scopes-oidc): Understand the `.default` scope. See the scopes available for Azure DevOps in [our list of scopes](oauth.md#scopes).
+* [Request permissions through consent](/entra/identity-platform/consent-types-developer)
+* [Use authentication libraries](/entra/identity-platform/reference-v2-libraries) and [code samples](/entra/identity-platform/sample-v2-code?tabs=apptype)
+* [Manage personal access tokens via API](../../../organizations/accounts/manage-personal-access-tokens-via-api.md): Use the PAT lifecycle management APIs with Microsoft Entra tokens. Our docs and the [associated sample app](https://github.com/microsoft/azure-devops-auth-samples/tree/master/PersonalAccessTokenAPIAppSample) provide examples for setting up a Microsoft Entra app to use Azure DevOps REST APIs.
+* [Explore support and help options for developers](/entra/identity-platform/developer-support-help-options)
 
-### For admins
-* [What is application management in Microsoft Entra ID?](/entra/identity/enterprise-apps/what-is-application-management)
-* [Quickstart: Add an enterprise application](/entra/identity/enterprise-apps/add-application-portal)
-* [Consent experience for applications in Microsoft Entra ID](/entra/identity-platform/application-consent-experience)
+### Resources for admins
+
+* [Understand application management in Microsoft Entra ID](/entra/identity/enterprise-apps/what-is-application-management)
+* [Add an enterprise application](/entra/identity/enterprise-apps/add-application-portal)
+* [Explore the consent experience for applications in Microsoft Entra ID](/entra/identity-platform/application-consent-experience)
+
+## Tips for building & migrating
 
-## Building & migrating tips
 > [!NOTE]
-> Microsoft Entra OAuth apps doesn't natively support MSA users for Azure DevOps REST APIs. If you are building an app that must cater to MSA users or supports both Microsoft Entra and MSA users, [Azure DevOps OAuth apps](azure-devops-oauth.md) remains your best option. We are currently working on native support for MSA users through Microsoft Entra OAuth.
+> Microsoft Entra OAuth apps don't natively support Microsoft account (MSA) users for Azure DevOps REST APIs. If you're building an app that must cater to MSA users or support both Microsoft Entra and MSA users, [Azure DevOps OAuth apps](azure-devops-oauth.md) remain your best option. We're currently working on native support for MSA users through Microsoft Entra OAuth.
 
-* **Good-to-know Azure DevOps IDs:**
+* **Important Azure DevOps IDs:**
   * Microsoft Entra resource identifier: `499b84ac-1321-427f-aa17-267ca6975798`
-  * Resource Uri: `https://app.vssps.visualstudio.com`
+  * Resource URI: `https://app.vssps.visualstudio.com`
   * Use the `.default` scope when requesting a token with all scopes that the app is permissioned for.
-* When migrating an existing app, you may be using Azure DevOps user identifiers that don't exist in Microsoft Entra. Use the [ReadIdentities API](/rest/api/azure/devops/ims/identities/read-identities) to resolve and match the different identities in use by each identity provider.
+* When you migrate an existing app, you might use Azure DevOps user identifiers that don't exist in Microsoft Entra. Use the [ReadIdentities API](/rest/api/azure/devops/ims/identities/read-identities) to resolve and match the different identities used by each identity provider.
+
+## Related articles
 
+- [Authenticate to Azure DevOps with Microsoft Entra](entra.md)
+- [Use service principals & managed identities in Azure DevOps](service-principal-managed-identity.md)