Azure API Management APIs should be onboarded to Defender for APIs

What does the recommendation "Azure API Management APIs should be onboarded to Defender for APIs" check?

Flags REST APIs published in an Azure API Management instance that have not been onboarded to the Microsoft Defender for APIs plan, so their runtime traffic is not being inspected for threats. It checks each individual API, not just whether the plan is switched on for the subscription: enabling the plan is necessary but not sufficient, and an API stays unprotected until it is explicitly onboarded. Onboarding is asynchronous, so a newly onboarded API can take up to 50 minutes to clear from the recommendation. The control does not cover APIs exposed through the API Management self-hosted gateway, APIs managed inside API Management workspaces, or non-REST protocols such as SOAP, GraphQL and WebSocket, none of which Defender for APIs currently discovers or analyses.

Why does "Azure API Management APIs should be onboarded to Defender for APIs" matter?

An API Management gateway is usually the front door to your most sensitive backends: customer records, payments, partner integrations. Without Defender for APIs onboarding, that traffic flows through with no behavioural analysis, so credential stuffing, anomalous data exfiltration and the OWASP API Top 10 patterns pass undetected until they surface as a breach. The gap is easy to miss because the gateway itself stays healthy and responsive while abuse is under way: there is nothing in the request logs that obviously distinguishes a legitimate caller from an attacker replaying stolen tokens. Defender for APIs continuously inspects onboarded traffic and raises alerts on suspicious behaviour, and it also surfaces posture findings such as unauthenticated or dormant APIs. That early signal gives you the chance to respond before an authenticated abuse of a business API turns into regulatory exposure, contractual penalties and customer data loss.

How do I fix "Azure API Management APIs should be onboarded to Defender for APIs"?

1. Enable the Defender for APIs plan on the subscription so the option becomes available: az security pricing create -n Api --tier Standard --subplan P1 (the plan resource is Microsoft.Security/pricings named 'Api'; subplan P1 covers the standard onboarding tier).
2. Onboard each unprotected REST API. In the Defender for Cloud portal, open the 'Azure API Management APIs should be onboarded to Defender for APIs' recommendation, tick the APIs to protect and select Fix; alternatively run the Az PowerShell cmdlet Invoke-AzSecurityApiCollectionApimOnboard for a named API.
3. Codify both steps so new APIs inherit protection: declare the Microsoft.Security/pricings 'Api' resource with pricingTier 'Standard' and subPlan 'P1' in Bicep, and add the per-API onboarding to your deployment pipeline rather than relying on manual portal clicks.

# 1. Enable the Defender for APIs plan on the subscription so onboarded APIs are inspected.
az security pricing create --name Api --tier Standard

# 2. Disable the deprecated direct management endpoint (retired 15 March 2025).
#    'customProperties' on the service controls this gateway behaviour.
az apim update --name apim-prod --resource-group rg-platform \
  --set 'properties.customProperties."Microsoft.WindowsAzure.ApiManagement.Gateway.ManagementEndpoint"=false'

# 3. Re-enable backend certificate chain and name validation on a backend that
#    had it switched off. There is no native 'az apim backend' TLS flag, so PUT
#    the documented 'tls' block via the management API (api-version 2024-05-01).
sub=$(az account show --query id -o tsv)
az rest --method put \
  --uri "https://management.azure.com/subscriptions/$sub/resourceGroups/rg-platform/providers/Microsoft.ApiManagement/service/apim-prod/backends/payments-backend?api-version=2024-05-01" \
  --body '{"properties":{"url":"https://payments.internal/","protocol":"http","tls":{"validateCertificateChain":true,"validateCertificateName":true}}}'

# 4. Ratchet it shut: audit any instance whose management endpoint stays enabled.
#    Look the built-in policy up by display name; never hardcode a definition GUID.
pid=$(az policy definition list \
  --query "[?displayName=='API Management direct management endpoint should not be enabled'].name" -o tsv)
az policy assignment create \
  --name audit-apim-mgmt-endpoint \
  --policy "$pid" \
  --scope "/subscriptions/$sub"