Merge pull request #267191 from AlizaBernstein/WI-215040-api-enablement-plan

WI-215040 api entitlement plan

Author: ttorble

articles/defender-for-cloud/defender-for-apis-deploy.md

@@ -1,11 +1,11 @@
 ---
 title: Protect your APIs with Defender for APIs
-description: Learn about deploying the Defender for APIs plan in Defender for Cloud
+description: Learn about deploying the Defender for APIs plan in Defender for Cloud.
 author: dcurwin
 ms.author: dacurwin
 ms.service: defender-for-cloud
 ms.topic: conceptual
-ms.date: 12/03/2023
+ms.date: 03/03/2024
 ---
 
 # Protect your APIs with Defender for APIs
@@ -14,6 +14,9 @@ Defender for APIs in Microsoft Defender for Cloud offers full lifecycle protecti
 
 Defender for APIs helps you to gain visibility into business-critical APIs. You can investigate and improve your API security posture, prioritize vulnerability fixes, and quickly detect active real-time threats.
 
+This article describes how to enable and onboard the Defender for APIs plan in the Defender for Cloud portal. Alternately, you can [enable Defender for APIs within an API Management instance](../api-management/protect-with-defender-for-apis.md) in the Azure portal.
+
+Learn more about the [Microsoft Defender for APIs](defender-for-apis-introduction.md) plan in the Microsoft Defender for Cloud.
 Learn more about [Defender for APIs](defender-for-apis-introduction.md).
 
 ## Prerequisites
@@ -28,20 +31,62 @@ Learn more about [Defender for APIs](defender-for-apis-introduction.md).
 
 - Ensure that APIs you want to secure are published in [Azure API management](/azure/api-management/api-management-key-concepts). Follow [these instructions](/azure/api-management/get-started-create-service-instance) to set up Azure API Management.
 
