Blog Post

Azure Network Security Blog
10 MIN READ

Getting Started with Azure DDoS Protection REST API: A Step-by-Step Guide

davidfrazee's avatar
davidfrazee
Icon for Microsoft rankMicrosoft
Sep 24, 2024

REST API is a cornerstone in the management of resources on Azure, providing a streamlined and efficient approach for executing create, read, update, and delete (CRUD) operations. By leveraging HTTP methods such as GET, POST, PUT, and DELETE, REST API simplifies resource manipulation for administrators. Moreover, REST API’s support for various data formats, including JSON and XML, enhances its versatility, making it indispensable for automating workflows and facilitating continuous deployment and integration practices. Focusing on Azure DDoS Protection, we will delve into its REST API integration, which enables the configuration of plans, association of virtual networks and individual resources, and real-time protection status. This integration is crucial for maintaining robust security in the fast-paced environment of cloud deployments. It ensures that security protocols are not only enhanced but also keep pace with the rapid deployment cycles characteristic of modern cloud infrastructures.

 

Getting Started

In the following examples, we’ll be using Postman to send our REST API requests to Azure Resource Manager to create, update, and delete the Azure DDoS Protection plan. We’ll also manipulate virtual network and public IP resources to receive DDoS protection status and enable protection for specified resources. For Azure DDoS Network Protection, we will link a virtual network to a DDoS Protection Plan, ensuring that all resources within the virtual network are protected. For Azure DDoS IP Protection, we will enable DDoS protection directly on a public IP without needing a DDoS plan, providing flexibility for individual resources. There are other methods and tools to send REST APIs outside of Postman, such as PowerShell, Az CLI, Swagger, and more. The basics will be the same regardless of the tool or method used, just our interface will be different. To follow along, check out the prerequisites below to get started.

 

Prerequisites:

If you’re following along and have followed the prerequisites, you should now have your Postman Collection configured to something similar as below. Our first screenshot shows the Authorization tab in the Postman Collection. We’re going to use the Auth Type of Bearer Token and use the variable from our variables tab.

 

 

Next, we have our pre-request script that you can grab from the linked blog above. This script is needed to send the requests continuously to Azure Resource Manager.

 

 

Lastly, we have our variables defined to use in our Postman Collection.

 

 

With our Postman profiles configured, we can begin managing Azure resources outside of the Azure Portal in a quick and seamless manner. When sending a REST API request, there are mandatory fields that need to be present, depending on the type of request sent. To create a new Azure DDoS Protection plan or to update an existing one, we’ll need to use a PUT command, which requires 4 URI parameters and a Request Body. The URI parameter requirements are similar for the Virtual Network and Public IP resources.

 

URI Parameters – DDoS Protection:

 

URI Parameters – Virtual Network:

 

URI Parameters – Public IP:

 

Example of the request URI – DDoS Protection: PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/ddosProtectionPlans/{ddosProtectionPlanName}?api-version=2024-01-01 

 

Example of the request URI – Virtual Network: PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/virtualNetworks/{virtualNetworkName}?api-version=2024-01-01 

 

Example of the request URI – Public IP: PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/publicIPAddresses/{publicIpAddressName}?api-version=2024-01-01  

 

Request Body – DDoS Protection:

 

Request Body – Virtual Network:

 

Request Body – Public IP:

 

When sending a GET request or a DELETE request, we no longer require the request body, only the URI parameters to pull the information for the resource we want.

 

Creating an Azure DDoS Protection Plan

Azure DDoS Protection, combined with application design best practices, provides enhanced DDoS mitigation features to defend against DDoS attacks. It's automatically tuned to help protect your specific Azure resources in a virtual network. Protection is simple to enable on any new or existing virtual network, and it requires no application or resource changes.

 

Creating an Azure DDoS Protection plan is incredibly simple with the API as it only accepts two definitions in the request body with only one being required, the location. Looking at the JSON example below, we’ve only defined our location for the plan to live in South Central US. The location for an Azure DDoS Protection plan is nothing more than a placeholder, as a plan can span across resource groups, subscriptions, and regions.

