Master API Connections in Azure with Bicep
Microsoft provides extensive documentation on deploying almost any Azure resource using Bicep. This documentation includes detailed Bicep definitions for nearly all Azure resources, explaining which properties are required or optional and the value type each property accepts. This is very helpful for defining and deploying commonly used resources like Virtual Machines, Log Analytics Workspaces, and Function Apps, as they generally don’t require any custom properties beyond what the official Bicep documentation provides. However, API connections are a completely different story.
Imagine you need to set up a pipeline in Azure DevOps to automate the deployment of a solution’s infrastructure, which includes Logic Apps workflows. These workflows use other resources like Key Vaults, Storage Accounts, and Service Bus Queues. To use these resources, you need to deploy API connections. However, when you look at the official documentation of Bicep, you find that while it lists the basic properties, it requires more detailed instructions on how to authenticate appropriately with specific resources. This is where the real challenge starts.
Hours slip by as you scour blogs and repositories for examples, trying to piece together the correct configuration. This is a common scenario for many Azure developers. But what if there was a simpler way to know exactly which parameters are needed and where to define them for every API connection type?
Typical Authentication Scenarios for API Connections
API connection definitions vary depending on the resource one tries to connect to. This is easily noticed when designing Logic Apps workflows directly in the Azure Portal. For example, when adding an SQL Server action, the developer must provide the connection information, which in this case are a name for the connection, the authentication type to use, and the account credentials, which vary depending on the authentication type.
So, if you try to create an API connection leveraging a service principal, you’ll need to set:
- Tenant ID
- Client ID
- Client Secret of the Microsoft Entra ID application.
Creating a SQL Server API connection via SQL Server authentication
Yet, if you try to create an API connection leveraging SQL Server authentication, you’ll need to set:
- SQL Server name
- SQL Database name
- Username
- Password
- If the instance is hosted on-premises, the Azure on-premises data gateway
Creating a SQL Server API connection via SQL Server authenticationSimilarly, when adding a Service Bus action, the developer must set the service bus namespace endpoint to leverage a managed identity as the authentication type or the service bus connection string to authenticate via an access key.
Creating a Service Bus API Connection with Managed Identity
Creating a Service Bus API Connection with Access Key
Identifying these authentication parameters is straightforward in the Azure Portal because the UI guides you through the necessary fields in the Designer. However, these parameters are not as readily apparent when defining the API connection in Bicep, leading to potential confusion and difficulty during deployment.
Challenges and Documentation Gaps in Deploying API Connections with Bicep
For API connections, the official documentation offers a format to create Microsoft.Web/connections resources serve as a general template for deploying API connection resources for any Logic Apps connector. However, developers still face several vital questions:
- Under which property of the proposed template do I set the parameters to authenticate the connection? Should they be nested under the customParameterValues, nonSecretParameterValues, or parameterValues?
- What are the expected parameter names for a specific Logic Apps connector?
- If I need to use an on-premises data gateway, how can I set that through Bicep?
- How can I determine the authentication parameters for a custom API connection?
While many blog posts and repositories provide examples of how to define an API connection in Bicep for common Azure resources like Azure SQL Server, Service Bus, and Storage Accounts, Microsoft also offers some quickstart Bicep templates, including examples of how to use managed identities, the information can still be fragmented.
However, what if you need to deploy an API connection to an Azure service that the community hasn’t well documented? The lack of clear, comprehensive examples for less common services can make this challenging.
Fortunately, developers can rely on the Connectors reference overview to identify the properties needed to authenticate an API connection. It provides vital information about all connectors for Microsoft Power Automate, Microsoft Power Apps, and Azure Logic Apps. Each connector’s reference article includes a “Creating a connection” section that details the supported authentication types and the required authentication parameters. For example, the “Creating a connection” section of the SQL Server connector reference page lists the same supported authentication types found in the Logic Apps Designer in the Azure Portal.
SQL Server connector reference article
Part of the SQL Server connector supported authentication types.
Parameters for SQL Server authentication
However, even if you know which parameters are required, you might still wonder where to set these parameters in the template. Should they be nested under customParameterValues, nonSecretParameterValues, or parameterValues? This is where the browser’s development tools come in handy.
Leveraging Browser Tools and Practical Tips to Define API Connections
A useful trick for determining the correct resource definition for any API connection is to use the browser’s development tools while manually creating an API connection from the Logic Apps Designer in the Azure Portal.
For example, let’s use the SQL Server connector. In the Logic Apps Designer, open the browser’s Developer tools panel and select the Network tab before creating a new connection. Clear all current traces to clean the activity log.
In the Logic Apps Designer with the Developer Tools pane open before creating the connection
Create a new connection and stop recording the network trace once the action is refreshed. Examine the payload of the outgoing request to Azure, which reveals the information sent to the Azure Resource Manager. This shows how the configurations made through the portal are translated into JSON, providing valuable insight for defining your API connection Bicep templates.
Request payload after creating the connection
The payload displays the property names used, the data types of their values, and where the authentication parameters should be placed. In this example, the account information for SQL Server authentication goes under the parameterValueSet property.
It’s important to note that while the browser’s Developer tools provide insights into the expected authentication parameters, the payload format may not always align with the proposed API connection Bicep definition. According to the API connection Bicep reference, the customParameterValues, nonSecretParameterValues, and parameterValues properties expect an object of key-value pairs. However, when using the HTTP With Microsoft Entra ID connector with an on-premises data gateway, the Developer tools show that the resource ID is sent in an id property nested under the gateway.
Request payload after creating the connection
In such cases, you can review the API connection’s Resource JSON in the Azure Portal for more details about the authentication parameters. Remember, Bicep acts as an abstraction layer for ARM templates, so we can still define our Bicep template with the properties that will be converted, even if those properties are not explicitly defined in the reference.
JSON view of the API connection in the Azure Portal
API connection Bicep template with gateway property
Conclusion
While Microsoft’s documentation provides a solid foundation for deploying Azure resources using Bicep, it is a continuously evolving knowledge base. This growth is fueled by sharing our small wins and valuable insights from trial and error beyond the official documentation. Adding a dedicated section to the API connections Bicep reference site, detailing authentication types and their associated parameters from a Bicep perspective for each connector could be highly beneficial. This addition would help individual developers and enrich the entire Azure development community.
