draft complete

Author: dlepow

articles/api-management/TOC.yml

@@ -85,6 +85,13 @@
               href: /security/benchmark/azure/baselines/api-management-security-baseline?toc=/azure/api-management/&bc=/azure/api-management/breadcrumb/toc.json
             - name: Authentication and authorization
               href: authentication-authorization-overview.md
+            - name: API security
+              items:
+              - name: Defender for APIs (preview)
+                href: protect-with-defender-for-apis.md              
+              - name: Mitigate OWASP API threats
+                href: mitigate-owasp-api-threats.md
+                displayName: OWASP top 10, vulnerability, vulnerabilities
       - name: Observability
         href: observability.md
         displayName: monitoring
@@ -286,11 +293,6 @@
               href: api-management-howto-manage-protocols-ciphers.md
             - name: Defend against DDoS attacks
               href: protect-with-ddos-protection.md
-            - name: Mitigate OWASP API threats
-              href: mitigate-owasp-api-threats.md
-              displayName: OWASP top 10, vulnerability, vulnerabilities
-            - name: Protect APIs with Defender for APIs
-              href: protect-with-defender-for-apis.md
           - name: Manage API authorizations
             items:
             - name: Authorizations overview

articles/api-management/api-management-gateways-overview.md

@@ -76,6 +76,7 @@ The following table compares features available in the managed gateway versus th
 | [TLS settings](api-management-howto-manage-protocols-ciphers.md) |  ✔️ | ✔️ | ✔️ |
 | **HTTP/2** (Client-to-gateway) |  ❌ | ❌ | ✔️ |
 | **HTTP/2** (Gateway-to-backend) |  ❌ | ❌ | ✔️ |