{

    "location": "SouthCentralUS"

}

 

 

After sending the PUT command to create the Azure DDoS Protection plan, we’ll use a GET to pull the resource and check out what’s been created. It’s important to check the provisioning state and ensure that it is in a Succeeded state before sending another PUT. Sending another PUT while the policy is updating will place the resource into a failed state. As best practice, always check the provisioning state of all your resources before making any changes.

 

Using the example below, we can see the name that was passed through the URI parameters and our location that was passed in the body. You’ll also notice that there are Azure Tags associated with the protection plan. Although we didn’t set these tags in our request body, there is automation on this subscription that applies tags once created. A GET command is a great way to look at any resource in Azure and understand how that resource has been configured and its current provisioned state.

 

 

With this simple example, we can already see how REST API is a flexible and quick way to create and manage resources in Azure. This method allows us to see exactly how a resource is configured in JSON, without having to navigate multiple blades in the Azure Portal.

 

Protecting an Azure Virtual Network with Azure DDoS Protection

Now that we have established an Azure DDoS Protection plan, the next step is to link or associate the Azure Virtual Networks with the plan to initiate protection. First, we’ll run a GET against the virtual network to check the current protection status and if there are any plans already associated with the network. The screenshot below shows that the virtual network is not protected with Azure DDoS Protection and has no plan associated.

 

 

There is also another REST API call that can be made to check the DDoS protection status of a virtual network. The call is named ‘List Ddos Protection Status’ and we can see what this looks like below. It requires a POST call, rather than a GET, and this call might return a 202 Accepted status. This is a status code for asynchronous operations and will require a second REST API call to get the details you’re looking for. To do this in Postman, click on the Headers tab for the response and find the Header called Location. Copy the entire value that you find in the Location header and run a GET against it. If you don’t have a plan associated with the virtual network, what you’ll see is a list of Public IPs that are associated with the virtual network and if the workload is protected. Once we associate the plan we created earlier, we’ll run this call again and see how the information changes.

 

 

 

 

To get the plan associated with the virtual network, we’ll need to send an Update to Azure Resource Manager (ARM) using a PUT command, and we’ll have to be careful not to overwrite the configurations of the already existing virtual network. The best way to do this is to run a GET against the virtual network like we did earlier, then copy & paste the JSON response body into the request body of our PUT call. Once we have our already existing virtual network configurations defined in our PUT, we can then add additional body definitions to protect the virtual network with the Azure DDoS Protection plan.

 

Below is a JSON snippet of what this will look like. Under properties, we will change the boolean of ‘enableDdosProtection’ from false to true and then add the resourceID of the Azure DDoS Protection plan.

 

"enableDdosProtection": true,

"ddosProtectionPlan": {

    "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/xxxxxxxx/providers/Microsoft.Network/ddosProtectionPlans/ddosPlan-restAPI"

}

 

 

We’ve associated the plan and enabled DDoS protection for the virtual network. Let’s run the ‘List Ddos Protection Status’ call once more to see what the results are. Our public IP now shows that it is a protected workload, and we can see the resourceID of the Azure DDoS Protection plan.

 

 

Lastly, let’s run a GET against our Azure DDoS Protection plan API to see if any properties have changed after associating an Azure Virtual Network. We can see below that a virtualNetworks array block has been added to the properties, with our virtual network information. This is a quick and easy way to check on all of the virtual networks associated with an Azure DDoS Protection plan.

 

 

Protecting an Azure Public IP with Azure DDoS Protection

