[APIM] Credential guidance in policies

Author: dlepow

articles/api-management/authentication-basic-policy.md

@@ -16,6 +16,8 @@ ms.author: danlep
 
 Use the `authentication-basic` policy to authenticate with a backend service using Basic authentication. This policy effectively sets the HTTP Authorization header to the value corresponding to the credentials provided in the policy.
 
+[!INCLUDE [api-management-credentials-caution](../../includes/api-management-credentials-caution.md)]
+
 [!INCLUDE [api-management-policy-generic-alert](../../includes/api-management-policy-generic-alert.md)]
 
 

articles/api-management/authentication-certificate-policy.md

@@ -14,7 +14,9 @@ ms.author: danlep
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
- Use the `authentication-certificate` policy to authenticate with a backend service using a client certificate. When the certificate is [installed into API Management](./api-management-howto-mutual-certificates.md) first, identify it first by its thumbprint or certificate ID (resource name). 
+ Use the `authentication-certificate` policy to authenticate with a backend service using a client certificate. When the certificate is [installed into API Management](./api-management-howto-mutual-certificates.md) first, identify it first by its thumbprint or certificate ID (resourcename). 
+
+[!INCLUDE [api-management-credentials-caution](../../includes/api-management-credentials-caution.md)]
 
 > [!CAUTION]
 > If the certificate references a certificate stored in Azure Key Vault, identify it using the certificate ID. When a key vault certificate is rotated, its thumbprint in API Management will change, and the policy will not resolve the new certificate if it is identified by thumbprint.
@@ -43,6 +45,12 @@ ms.author: danlep
 - [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API, operation
 - [**Gateways:**](api-management-gateways-overview.md) classic, v2, consumption, self-hosted, workspace
 
+### Usage notes
+
+- We recommend configuring [key vault certificates](api-management-howto-mutual-certificates.md) to manage certificates used to secure access to backend services.
+- If you configure certificates or passwords not stored in the built-in certificate store, we recommend using [named values](api-management-howto-properties.md) to provide credentials.
+
+
 ## Examples
 
 ### Client certificate identified by the certificate ID

articles/api-management/proxy-policy.md

@@ -16,6 +16,8 @@ ms.author: danlep
 
 The `proxy` policy allows you to route requests forwarded to backends via an HTTP proxy. Only HTTP (not HTTPS) is supported between the gateway and the proxy. Basic and NTLM authentication only. 
 
+[!INCLUDE [api-management-credentials-caution](../../includes/api-management-credentials-caution.md)]
+
 [!INCLUDE [api-management-policy-generic-alert](../../includes/api-management-policy-generic-alert.md)]
 
 
@@ -39,6 +41,11 @@ The `proxy` policy allows you to route requests forwarded to backends via an HTT
 - [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API, operation
 -  [**Gateways:**](api-management-gateways-overview.md) classic, v2, consumption, self-hosted, workspace
 
+### Usage notes
+
+- We recommend using [named values](api-management-howto-properties.md) to provide credentials, with secrets protected in a key vault.
+
+
 ## Example
 
 In this example, [named values](api-management-howto-properties.md) are used for the username and password to avoid storing sensitive information in the policy document.

includes/api-management-credentials-caution.md

@@ -0,0 +1,9 @@
+---
+author: vladvino
+ms.service: azure-api-management
+ms.topic: include
+ms.date: 09/11/2024
+ms.author: vlvinogr
+---
+> [!CAUTION]
+> Credentials may be exposed by this policy. Microsoft recommends that you use the most secure authentication methods supported by your backend, and protect sensitive information with [named values](api-management-howto-properties.md). Learn more about [risks](mitigate-owasp-api-threats.md#broken-user-authentication) of different authentication mechanisms.