Merge pull request #292921 from dlepow/apimropc

prmerger-automator[bot] · web-flow · commit 17b9b41419ad · 2025-02-05T17:45:27.000Z
[APIM][SFI] Basic auth caveats and guidance
diff --git a/articles/api-management/api-management-configuration-repository-git.md b/articles/api-management/api-management-configuration-repository-git.md
@@ -13,6 +13,9 @@ ms.author: danlep
 
 [!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]
 
+> [!IMPORTANT]
+> Starting March 15, 2025, Azure API Management will [retire](breaking-changes/git-configuration-retirement-march-2025.md) the ability to manage the configuration of your service instance using the built-in Git repository. If you plan to continue using a Git repository to manage the configuration of your service instance after the retirement date, update your configuration management to use a different solution such as APIOps and your own Git repository implementation.
+
 Each API Management service instance maintains a configuration database that contains information about the configuration and metadata for the service instance. Changes can be made to the service instance by changing a setting in the Azure portal, using Azure tools such as Azure PowerShell or the Azure CLI, or making a REST API call. In addition to these methods, you can manage your service instance configuration using Git, enabling scenarios such as:
 
 * **Configuration versioning** - Download and store different versions of your service configuration
@@ -42,7 +45,7 @@ This article describes how to enable and use Git to manage your service configur
 
  1. Navigate to your API Management instance in the [Azure portal](https://portal.azure.com/).
 
- 1. In the left menu, under **Deployment and infrastructure**, select **Repository**.
+ 1. In the left menu, under **Deployment + infrastructure**, select **Repository**.
  
 :::image type="content" source="media/api-management-configuration-repository-git/api-management-enable-git.png" alt-text="Screenshot showing how to access Git configuration for API Management.":::
 
@@ -67,7 +70,10 @@ For information on saving the service configuration using the REST API, see [Ten
 
 ## Get access credentials
 
-To clone a repository, in addition to the URL to your repository, your need a username and a password. 
+To clone a repository, in addition to the URL to your repository, you need a username and a password. 
+
+> [!CAUTION]
+> Using username and password credentials with a Git repository can pose security risks. Store your password securely and rotate it regularly. Don't store your credentials in plain text in code or configuration files. 
 
 1. On the **Repository** page, select **Access credentials** near the top of the page.
 
@@ -91,19 +97,19 @@ git clone https://{name}.scm.azure-api.net/
 
 Provide the username and password when prompted.
 
-If you receive any errors, try modifying your `git clone` command to include the user name and password, as shown in the following example.
+If you receive any errors, try modifying your `git clone` command to include the username, as shown in the following example. Provide the password when prompted.
 
 ```
-git clone https://username:password@{name}.scm.azure-api.net/
+git clone https://username@{name}.scm.azure-api.net/
 ```
 
-If this provides an error, try URL encoding the password portion of the command. One quick way to do this is to open Visual Studio, and issue the following command in the **Immediate Window**. To open the **Immediate Window**, open any solution or project in Visual Studio (or create a new empty console application), and choose **Windows**, **Immediate** from the **Debug** menu.
+If this provides an error, try URL encoding the password and pass it in the command. One quick way to do this is to open Visual Studio, and issue the following command in the **Immediate Window**. To open the **Immediate Window**, open any solution or project in Visual Studio (or create a new empty console application), and choose **Windows**, **Immediate** from the **Debug** menu.
 
 ```
 ?System.Net.WebUtility.UrlEncode("password from the Azure portal")
 ```
 
-Use the encoded password along with your user name and repository location to construct the git command.
+Use the encoded password along with your username and repository location to construct the git command.
 
 ```
 git clone https://username:url encoded password@{name}.scm.azure-api.net/
@@ -205,7 +211,7 @@ These files can be created, deleted, edited, and managed on your local file syst
 > * [Subscriptions](/rest/api/apimanagement/current-ga/subscription)
 > * Named values
 > * Developer portal entities other than styles and templates
-> * Policy Fragments
+> * Policy fragments
 >
 
 ### Root api-management folder
@@ -305,7 +311,8 @@ The `templates` folder contains configuration for the [email templates](api-mana
 * `<template name>\configuration.json` - Configuration for the email template.
 * `<template name>\body.html` - Body of the email template.
 
-## Next steps
+## Related content
+
 For information on other ways to manage your service instance, see:
 
 * [Azure PowerShell cmdlet reference](/powershell/module/az.apimanagement)
diff --git a/articles/api-management/authentication-authorization-overview.md b/articles/api-management/authentication-authorization-overview.md
@@ -149,7 +149,7 @@ While authorization is preferred, and OAuth 2.0 has become the dominant method o
 |---------|---------|---------|
 |[Managed identity authentication](authentication-managed-identity-policy.md)     |   Authenticate to backend API with a system-assigned or user-assigned [managed identity](api-management-howto-use-managed-service-identity.md).      |   Recommended for scoped access to a protected backend resource by obtaining a token from Microsoft Entra ID.    |
 |[Certificate authentication](authentication-certificate-policy.md)     |    Authenticate to backend API using a client certificate.      |  Certificate may be stored in key vault.      |
-|[Basic authentication](authentication-basic-policy.md)     |   Authenticate to backend API with username and password that are passed through an Authorization header.      | Discouraged if better options are available.         |
+|[Basic authentication](authentication-basic-policy.md)     |   Authenticate to backend API with username and password that are passed through an Authorization header.      | Discouraged if more secure authentication options are available (for example, managed identity, certificates, credential manager).  If chosen, use [named values](api-management-howto-properties.md) to provide credentials, with secrets protected in a key vault.
 
 ## Next steps
 * Learn more about [authentication and authorization](../active-directory/develop/authentication-vs-authorization.md) in the Microsoft identity platform.
diff --git a/articles/api-management/breaking-changes/git-configuration-retirement-march-2025.md b/articles/api-management/breaking-changes/git-configuration-retirement-march-2025.md
@@ -13,7 +13,7 @@ ms.author: danlep
 
 [!INCLUDE [api-management-availability-premium-dev-standard-basic](../../../includes/api-management-availability-premium-dev-standard-basic.md)]
 
-Effective 15 March 2025, Azure API Management will retire the ability to manage the configuration of your service instance using the built-in Git repository. If you plan to continue using a Git repository to manage the configuration of your service instance after the retirement date, you must update your configuration management to use a different solution such as APIOps and your own Git repository implementation.
+Starting 15 March 2025, Azure API Management will retire the ability to manage the configuration of your service instance using the built-in Git repository. If you plan to continue using a Git repository to manage the configuration of your service instance after the retirement date, you must update your configuration management to use a different solution such as APIOps and your own Git repository implementation.
 
 ## Is my service affected by this?
 
diff --git a/articles/api-management/developer-portal-basic-authentication.md b/articles/api-management/developer-portal-basic-authentication.md
@@ -5,8 +5,8 @@ description: Learn how to set up user accounts with username and password authen
 
 author: dlepow
 ms.service: azure-api-management
-ms.topic: article
-ms.date: 08/30/2022
+ms.topic: how-to
+ms.date: 01/10/2025
 ms.author: danlep
 ---
 
@@ -18,6 +18,8 @@ In the developer portal for Azure API Management, the default authentication met
 
 For an overview of options to secure the developer portal, see [Secure access to the API Management developer portal](secure-developer-portal-access.md). 
 
+> [!CAUTION]
+> While you can use basic authentication to secure users' access to the developer portal, we recommend configuring a more secure authentication method such as [Microsoft Entra ID](api-management-howto-aad.md) or [Azure AD B2C](api-management-howto-aad-b2c.md), if available. 
 
 ## Prerequisites
 
diff --git a/articles/api-management/developer-portal-wordpress-plugin.md b/articles/api-management/developer-portal-wordpress-plugin.md
@@ -6,7 +6,7 @@ author: dlepow
 ms.service: azure-api-management
 ms.custom: 
 ms.topic: how-to
-ms.date: 07/18/2024
+ms.date: 01/10/2025
 ms.author: danlep
 ---
 
@@ -35,9 +35,12 @@ For this scenario, you create a managed WordPress site hosted on Azure App Servi
 
 1. In the Azure portal, navigate to [https://portal.azure.com/#create/WordPress.WordPress](https://portal.azure.com/#create/WordPress.WordPress). 
 
-1. On the **Create WordPress on App Service** page, in the **Basics** tab, enter your project details. 
+1. On the **Create WordPress on App Service** page, in the **Basics** tab, enter your project details, Web App details, and WordPress setup settings. 
 
-    Record the WordPress admin username and password in a safe place. These credentials are required to sign into the WordPress admin site and install the plugin in a later step.
+    Store the WordPress admin username and password in a safe place. These credentials are required to sign into the WordPress admin site and install the plugin in a later step.
+
+    > [!CAUTION]
+    > Avoid using the default WordPress `admin` username, and create a strong password. [Learn more about WordPress password best practices](https://wordpress.org/documentation/article/password-best-practices/)
 
 1. On the **Add-ins** tab:
 
diff --git a/articles/api-management/secure-developer-portal-access.md b/articles/api-management/secure-developer-portal-access.md
@@ -5,7 +5,7 @@ description: Learn about options to secure access to the API Management develope
 author: dlepow
 
 ms.service: azure-api-management
-ms.topic: conceptual
+ms.topic: concept-article
 ms.date: 09/12/2023
 ms.author: danlep
 ---
@@ -36,6 +36,9 @@ API Management has a fully customizable, standalone, managed [developer portal](
 
 * **Basic authentication** - A default option is to use the built-in developer portal [username and password](developer-portal-basic-authentication.md) provider, which allows developers to register directly in API Management and sign in using API Management user accounts. User sign up through this option is protected by a CAPTCHA service. 
 
+    > [!CAUTION]
+    > While you can use basic authentication to secure users' access to the developer portal, we recommend configuring a more secure authentication method such as [Microsoft Entra ID](api-management-howto-aad.md) or [Azure AD B2C](api-management-howto-aad-b2c.md).
+
 
 ## Developer portal test console
 In addition to providing configuration for developer users to sign up for access and sign in, the developer portal includes a test console where the developers can send test requests through API Management to the backend APIs. This test facility also exists for contributing users of API Management who manage the service using the Azure portal. 
@@ -111,6 +114,6 @@ Key configurations:
 Go a step further by delegating [user registration or product subscription](api-management-howto-setup-delegation.md) and extend the process with your own logic. 
 
 
-## Next steps
+## Related content
 * Learn more about [authentication and authorization](../active-directory/develop/authentication-vs-authorization.md) in the Microsoft identity platform.
 * Learn how to [mitigate OWASP API security threats](mitigate-owasp-api-threats.md) using API Management.
diff --git a/articles/api-management/sql-data-source-policy.md b/articles/api-management/sql-data-source-policy.md
@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: azure-api-management
 ms.topic: article
-ms.date: 07/23/2024
+ms.date: 01/10/2025
 ms.author: danlep
 ---
 
@@ -77,7 +77,7 @@ The `sql-data-source` resolver policy configures a Transact-SQL (T-SQL) request
 
 | Attribute                                      | Description                                                                                 | Required                                           | Default |
 | ----------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------- |
-| use-managed-identity | Boolean. Specifies whether to use the API Management instance's system-assigned [managed identity](api-management-howto-use-managed-service-identity.md) for connection to the Azure SQL database in place of a username and password in the connection string. Policy expressions are allowed. <br/><br/>The identity must be [configured](#configure-managed-identity-integration-with-azure-sql) to access the Azure SQL database.  | No  | `false`   |
+| use-managed-identity | Boolean. Specifies whether to use the API Management instance's system-assigned [managed identity](api-management-howto-use-managed-service-identity.md) for connection to the Azure SQL database in place of a username and password in the connection string. Policy expressions are allowed. <br/><br/>The identity must be [configured](#configure-managed-identity-integration-with-azure-sql) to access the Azure SQL database. Microsoft recommends this option as the most secure authentication method.  | No  | `false`   |
 
 ### request attribute
 
@@ -128,7 +128,7 @@ The `sql-data-source` resolver policy configures a Transact-SQL (T-SQL) request
 
 ## Configure managed identity integration with Azure SQL
 
-You can configure an API Management system-assigned managed identity for access to Azure SQL instead of configuring SQL authentication with username and password. For background, see [Configure and manage Microsoft Entra authentication with Azure SQL](/azure/azure-sql/database/authentication-aad-configure).
+We strongly recommend configuring an API Management system-assigned managed identity for access to Azure SQL instead of configuring SQL authentication with username and password. For background, see [Configure and manage Microsoft Entra authentication with Azure SQL](/azure/azure-sql/database/authentication-aad-configure).
 
 ### Prerequisites
 
@@ -149,7 +149,7 @@ Enable Microsoft Entra authentication to SQL Database by assigning a Microsoft E
 
 1. In the portal, go to your Azure SQL database resource.
 1. Select **Query editor (preview)**.
-1. Login using Active Directory authentication.
+1. Login using Microsoft Entra authentication.
 1. Execute the following SQL script. Replace `<identity-name>` with the name of your API Management instance.
 
     ```sql