-> [!NOTE]
-> This article describes how to enable and onboard the Defender for APIs plan in the Defender for Cloud portal. Alternately, you can [enable Defender for APIs within an API Management instance](../api-management/protect-with-defender-for-apis.md) in the Azure portal.
+- You must select a plan that grants entitlement appropriate for the API traffic volume in your subscription to receive the most optimal pricing. By default, subscriptions are opted into "Plan 1", which can lead to unexpected overages if your subscription has API traffic higher than the [one million API calls entitlement](https://ms.portal.azure.com/#view/Microsoft_Azure_Security/SecurityMenuBlade/~/18).
 
 ## Enable the Defender for APIs plan
 
+When selecting a plan, consider these points:
+
+- Defender for APIs protects only those APIs that are onboarded to Defender for APIs. This means you can activate the plan at the subscription level, and complete the second step of onboarding by fixing the onboarding recommendation. For more information about onboarding, see the [onboarding guide](defender-for-apis-deploy.md#enable-the-defender-for-apis-plan).
+- Defender for APIs has five pricing plans, each with a different entitlement limit and monthly fee. The billing is done at the subscription level.  
+- Billing is applied to the entire subscription based on the total amount of API traffic monitored over the month for the subscription. 
+- The API traffic counted towards the billing is reset to 0 at the start of each month (every billing cycle). 
+- The overages are computed on API traffic exceeding the entitlement limit per plan selection during the month for your entire subscription.
+
+To select the best plan for your subscription from the Microsoft Defender for Cloud [pricing page](https://azure.microsoft.com/pricing/details/defender-for-cloud/), follow these steps and choose the plan that matches your subscriptions’ API traffic requirements:  
+
+> [!NOTE]
+> The Defender for Cloud pricing page will be updated with the pricing information and pricing calculators by end of March 2024. In the meantime, use this document to select the correct Defender for APIs entitlements and enable the plan.
+
 1. Sign into the [portal](https://portal.azure.com/), and in Defender for Cloud, select **Environment settings**.
 
 1. Select the subscription that contains the managed APIs that you want to protect.
 
-1. In the **APIs** plan, select **On**. Then select **Save**:
+    :::image type="content" source="media/defender-for-apis-entitlement-plans/select-environment-settings.png" alt-text="Screenshot that shows where to select Environment settings." lightbox="media/defender-for-apis-entitlement-plans/select-environment-settings.png":::
+   
+1. Select **Details** under the pricing column for the APIs plan.     
+
+    :::image type="content" source="media/defender-for-apis-entitlement-plans/select-api-details.png" alt-text="Screenshot that shows where to select API details." lightbox="media/defender-for-apis-entitlement-plans/select-api-details.png":::
+ 
+1. Select the plan that is suitable for your subscription. 
+1. Select **Save**. 
+
+## Selecting the optimal plan based on historical Azure API Management API traffic usage
+
+You must select a plan that grants entitlement appropriate for the API traffic volume in your subscription to receive the most optimal pricing. By default, subscriptions are opted into **Plan 1**, which can lead to unexpected overages if your subscription has API traffic higher than the [one million API calls entitlement](https://ms.portal.azure.com/#view/Microsoft_Azure_Security/SecurityMenuBlade/~/18). 
+
+**To estimate the monthly API traffic in Azure API Management:** 
+
+1. Navigate to the Azure API Management portal and select **Metrics** under the Monitoring menu bar item.  
+
+    :::image type="content" source="media/defender-for-apis-entitlement-plans/select-metrics.png" alt-text="Screenshot that shows where to select metrics." lightbox="media/defender-for-apis-entitlement-plans/select-metrics.png":::
+
+1. Select the time range as **Last 30 days**.
+1. Select and set the following parameters:
+
+    1. Scope: **Azure API Management Service Name** 
+    1. Metric Namespace: **API Management service standard metrics**
+    1. Metric = **Requests**
+    1. Aggregation = **Sum**
+    
+1. After setting the above parameters, the query will automatically run, and the total number of requests for the past 30 days appears at the bottom of the screen. In the screenshot example, the query results in 414 total number of requests.
+
+    :::image type="content" source="media/defender-for-apis-entitlement-plans/metrics-results.png" alt-text="Screenshot that shows metrics results." lightbox="media/defender-for-apis-entitlement-plans/metrics-results.png":::
 
-    :::image type="content" source="media/defender-for-apis-deploy/enable-plan.png" alt-text="Screenshot that shows how to turn on the Defender for APIs plan in the portal." lightbox="media/defender-for-apis-deploy/enable-plan.png":::
+    > [!NOTE]
+    > These instructions are for calculating the usage per Azure API management service. To calculate the estimated traffic usage for *all* API management services within the Azure subscription, change the **Scope** parameter to each Azure API management service within the Azure subscription, re-run the query, and sum the query results. 
 
-1. Select **Save**.
+If you don't have access to run the metrics query, reach out to your internal Azure API Management administrator or your Microsoft account manager.  
 
 > [!NOTE]
 > After enabling Defender for APIs, onboarded APIs take up to 50 minutes to appear in the **Recommendations** tab. Security insights are available in the **Workload protections** > **API security** dashboard within 40 minutes of onboarding.
@@ -50,22 +95,22 @@ Learn more about [Defender for APIs](defender-for-apis-introduction.md).
 
 1. In the Defender for Cloud portal, select **Recommendations**.
 1. Search for *Defender for APIs*.
-1. Under **Enable enhanced security features**, select the security recommendation **Azure API Management APIs should be onboarded to Defender for APIs**:
+1. Under **Enable enhanced security features** select the security recommendation **Azure API Management APIs should be onboarded to Defender for APIs**:
 
     :::image type="content" source="media/defender-for-apis-deploy/api-recommendations.png" alt-text="Screenshot that shows how to turn on the Defender for APIs plan from the recommendation." lightbox="media/defender-for-apis-deploy/api-recommendations.png":::
 
-1. In the recommendation page, you can review the recommendation severity, update interval, description, and remediation steps.
+1. In the recommendation page you can review the recommendation severity, update interval, description, and remediation steps.
 1. Review the resources in scope for the recommendations:
     - **Unhealthy resources**: Resources that aren't onboarded to Defender for APIs.
     - **Healthy resources**: API resources that are onboarded to Defender for APIs.
     - **Not applicable resources**: API resources that aren't applicable for protection.
 
-1. In **Unhealthy resources**, select the APIs that you want to protect with Defender for APIs.
+1. In **Unhealthy resources** select the APIs that you want to protect with Defender for APIs.
 1. Select **Fix**:
 
     :::image type="content" source="media/defender-for-apis-deploy/api-recommendation-details.png" alt-text="Screenshot that shows the recommendation details for turning on the plan." lightbox="media/defender-for-apis-deploy/api-recommendation-details.png":::
 
-1. In **Fixing resources**, review the selected APIs, and select **Fix resources**:
+1. In **Fixing resources** review the selected APIs and select **Fix resources**:
 
     :::image type="content" source="media/defender-for-apis-deploy/fix-resources.png" alt-text="Screenshot that shows how to fix unhealthy resources." lightbox="media/defender-for-apis-deploy/fix-resources.png":::
 
@@ -85,4 +130,5 @@ You can also navigate to other collections to learn about what types of insights
 
 ## Next steps
 
-[Review](defender-for-apis-posture.md) API threats and security posture.
+- [Review](defender-for-apis-posture.md) API threats and security posture.
+- [Investigate API findings, recommendations, and alerts](defender-for-apis-posture.md). 

articles/defender-for-cloud/faq-defender-for-apis.yml

@@ -29,7 +29,10 @@ sections:
 
       - question: Does Defender for APIs collect API traffic logs from Azure API Management?
         answer: Defender for APIs receives a copy of all of the HTTP request and response traffic sent to the API management service for all onboarded APIs. This includes the request URL, the response status code, and a subset of HTTP headers for the requests and responses. Also, Defender for APIs receives a copy of some of the HTTP request and response bodies. The request and response bodies received by Defender for APIs are capped at a size of 64 KB.
-              
+
+      - question: Why can't I select multiple resources?
+        answer: API Management service resources don't enable multi-selection with metrics. You can let the API Management service team know this capability is important and upvote this request.
+
   - name: Questions related to region/geo 
     questions:
       - question: I just moved my APIs within my Azure API Management service to a new region. Why are these not updated?