+| API threat detection with [Defender for APIs](protect-with-defender-for-apis.md) | ✔️ |  ❌ | ❌ | 
 
 <sup>1</sup> Depends on how the gateway is deployed, but is the responsibility of the customer.<br/>
 <sup>2</sup> Connectivity to the self-hosted gateway v2 [configuration endpoint](self-hosted-gateway-overview.md#fqdn-dependencies) requires DNS resolution of the default endpoint hostname; custom domain name is currently not supported.<br/>

articles/api-management/media/protect-with-defender-for-apis/defender-for-apis-recommendations.png

@@ -4,7 +4,7 @@ description: Learn how to protect against common API-based vulnerabilities, as i
 author: mikebudzynski
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 05/31/2022
+ms.date: 04/13/2023
 ms.author: mibudz
 ---
 
@@ -14,6 +14,9 @@ The Open Web Application Security Project ([OWASP](https://owasp.org/about/)) Fo
 
 The OWASP [API Security Project](https://owasp.org/www-project-api-security/) focuses on strategies and solutions to understand and mitigate the unique *vulnerabilities and security risks of APIs*. In this article, we'll discuss recommendations to use Azure API Management to mitigate the top 10 API threats identified by OWASP.
 
+> [!NOTE]
+> In addition to following the recommendations in this article, you can enable [Defender for APIs](https://aka.ms/apiSecurityOverview) (preview), a capability of Microsoft Defender for Cloud, for API security insights, recommendations, and threat detection. [Learn more about using Defender for APIs with API Management](protect-with-defender-for-apis.md)
+
 ## Broken object level authorization 
 
 API objects that aren't protected with the appropriate level of authorization may be vulnerable to data leaks and unauthorized data manipulation through weak object access identifiers. For example, an attacker could exploit an integer object identifier, which can be iterated. 
@@ -308,7 +311,10 @@ More information about this threat: [API10:2019  Insufficient logging and monito
 
 ## Next steps
 
+Learn more about:
+
 * [Authentication and authorization in API Management](authentication-authorization-overview.md)
 * [Security baseline for API Management](/security/benchmark/azure/baselines/api-management-security-baseline)
 * [Security controls by Azure policy](security-controls-policy.md)
 * [Landing zone accelerator for API Management](/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator)
+* [Defender for APIs](https://aka.ms/apiSecurityOverview)

articles/api-management/media/protect-with-defender-for-apis/enable-defender-for-apis.png

@@ -1,100 +1,108 @@
 ---
-title: Protect APS in API Management with Defender for APIs 
-description: Learn how to use Azure Defender for APIs to identify and protect API threat in your Azure API Management instance.
+title: Protect APIs in API Management with Defender for APIs 
+description: Learn how to enable enhanced API security features in Azure API Management by using Microsoft Defender for Cloud.
 services: api-management
 author: dlepow
 
 ms.service: api-management
 ms.topic: how-to
-ms.date: 04/06/2023
+ms.date: 04/14/2023
 ms.author: danlep
 ---
-# Use Azure Defender for APIs to protect against API threats
+# Enable enhanced API security features using Microsoft Defender for Cloud 
 <!-- Update links to D4APIs docs when available -->
-This article shows how to identify and protect against API threats exposed in your API Management instance by using Azure [Defender for APIs](https://aka.ms/apiSecurityOverview) (preview). Background about this feature and considerations for use are also provided.
 
-[!INCLUDE [api-management-availability-premium-dev-standard-basic](../../includes/api-management-availability-premium-dev-standard-basic.md)]
+Defender for APIs (preview), a new capability of Microsoft Defender for Cloud, offers full lifecycle protection, detection, and response coverage for APIs that are managed in Azure API Management. The service empowers security practitioners to gain visibility into their business-critical APIs, understand their security posture, prioritize vulnerability fixes, and detect active runtime threats within minutes.  
 
-## Preview limitations
+This article shows how to use the Azure portal to enable Defender for APIs from your API Management instance and view a summary of security recommendations and alerts for onboarded APIs. You can also enable Defender for APIs directly in the Microsoft Defender for Cloud console, where more API security insights and inventory experiences are available. 
 
-* Currently, Defender for APIs only discovers and analyzes REST APIs. 
-* This feature isn't supported in the API Management [self-hosted gateway](self-hosted-gateway-overview.md).
-* This feature isn't supported for APIs in API Management [workspaces](workspaces-overview.md).
-* In [multi-region](api-management-howto-deploy-multi-region.md) deployments of API Management, some ML-based detections, data classification capabilities, and security insights that are available in the primary region currently don't work in secondary regions. In secondary regions, data residency requirements are still met.
+To learn more, see:
 
-## Benefits
+* [Microsoft Defender for APIs – Benefits and features](https://aka.ms/apiSecurityOverview) 
+* [Microsoft Defender for Cloud](/azure/defender-for-cloud/defender-for-cloud-introduction)
 
-Defender for APIs, a part of Microsoft [Defender for Cloud](/azure/defender-for-cloud/defender-for-cloud-introduction), offers full lifecycle protection, detection, and response coverage for APIs. The service empowers security practitioners to gain visibility into their business-critical APIs, understand their security posture, prioritize vulnerability fixes, and detect active runtime threats within minutes. Currently, the service supports APIs managed in Azure API Management. 
+[!INCLUDE [api-management-availability-premium-dev-standard-basic](../../includes/api-management-availability-premium-dev-standard-basic.md)]
 
-Defender for APIs has the following key capabilities:
+## Preview limitations
 
-* **API inventory** - Discover and catalog all APIs managed in API Management.
+* Currently, Defender for APIs discovers and analyzes REST APIs only. 
+* Defender for APIs currently doesn't onboard APIs that are exposed using the API Management [self-hosted gateway](self-hosted-gateway-overview.md) or managed using API Management [workspaces](workspaces-overview.md).
+* Some ML-based detections and security insights (data classification, authentication check, unused and external APIs) for instances with [multi-region](api-management-howto-deploy-multi-region.md) deployments aren't supported in secondary regions. In such cases, data residency requirements are still met.  
 
-* **API security insights** - Identify external, unused, and unauthenticated APIs, and attack paths, and provide hardening recommendations.
+## Prerequisites
 
-* **API data classification** -  Classify APIs that handle sensitive data for risk prioritization.
+* At least one API Management instance in an Azure subscription. Defender for APIs is enabled at the level of a subscription. 
+* One or more supported APIs must be imported to the API Management instance.
+* Permissions to [enable the Defender for APIs plan](azure/defender-for-cloud/permissions).
+* Owner or Contributor permissions on the API Management instance. 
 
-* **OWASP API Top 10 threat detection** - Detect exploits using ML-based and rule-based detections, monitor API traffic for compromise.
+## Onboard to Defender for APIs
 
-* **Threat response** - Integrate or export alerts into SIEM systems for investigation and threat response workflows.
+Onboarding APIs to Defender for APIs is a two-step process: enabling the Defender for APIs plan, and onboarding unprotected APIs in your API Management instances.   
 
-* **Integration with [cloud security graph](/azure/defender-for-cloud/concept-attack-path)** - Query API inventory, insights, and recommendations for prioritized remediation and attack path analysis.
+> [!CAUTION]
+> Onboarding APIs to Defender for APIs may increase compute, memory, and network utilization of your API Management instance. Do not onboard all APIs at one time if your API Management instance is running at high utilization. Use caution by gradually onboarding APIs, while monitoring the utilization of your instance (for example, using [the capacity metric](api-management-capacity.md)) and scaling out as needed. 
 
-## Prerequisites
+### Enable the Defender for APIs plan for a subscription
 
-* One or more API Management instances in an Azure subscription. Defender for APIs is enabled at the level of an Azure subscription. 
-* At least one REST API must be imported to an instance. 
+1. Sign in to the [portal](https://portal.azure.com), and go to your API Management instance.
 
-## Onboard to Defender for APIs
-Onboarding APIs from Azure API Management to Defender for APIs is a two-step process:   
+1. In the left menu, select **Microsoft Defender for Cloud (preview)**.
+
+1. Select **Enable Defender on the subscription**.
 
-1. First, enable the Defender for APIs plan for a subscription 
+    :::image type="content" source="media/protect-with-defender-for-apis/enable-defender-for-apis.png" alt-text="Screenshot showing how to enable Defender for APIs in the portal.":::
 
-    1. Sign in to the [portal](https://portal.azure.com), and go to **Defender for Cloud**.
-    1. In the left menu, select **Environment settings**
-    1. In **Defender plans**, enable **APIs**.
+1. On the **Defender plan** page, select **On** for the **APIs** plan.
 
-    After the Defender for APIs plan is turned on, APIs in the API Management instances that are available for onboarding are listed on the **Recommendations** page.
-1. Next, onboard unprotected APIs to Defender for APIs 
+1. Select **Save**.
 
-    1. In the portal, go to **Defender for Cloud** > **Recommendations**.
-    1. Search for **Defender for APIs**.
-    1. Under **Enable enhanced security features**, select **Azure API Management APIs should be onboarded to Defender for APIs**.
-    1. Select an API that you wish to onboard to Defender for APIs from the list of **Unhealthy** resources. 
-    1. Select **Fix**. 
 
-For details, see  [Quickstart: Enabling enhanced API security features from Microsoft Defender for Cloud](https://aka.ms/apiSecurityApimOnboarding).  
+### Onboard unprotected APIs to Defender for APIs 
 
-> [!WARNING]
-> Onboarding APIs to Defender for APIs will increase compute and memory utilization by your API Management instance and may affect gateway performance. Onboard APIs gradually, monitor the gateway performance, and scale out the API Management instance as needed. For more information, see [Performance considerations](#performance-considerations).
+1. In the portal, go back to your API Management instance.
+1. In the left menu, select **Microsoft Defender for Cloud (preview)**.
+1. Under **Recommendations**, select **Azure API Management APIs should be onboarded to Defender for APIs**.
+    :::image type="content" source="media/protect-with-defender-for-apis/defender-for-apis-recommendations.png" alt-text="Screenshot of Defender for APIs recommendations in the portal.":::
+1. On the next screen, review details about the recommendation:
+    * Severity  
+    * Refresh interval for security findings 
+    * Description and remediation steps
+    * Affected resources, classified as **Healthy** (onboarded to Defender for APIs), **Unhealthy** (not onboarded), or **Not applicable**, along with associated metadata from API Management
+    
+   > [!NOTE]
+   > Affected resources include all API collections (that is, APIs and their associated operations) from all API Management instances under the subscription. 
+
+1. From the list of **Unhealthy** resources, select the API(s) that you wish to onboard to Defender for APIs.
+1. Select **Fix**, and then select **Fix resources**.
+    :::image type="content" source="media/protect-with-defender-for-apis/fix-unhealthy-resources.png" alt-text="Screenshot of onboarding unhealthy APIs in the portal.":::
+1.  Track the status of onboarded resources under **Notifications**. 
 
 > [!NOTE]
-> Defender for APIs will take 30 minutes to generate its first security insights after onboarding an API. Thereafter, security insights are refreshed every 30 minutes. 
+> Defender for APIs takes 30 minutes to generate its first security insights after onboarding an API. Thereafter, security insights are refreshed every 30 minutes. 
 > 
 
-## View security insights
-
-After APIs are onboarded and security insights are generated, view security insights in the portal.
+## View security coverage
 
-1. In the portal, go to **Defender for Cloud** > **Workload protections**.
-1. Select **API security**.
+After you onboard the APIs from API Management, Defender for APIs receives API traffic that will be used to build security insights and monitor for threats. Defender for APIs generates security recommendations for risky and vulnerable APIs.  
 
-Review security insights for an onboarded API (called an *API collection* in Defender for APIs) or operation (*API endpoint*).
+You can view a summary of all security recommendations and alerts for onboarded APIs by selecting **Microsoft Defender for Cloud (preview)** in the menu for your API Management instance:
 
-## Performance considerations
+1. In the portal, go to your API Management instance and select **Microsoft Defender for Cloud (preview**) from the left menu.
+1. Review **Recommendations** and **Security insights and alerts**.
 
-Onboarding APIs to Defender for APIs can affect the performance of the API Management instance in which they're managed. Onboard APIs gradually and monitor your API Management instances for performance changes. Performance impacts by Defender for APIs can be mitigated by scaling or upgrading an API Management instance.     
+    :::image type="content" source="media/protect-with-defender-for-apis/view-security-insights.png" alt-text="Screenshot of API security insights in the portal.":::
 
-* **Reduced gateway performance** - The performance of your API Management gateway (throughput of API requests) may be reduced when many APIs are onboarded from an instance.
-* **Possible outage** - If you onboard multiple APIs from an API Management instance at one time, it is possible to cause a gateway outage. 
-* **Monitor capacity metric** - Monitor the [capacity](api-management-capacity.md) metric to evaluate changes in the load on an API Management instance caused by onboarding to Defender for APIs. Look at long-term trends or averages when making decisions to [scale](api-management-capacity.md#use-capacity-for-scaling-decisions) an API Management instance
+For the security alerts received, Defender for APIs suggests necessary steps to perform the required analysis and validate the potential exploit or anomaly associated with the APIs. Follow the steps in the security alert to fix and return the APIs to healthy status. 
 
+To learn more about the benefits of Defender for APIs, including additional API inventory experiences within Defender for Cloud, see [Microsoft Defender for APIs – Benefits and features](https://aka.ms/apiSecurityOverview). 
 
 ## Next steps
 
 * Learn more about Defender for APIs:
-    * [Benefits and features](https://aka.ms/apiSecurityOverview)
+    * [Benefits and features](https://aka.ms/apiSecurityOverview) 
     * [API security alerts](https://aka.ms/apiSecurityAlerts)
     * [API security threats](https://aka.ms/apiSecurityRecommendations)
     * [API security troubleshooting guide](https://aka.ms/apiSecurityTroubleshooting)
+    * [Pricing](https://azure.microsoft.com/pricing/details/defender-for-cloud/)
 * Learn how to [upgrade and scale](upgrade-and-scale.md) an API Management instance.