Azure Public IP resources can be safeguarded against DDoS attacks using either Azure DDoS Network Protection or Azure DDoS IP Protection. Azure DDoS Network Protection provides comprehensive defense for entire virtual networks, leveraging always-on traffic monitoring and adaptive tuning to mitigate large-scale attacks. It requires customers to create a DDoS plan upfront which may be an overkill for SMB customers who have a small number of public IPs that they want to safeguard against DDoS attacks. For such cases, customers have an option to enable Azure DDoS IP Protection on their public IPs directly using the DdosSettings protectionMode property as shown below. Azure DDoS IP Protection offers targeted protection for individual public IP addresses. In this section, we’ll cover what it looks like when a public IP resource is protected under Azure DDoS Network Protection and how to enable Azure DDoS IP Protection.

 

Our first example shows a simple GET against a public IP resource that is associated with an Application Gateway in my virtual network. From the API call, we see there are ddosSettings under the properties and the protectionMode says ‘VirtualNetworkInherited’. This doesn’t truly show us the protection status of the public IP resource though, since a virtual network could be or could not be protected with a DDoS protection plan. To obtain the true value of the protection status, we’ll use another API call called ‘Ddos Protection Status’.

 

 

The ‘Ddos Protection Status’ API call is like the ‘List Ddos Protection Status’ for Azure Virtual Networks. When you make the initial POST call, you will most likely receive a 202 Accepted response. Remember to open the Headers tab in the response and copy the entire value of the Location header to run a GET call against it.

 

Below is a screenshot of what that call will return. We’re able to the resourceID of the public IP address, that the IP is a protected workload, and we can reference the DDoS protection plan resourceID.

 

 

To enable the Azure DDoS IP Protection SKU for an Azure Public IP resource, you would make a simple change to the ddosSettings block under properties from ‘VirtualNetworkInherited’, to ‘Enabled’. The ‘VirtualNetworkInherited’ value is the default value you’ll see on any Azure Public IP resource that has not been explicitly configured with Azure DDoS IP Protection or with a value of ‘Disabled’.

 

Below is a JSON snip of how to make the change with screenshot.

 

"ddosSettings": {

    "protectionMode": "Enabled"

 }

 

 

Deleting an Azure DDoS Protection Plan

Deleting an Azure DDoS Protection plan is simple but may require multiple steps if there are virtual networks associated with the plan during deletion. It is a prerequisite that all virtual network associations with the DDoS protection plan be removed before attempting a delete against the plan resource. As you can see below, I received a 400 Bad Request because there was still a virtual network that was using the DDoS protection plan. The error returned is useful, since it shows me exactly which resources are still using the plan, allowing me to go directly to that virtual network to remove the association.

 

 

Now we’ll remove the DDoS protection plan association using a PUT against the Azure Virtual Network. The removal requires that the boolean for ‘enableDdosProtection’ be set to false, and the ‘ddosProtectionPlan’ block be completely removed. Remember that since we’re only doing an Update to the virtual network resource, make sure to copy and paste a recent GET of the virtual network resource and make the minor changes to that JSON body.

 

 

Once the process above is complete, we can send the DELETE API call for the Azure DDoS Protection plan. You’ll notice that we get a 202 Accepted code and nothing in the response body. This is an indication of another async call that will require a second API call to get the information. The difference between this async call and the ones we executed previously is that we’re going to look for another Header other than ‘Location’. For our second API call, we need to find the Header, AzureAsyncOperation. Copy the full value of the AzureAsyncOperation header and run a GET against it. You’ll see a Suceeded status of the deletion for the Azure DDoS Protection plan.

 

 

 

Conclusion

In this guide, we’ve learned how to use the Azure REST API to create and configure an Azure DDoS Protection plan, as well as configure Azure DDoS IP Protection for a single public IP resource. We have seen how to use Postman to send HTTP requests to the Azure Resource Manager endpoint and how to authenticate with Azure Entra ID. We have also explored how to verify DDoS protection status for Azure Virtual Networks and Azure Public IP resources. To learn more about Azure REST API and Azure DDoS Protection, check out the referenced documentation below.

 

References

Updated Sep 24, 2024
Version 1.0
No CommentsBe the first to comment