In most Infrastructure as Code teams, Bicep quality checks start to look mature as soon as linting and deployment validation are in place. In practice, there is still a blind spot: logic-level testing of exported functions, types, and variables.

Most teams validate by deploying to a subscription and checking outcomes afterwards. That is useful, but it is also slow and expensive when what you actually want to verify is pure logic. A shared Bicep library changes, everything still compiles, and then a downstream module fails later in a deployment pipeline because a naming function or constructor behaviour subtly changed. That is exactly the type of issue we normally catch early in application development with unit tests.

If you maintain shared Bicep libraries, this gap hurts quickly:

• Naming functions drift without anyone noticing
• Type constructors change and break downstream modules
• Refactors feel risky because feedback loops are too long

I wanted a way to unit test Bicep logic directly, without deploying anything.

Introducing BicepConsoleTTK

To solve that problem, I created BicepConsoleTTK (Bicep Console Test Tool Kit).

It is a Pester-based framework that executes Bicep expressions through the Bicep console REPL, so you can assert outputs in fast, repeatable unit tests.

Repository:

At a high level, the toolkit gives you two commands:

• Import-Bicep: reads one or more Bicep files and extracts the exports you ask for
• Invoke-BicepExpression: runs those declarations plus your expression in bicep console and returns the result

Why This Approach Works

This lets you test Bicep logic in isolation, before template deployment.

Practical outcomes:

• Faster feedback during development
• More confidence when refactoring shared functions
• Cleaner CI pipelines for template libraries
• Better separation between unit tests (logic) and integration tests (deployment)

Features

• Familiar import syntax (named imports and wildcard imports)
• Multi-file import composition with preserved order
• Deduplication when the same member is imported multiple ways
• Setup declarations for multi-step scenarios
• Pipeline input support
• Cleaner Bicep console error reporting
• CI/CD-friendly, non-interactive execution

Prerequisites

• PowerShell 5.1 (Desktop) or 7+
• Pester 5.x
• Bicep CLI 0.42.1+
• bicep available on your PATH

Installation

From PowerShell Gallery

Install-Module -Name BicepConsoleTTK -Repository PSGallery

In your test file:

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

From Source

git clone https://github.com/Andrew-D-Wilson/bicep-console-test-framework.git
Import-Module "$PSScriptRoot/../src/BicepConsoleTTK" -Force

Copilot Integration

This repository ships two complementary artefacts that teach GitHub Copilot how to write BicepConsoleTTK tests.

Agent Skill (Recommended)

The .github/skills/bicepconsolettk/SKILL.md file is a GitHub Copilot agent skill. When Copilot is working in agent mode, it automatically loads this skill whenever the task is related to writing Bicep tests, injecting the full authoring guide into its context.

The skill is discovered automatically from .github/skills/ in any repository that contains it.

VS Code Instructions File

The bicepconsolettk.instructions.md file is a VS Code Copilot custom instructions file.

To use it in your own repository:

1. Copy the file to .github/instructions/bicepconsolettk.instructions.md
2. Keep applyTo: "**/*.Tests.ps1" so it is scoped to Pester test files
3. Ask Copilot to generate or refactor tests in your *.Tests.ps1 files

With both artefacts in place, Copilot gets better guidance in both agent-driven workflows and editor-scoped instruction workflows.

Usage

1. Import exports from Bicep files

$imports = Import-Bicep @(
	"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
	"import {basicResource}             from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
)

2. Evaluate an expression

$result = Invoke-BicepExpression -b $imports -e "newCoreParams('uksouth', 'uks', 'prod', 'myapp')"

3. Use setup declarations when needed

$setupDeclarations = @(
	"var projectNameStart = 'hello'",
	"var projectNameComplete = '`${projectNameStart}world'",
	"var coreParameters coreParams = newCoreParams('uksouth', 'uks', 'dev', projectNameComplete)"
)

$result = Invoke-BicepExpression -b $imports -s $setupDeclarations -e "basicResource('aks', coreParameters)"

Example Pester Test

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

Describe "Naming Functions" {
	BeforeAll {
		$script:imports = Import-Bicep @(
			"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
			"import {basicResource, csResource} from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
		)
	}

	It "basicResource includes abbreviation, project, environment and location" {
		$result = Invoke-BicepExpression -b $script:imports `
			-e "basicResource('aks', newCoreParams('uksouth', 'uks', 'dev', 'myapp'))"

		$result | Should -Be "'aks-myapp-dev-uksouth'"
	}
}

Run tests with:

Invoke-Pester -Path ./tests

How It Works (Short Version)

Import-Bicep parses import strings, resolves file paths, and extracts exported declarations from source files.

Invoke-BicepExpression sends those declarations and your expression into bicep console, captures output, and translates console noise into readable exceptions when failures occur.

That gives you deterministic, fast unit tests focused on logic instead of deployment orchestration.

Where This Fits in Your Testing Strategy

Use BicepConsoleTTK for:

• Function output verification
• Naming convention enforcement
• Shared type constructor validation
• Regression checks during refactoring

Still keep deployment/integration tests for:

• Resource runtime behavior
• Policy and RBAC interactions
• End-to-end environment validation

Both layers matter. This tool improves the unit-testing layer.

In Short

BicepConsoleTTK helps you test Bicep exports the same way you test application code: quickly, repeatedly, and early.

If your team relies on shared Bicep libraries, this can remove a lot of friction from your delivery pipeline while increasing confidence in every change.

⚠️ NOTE

Microsoft guidance is clear that Azure RBAC should be used for data plane authorization moving forward, instead of legacy access policies

• Azure role-based access control (Azure RBAC) vs. access policies (legacy)
• Provide access to Key Vault keys, certificates, and secrets with Azure role-based access control

Problem Space

When multiple applications share a single Azure Key Vault, access policy management can become an unexpected source of deployment risk → and the root cause is easy to miss.

// BICEP
resource KeyVaultDeploy 'Microsoft.KeyVault/vaults@2025-05-01' = {
  name: ''
  location: ''
  properties: {
    ...
    accessPolicies: []
    ...
  }
}

The accessPolicies property on the Microsoft.KeyVault/vaults ARM resource is a required field. In a shared Key Vault scenario, where the vault is owned and deployed by one application, the natural thing to do is set this to an empty array as the application does not own the other applications access policies, so it does not declare them.

This is where the problem begins.

When ARM deploys the Key Vault resource with accessPolicies set to an empty array [], it treats that as the desired state for the vault. Any access policies that existed previously (including those belonging to other applications) are removed.

Here is how the failure pattern plays out in practice:

1. Application A owns the Key Vault and deploys it with accessPolicies: [].
2. Immediately after, Application A’s IaC deploys its own access policies via a separate step (for example, using the Microsoft.KeyVault/vaults/accessPolicies child resource). Access is restored for Application A without apparent issue.
3. Application B’s access policies have been silently removed — it never re-deploys the key vault, only its own access policy step.
4. Application B fails at runtime when attempting secret, key, or certificate operations — authorization errors with no obvious cause.
5. Application B is re-deployed, its access policies are restored, and both applications work again — until the next time Application A’s pipeline runs.

This cycle repeats silently. Each Application A deployment is an outage for Application B, and the connection between the two is not obvious unless you know to look for it.

This can happen if you have the following setup:

• Multiple applications or pipelines sharing a Key Vault
• The Key Vault instance deployed as part of one application’s IaC
• Access configured through Key Vault access policies
• Each application’s pipeline independently managing only its own policy entries

Workarounds (Still Using Access Policies)

If moving to RBAC immediately is not possible, the following workarounds address the underlying coupling problem — but each comes with trade-offs.

1. Move the Key Vault to a Core Resources Deployment

Extract the Key Vault resource into a dedicated core infrastructure deployment, separate from any application pipeline. Application pipelines then only manage their own access policy entries against the pre-existing vault.

Benefits:

• The vault is no longer redeployed as part of application changes
• Eliminates the empty accessPolicies overwrite problem
• Makes ownership of the shared resource explicit

Trade-off:

• When the core resources deployment runs (for environment rebuilds, configuration changes, or disaster recovery), all dependent applications will need to be re-deployed afterwards to restore their access policy entries. This creates an operational dependency that must be planned for and communicated clearly across teams.

2. Provision a Separate Key Vault Per Application

Give each application its own dedicated Key Vault, eliminating the shared resource entirely.

Benefits:

• No cross-application policy coupling — each key vault is fully owned by one application
• Reduces blast radius of deployment mistakes
• Cleaner isolation and tenancy boundaries

Trade-offs:

• More key vaults to provision, monitor, rotate secrets in, and govern
• Increases operational overhead for certificate and secret lifecycle management
• Harder to get a unified view of secrets across the estate

This option improves isolation but does not solve the root-cause pattern; it just limits the blast radius per key vault.

The Real Solution: Move to Azure RBAC

The correct long-term fix is to stop using access policies for Key Vault data plane authorization entirely and adopt Azure RBAC role assignments.

With RBAC:

• Role assignments are additive and independently managed — assigning a role for Application B does not affect Application A’s assignments
• Authorization state is managed through Azure’s centralized RBAC model, consistent with the rest of the Azure platform
• Microsoft explicitly recommends RBAC over access policies for new and migrating workloads

The deployment pattern becomes:

1. Deploy the Key Vault resource. The accessPolicies field becomes irrelevant.
2. Each application independently deploys Microsoft.Authorization/roleAssignments scoped to the vault for its own managed identity or service principal.
3. An application deployment wont affect another application’s authorization.
4. A redeploy of the Key Vault resource won’t remove existing application’s authorizations.

Practical migration approach:

1. Enable the RBAC permission model on the Key Vault IaC (enableRbacAuthorization: true).
2. Map existing access policy permissions to the appropriate built-in Key Vault RBAC roles (for example Key Vault Secrets User, Key Vault Certificates User).
   • Assign roles to the required identities at the appropriate scope (Key Vault, Key Vault Secret/Certificate).
3. Remove legacy access policy configuration from all IaC templates.
4. Deploy IaC and Validate application behavior against the new authorization model.

Useful Microsoft documentation:

• RBAC vs access policy comparison and recommendation
• RBAC implementation guidance for Key Vault

Closing Thoughts

The empty accessPolicies: [] pattern is easy to arrive at — the field is required, the application does not own the other policies, so an empty array seems reasonable. In a single-application setup it causes no problems. In a shared-vault, multi-application setup it causes silent, repeating outages that are hard to diagnose without knowing where to look.

The workarounds described here reduce the risk while a migration is planned, but neither fully resolves the underlying problem.

The right answer is Azure RBAC. Role assignments are independent, additive, and do not interfere with each other across application boundaries. Moving to RBAC removes this class of problem entirely.

As Bicep adoption grows, so does the complexity of the environments and teams using it. Without clear authoring practices, Bicep codebases can quickly become inconsistent, hard to maintain, and error-prone. In this post I wanted to share some practical authoring practices and anti-patterns to help you and your team write better Bicep code.

Why Define and Stick to Your Authoring Practices

Defining and following authoring practices ensures:

• Consistency across your codebase and team
• Easier onboarding for new contributors
• Fewer errors and less technical debt
• Improved maintainability and clarity

Below are some key practices and common anti-patterns to consider.

Authoring Practices

1. Folder Structure

Organise your Bicep files in a logical folder structure. For example, group modules by resource type or deployment context. This makes navigation and reuse easier:

├── modules/
│   ├── storage/
│   └── networking/
├── main.bicep
├── parameters/

2. Template Structure

Keep your templates clean and modular. Use modules for reusable components, and keep your main entry point focused on orchestration. Avoid putting everything in a single file.

3. Well Defined Names

Use clear, descriptive names for resources, parameters, and variables. Avoid abbreviations that aren’t widely understood. For example, prefer storageAccountName over saName.

4. Descriptions

Add descriptions to parameters, outputs, and resources. This helps users understand intent and usage:

@description('Configurable name for the application storage account')
param storageAccountName string

5. Comments

Use comments to explain why something is done, not what is done. Avoid echoing the code. Good comments provide context or rationale.

6. Constraints and Metadata

Leverage allowed values, min/max length, and metadata to enforce constraints and provide guidance:

@minLength(3)
@maxLength(24)
@allowed([ 'dev' 'test' 'prod' ])
param environment string

Make sure to use these where there is a specific need, over constraining parameters can equally cause issues.

7. Contracts

Define clear contracts for your modules: what parameters are required, what outputs are provided, and what assumptions are made. Document these in the module and in a README.

8. README

Modules and major orchestrating templates should have a README explaining its purpose and usage. This is invaluable for onboarding and reuse.

9. Bicep Linting

Use Bicep linting as part of your authoring workflow to catch issues early and enforce consistency. Define team linting rules in bicepconfig.json, run lint checks locally during development, and enforce them in CI to prevent low-quality or non-compliant templates from being merged.

10. AI-Generated Templates and Conformance

If you are using AI to generate Bicep, treat your authoring practices as executable guardrails rather than optional guidance.

Start by defining a clear generation contract in your prompt and repository standards:

• Require a specific folder structure and file naming convention
• Require module contracts (documented params/outputs and assumptions)
• Require descriptions, meaningful names, and no dead code
• Require lint-clean output before a template is considered complete

Then enforce conformance automatically in CI:

• Validate formatting and linting on every pull request
• Fail builds when lint rules are violated
• Optionally add policy checks (for example, naming, locations, and SKUs)
• Require human review for architectural decisions, not just syntax correctness

Finally, use a feedback loop. When reviewers find repeated AI mistakes, update your prompt template, lint configuration, and module examples so the next generation cycle improves by default.

Anti-Patterns

1. Premature Abstraction

Don’t create modules or abstractions before you have a real need. Over-abstraction leads to unnecessary complexity and maintenance overhead.

2. Over-Specification

Avoid making every resource parameter configurable if it’s not needed. Too many parameters can confuse users and make templates harder to use.

3. Echo Comments

Comments that simply restate the code add no value. For example:

// Set the storage account name
param storageAccountName string

Instead, explain why a value is needed or any constraints.

4. Dead Code

Remove unused parameters, variables, and resources. Dead code clutters templates and can cause confusion or errors.

5. Generic Copy-Paste Documentation

Avoid boilerplate documentation that doesn’t reflect the actual template. Tailor docs and comments to the specific module or resource.

6. Poorly Defined Names

Names like var1 or resource2 make templates hard to understand. Use meaningful, descriptive names everywhere.

Conclusion

Establishing and following authoring practices for Bicep will help your team deliver infrastructure as code that is robust, maintainable, and easy to understand. Avoid common anti-patterns, and invest in clarity and documentation.

There have been few times where I have landed into this particular predicament whereby either by my own doing or through the use of another’s code base, a deep nested or thoroughly utilised (parameter/variable/or other defined item) has been created with the same name as a Bicep function. As by Murphy’s law, its only once you have reached this point of no return that you realise that your items name conflicts.

Now if you are like many in your unawares, your thoughts and actions will conclude to a singular one of ’that sucks… followed by a nasty refactor'.

Solution - Namespaces

Namespaces are a declarative scope in which identifiers such as the names of types, functions, and variables can be declared. These namespaces are used to organise code into logical groups and to prevent name collisions such as the one you are currently experiencing.

Thankfully, in Bicep there are two namespaces where all functions are split, az and sys.

• az | Contains functions that are specific to an Azure deployment such as:
  • deployment
  • environment
  • resourceGroup
  • subscription
• sys | Contains functions that are used to construct values, and decorators for parameters and resource loops. This includes but is not limited to:
  • [Array] concat
  • [File] loadJsonContent
  • [Lambda] filter
  • [Logical] bool
  • [Numeric] int
  • [String] contains

To make use of these namespaces, simply add the namespace identifier in front of the function. The example below shows a real world example of this issue where a parameter name ‘environment’ has been extensively utilised in this template and many others. This particular template is being used to deploy an AuthProvider in API Management, and the author wishes to utilise the environment function for the authentication.loginEndpoint. Without the use of the az namespace, the environment parameter would need to be refactored both in this template and wider templates for consistency.

/******************************************
Bicep Template: Function Namespace Example
Author: Andrew Wilson
******************************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('The environment to deploy the resources to.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string = 'dev'

...

// ** Resources **
// ***************

...

// Create a new Auth Provider in APIM Credential Manager
resource AuthorizationProvider 'Microsoft.ApiManagement/service/authorizationProviders@2024-05-01' = {
  ...
  properties: {
    ...
    oauth2: {
      ...
      grantTypes: {
        clientCredentials: {
          loginUri: az.environment().authentication.loginEndpoint
        }
      }
    }
  }
}

As always, have a play, and happy Bicep-ing!

Building on our previous exploration of Typed Variables, today we’re diving into one of my favorite patterns for creating maintainable and reusable Bicep templates: the Shared Variable File Pattern. This approach transforms your templates from being tightly coupled to specific configurations into truly agnostic, environment-ready solutions.

The beauty of this pattern lies in its simplicity - by extracting configuration data into external JSON or YAML files, you can create templates that adapt without modification. When combined with typed variables, this approach becomes even more powerful, providing compile-time validation and enhanced developer experience.

Why Use Config Files?

Before diving into the implementation, let’s understand why this pattern is so valuable:

1. Separation of Concerns: Keep your infrastructure logic separate from configuration data
2. Reduced Template Complexity: Remove large, complex variable definitions from your templates for better readability
3. Reusability: Share common configurations across multiple templates without duplication
4. Team Collaboration: Non-technical team members can modify configurations without touching Bicep code

The Pattern in Action

Traditional Approach (What We Want to Avoid)

Traditionally, you might embed all configuration directly in your Bicep template:

var nsgRules = [
  {
    name: 'AllowManagementEndpoint'
    properties: {
      description: 'Management endpoint for Azure portal and PowerShell'
      sourceAddressPrefix: 'ApiManagement'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '3443'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 100
      direction: 'Inbound'
    }
  }
  {
    name: 'AllowAzureInfrastructureLoadBalancer'
    properties: {
      description: 'Azure Infrastructure Load Balancer'
      sourceAddressPrefix: 'AzureLoadBalancer'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '6390'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 110
      direction: 'Inbound'
    }
  }
  // ... many more rules
]

This approach has several downsides:

• Templates become bloated and hard to read
• Changes require modifying Bicep code
• No separation between infrastructure logic and configuration data

Modern Approach with Config Files

Let’s transform this using the shared variable file pattern combined with typed variables.

Step 1: Create Your Config File

Create the configuration file for your deployment:

configs/nsg-rules.json

{
  "securityRules": [
    {
      "name": "AllowManagementEndpoint",
      "properties": {
        "description": "Management endpoint for Azure portal and PowerShell",
        "sourceAddressPrefix": "ApiManagement",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "3443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 100,
        "direction": "Inbound"
      }
    },
    {
      "name": "AllowDeveloperAccess",
      "properties": {
        "description": "Allow developer access from corporate network",
        "sourceAddressPrefix": "10.0.0.0/8",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 200,
        "direction": "Inbound"
      }
    }
  ]
}

Step 2: Define Typed Variables

Create a user-defined type to ensure your config files match the expected structure:

// User-Defined Types
// ******************

@sealed()
@description('Defines the structure for NSG security rule properties.')
type nsgSecurityRuleProperties = {
  @description('Description of the security rule.')
  description: string
  @description('Source address prefix or tag.')
  sourceAddressPrefix: string
  @description('Source port range.')
  sourcePortRange: string
  @description('Destination address prefix or tag.')
  destinationAddressPrefix: string
  @description('Destination port range.')
  destinationPortRange: string
  @description('Network protocol (Tcp, Udp, or *).')
  protocol: 'Tcp' | 'Udp' | '*'
  @description('Access type (Allow or Deny).')
  access: 'Allow' | 'Deny'
  @description('Priority value (100-4096).')
  priority: int
  @description('Direction (Inbound or Outbound).')
  direction: 'Inbound' | 'Outbound'
}

@sealed()
@description('Defines the structure for NSG security rule.')
type nsgSecurityRule = {
  @description('Name of the security rule.')
  name: string
  @description('Properties of the security rule.')
  properties: nsgSecurityRuleProperties
}

@sealed()
@description('Defines the structure for NSG configuration file.')
type nsgConfig = {
  @description('Array of security rules.')
  securityRules: nsgSecurityRule[]
}

Step 3: Load and Use Configuration

Now your Bicep template becomes clean and agnostic:

// Parameters
// **********

@description('Environment to deploy to.')
param environment string

// Variables
// *********

// Load configuration with full type safety
var nsgConf nsgConfig = loadJsonContent('./configs/nsg-rules.json')

// Resources
// *********

resource networkSecurityGroup 'Microsoft.Network/networkSecurityGroups@2024-01-01' = {
  name: 'nsg-apim'
  location: resourceGroup().location
  properties: {
    securityRules: nsgConfig.securityRules
  }
}

Advanced Techniques

Multi-Component Configuration Files

You can organise multiple configuration aspects in a single file and load only what you need:

configs/apim-config.json

{
  "networking": {
    "securityRules": [...],
    "subnets": [...]
  },
  "apim": {
    "sku": {
      "name": "Developer",
      "capacity": 1
    },
    "policies": [...]
  },
  "monitoring": {
    "logAnalytics": {...},
    "alerts": [...]
  }
}

Load specific sections using JSONPath:

// Load only the networking configuration
var networkingConfig = loadJsonContent('./configs/apim-config.json', 'networking')

// Load only the APIM configuration
var apimConfig = loadJsonContent('./configs/apim-config.json', 'apim')

Best Practices

1. Use Typed Variables: Define user-defined types for your configuration structures - this provides compile-time validation and excellent IntelliSense support
2. Logical File Organisation: Create separate config files for different aspects (networking, security, monitoring) rather than one monolithic file
3. Validate Early: Let typed variables catch configuration mismatches during authoring, not deployment
4. Size Considerations: Remember that loaded content is included in the generated ARM template (4MB limit)
5. Version Control: Keep config files in source control alongside your Bicep templates

Real-World Benefits

This pattern has transformed how I approach Bicep development:

• Faster Development: IntelliSense support with typed variables makes configuration editing a breeze
• Fewer Deployment Failures: Compile-time validation catches configuration errors before deployment
• Better Team Collaboration: Operations teams can modify configs without touching infrastructure code
• Easier Maintenance: Changes to configuration don’t require Bicep code modifications

Summary

The shared variable file pattern, enhanced with typed variables, creates a powerful combination for building maintainable, agnostic Bicep templates. By separating configuration from infrastructure logic, you gain flexibility, reusability, and compile-time safety that makes your Infrastructure as Code truly robust. Happy Bicep-ing!

One of my core goals when writing IaC templates is ensuring reusability of common components, resources, and in this case, configuration. More often than not, I see configuration that is broadly common between resources (except for one or two properties) being duplicated throughout templates. This duplication means that changing a single property value requires updates across the entire codebase—a change that’s not trivial to manage unless you’re well-versed with the codebase and understand all areas where the configuration is implemented.

This pattern becomes particularly problematic as your infrastructure grows in complexity. Consider scenarios where you need to update a common tag value, modify a naming convention, or adjust a configuration parameter across dozens of resources. Without proper abstraction, these seemingly simple changes can become error-prone maintenance nightmares.

In this post, I’ll demonstrate two powerful Bicep techniques to transform static, duplicated configuration into dynamic, reusable patterns that will make your templates more maintainable and less prone to configuration drift.

Common Configuration Scenarios

Before diving into solutions, let’s examine two common scenarios where static configuration creates maintenance headaches:

Scenario 1: Resource Tagging

Every Azure resource should be properly tagged for governance, cost tracking, and management. However, I frequently see templates where tags are copy-pasted across resources, creating maintenance debt:

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  // ... other properties
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
  // ... other properties
}

This approach works for a single resource, but imagine maintaining this across 50+ resources. When the business unit name changes or you need to add a new compliance tag, you’re looking at a significant refactoring effort.

Scenario 2: Complex Configuration Structures

Complex JSON configurations, such as Consumption Logic App workflow definitions, often contain embedded values that need to vary between environments or deployments:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "12:00:00" // ← Currently hard-coded static configuration
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1, // ← Currently hard-coded static configuration
                    "schedule": {
                        "hours": [
                            "11"
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "2" // ← Currently hard-coded static configuration
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

In this Consumption Logic App workflow, the recurrence interval, evaluatedRecurrence interval, and condition time values are hard-coded. If you need different intervals or values for different environments (perhaps more frequent polling in production), you’d need to maintain separate configuration files or manually edit values during deployment.

My Recommended Approaches

Approach 1: Union Function for Object Composition

The union() function is perfect for combining base configuration with resource-specific overrides. This approach works exceptionally well for scenarios like tagging, where you have a core set of common properties and some resource-specific additions.

The Problem: Without union, you end up repeating common tags across every resource:

// Bad: Repeated configuration
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'  // Duplicated!
    Version: deployment().properties.template.contentVersion  // Duplicated!
    Environment: environment  // Duplicated!
    Region: region  // Duplicated!
    ResourceName: 'Key Vault'
    'hidden-title': 'Bicep Tips and Tricks Key Vault'
  }
}

The Solution: Use union to combine base and specific configurations:

// Good: Centralized common configuration
// ** Parameters **
@description('The environment to deploy to')
param environment string = 'dev'

@description('The Azure region to deploy to')
param region string = 'UkSouth'

// ** Variables **
var coreTags = {
  BusinessUnit: 'BicepTipsAndTricks'
  Version: deployment().properties.template.contentVersion
  Environment: environment
  Region: region
}

// Create resource-specific tag combinations
var storageAccountTags = union(coreTags, {
  ResourceName: 'Storage Account'
  'hidden-title': 'Bicep Tips and Tricks Storage'
})

var keyVaultTags = union(coreTags, {
  ResourceName: 'Key Vault'
  'hidden-title': 'Bicep Tips and Tricks Key Vault'
  DataClassification: 'Confidential'  // Additional tag specific to Key Vault
})

// ** Resources **
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  name: 'mystorageaccount'
  location: region
  tags: storageAccountTags
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: 'mykeyvault'
  location: region
  tags: keyVaultTags
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: subscription().tenantId
  }
}

Key Benefits:

• Single source of truth: Common tags are defined once in coreTags
• Easy maintenance: Update business unit name? Change it in one place
• Flexible: Each resource can still have unique tags

Approach 2: Token Replacement for Complex Configurations

For complex JSON configurations that need dynamic values, token replacement provides an elegant solution. This approach is particularly powerful when working with imported JSON files that contain configuration.

The Problem: Static values embedded in complex configurations:

The Solution: Use token placeholders and replacement functions.

First, modify your JSON configuration file to use tokens:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "__schedule_time__"  // ← Token for schedule time
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1,
                    "schedule": {
                        "hours": [
                            "__schedule_hour__"  // ← Token for schedule hour
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "__interval__"  // ← Token for interval
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

Then, create a robust token replacement system in your Bicep template:

// ** Imported Types and Functions **
@description('Token Replacement Definition')
@sealed()
@export()
type TokenReplacement = {
  @description('Token to be replaced')
  token: string
  @description('Replacement value')
  replacement: string
}

@description('String Tokens Replacement Function')
@export()
func stringTokensReplacement(stringValue string, tokenReplacements TokenReplacement[]) string =>
  reduce(tokenReplacements, stringValue, (current, next) => replace(string(current), next.token, next.replacement))

// ** Parameters **
@description('The interval for the Logic App trigger')
param logicAppInterval int = 2

@description('The schedule hour for the Logic App trigger')
param scheduleHour int = 11

@description('The schedule time for condition comparison')
param scheduleTime string = '12:00:00'

@description('The environment for deployment')
param environment string = 'dev'

// ** Variables **
var logicAppConsumptionWorkflow = loadJsonContent('./logicAppConsumptionWorkflow.json')

// Define all token replacements in one place
var tokenReplacements = [
  {
    token: '__interval__'
    replacement: string(logicAppInterval)
  }
  {
    token: '__schedule_hour__'
    replacement: string(scheduleHour)
  }
  {
    token: '__schedule_time__'
    replacement: scheduleTime
  }
]

// Apply all token replacements
var processedWorkflowDefinition = json(stringTokensReplacement(
  string(logicAppConsumptionWorkflow),
  tokenReplacements
))

// ** Resources **
resource logicApp 'Microsoft.Logic/workflows@2023-12-01' = {
  name: 'my-dynamic-logic-app-${environment}'
  location: resourceGroup().location
  properties: {
    definition: processedWorkflowDefinition.definition
    parameters: processedWorkflowDefinition.parameters
  }
}

Key Benefits:

• Environment-specific values: Different intervals for dev/test/prod
• Centralized configuration: All replacements defined in one place
• Scalable: Easy to add new tokens as requirements grow
• Version control friendly: JSON templates remain clean and readable

Summary

Transforming static configuration into dynamic, reusable patterns is essential for maintainable Infrastructure as Code. Use the union() function when combining common configuration with resource-specific properties (like tags), and token replacement for complex JSON configurations that need dynamic values injected. Both approaches centralize configuration management, reduce duplication, and make your Bicep templates more maintainable across environments. The next time you find yourself copy-pasting configuration, choose the right pattern and eliminate that technical debt!

In late May this year, an exciting but semi overlooked feature was released, and I absolutely love it - Typed Variables!

Prior to this release, variable types were inferred through the value, which is fine for most statically defined content within a template, but there are cases that I will go through in this post where typing your variables really does make a big difference.

Why Use Typed Variables

Before I get going, let me walk through why you should consider using typed variables:

1. Fail-Fast Error Detection: Typed variables enable the Bicep compiler to validate assigned values against declared types during authoring and compilation. This helps catch mistakes early, reducing deployment failures.
2. Clearer Intent: Declaring types communicates your intent directly in the code, making it obvious how each variable should be used and what kind of data it should hold.
3. Enhanced IntelliSense Support: Editors like Visual Studio Code offer richer autocompletion and validation for typed variables, speeding up development and reducing errors.
4. Safer Refactoring: When you change variable values or types, the compiler immediately flags mismatches, making refactoring safer and more predictable.

Setup

Defining a typed variable is as simple as the following:

var <variable-name> <data-type> = <variable-value>

⚠️ Note: Requires Bicep version 0.36.X or later.

Typed variables support both the standard set of base data types - string, int, bool, object, array - or for the more advanced, User-defined data types and Resource-derived types.

My Top Two Use Cases

1. Clear Intent

The first major use case for typed variables is improving code clarity and maintainability, especially when working with functions that return complex objects. Without type declarations, it can be difficult to understand what a function returns or how to properly use the resulting variable.

Consider this example with a custom function:

Un-Typed Variable

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) object => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Un-typed - No IntelliSense on variable use or expectation of variable type.
var variable = myFunction('example', 42)

In this un-typed scenario, several issues arise:

• Unclear return type: The function returns a generic object, making it unclear what properties are available
• No IntelliSense support: When using variable., your editor can’t help you with autocompletion
• Hidden intent: Other developers (or future you) must examine the function implementation to understand what it returns
• Error-prone usage: Typos in property names won’t be caught until deployment time

Now let’s see how typed variables solve these problems:

Typed Variable

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for myFunction output.')
type myFunctionOutputType = {
  @description('The first property of the output.')
  property1: string
  @description('The second property of the output.')
  property2: int
}

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) myFunctionOutputType => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Typed - Includes IntelliSense, code clarity, and refactor safety on variable use.
var typedVariable myFunctionOutputType = myFunction('example', 42)

The typed approach delivers immediate improvements:

• Crystal clear intent: The type definition explicitly documents what the function returns and what each property represents
• Enhanced developer experience: Full IntelliSense support when working with the variable, including property names and descriptions
• Compile-time safety: Any mismatch between the function’s actual return value and the declared type will be caught during authoring and compilation
• Better maintainability: Changes to the function’s return structure must be reflected in the type definition, ensuring consistency across the codebase
• Team collaboration: New team members can quickly understand the data structure without diving into function implementations

This pattern is especially valuable in larger Bicep templates where functions might be defined in one section and used much later in the file, or using imported functions as discussed earlier in the series.

2. File functions

One of the most powerful applications of typed variables is when working with Bicep’s file functions such as loadJsonContent() and loadYamlContent(). Without typed variables, these functions return as an Any object, providing no compile-time validation for the loaded content.

Let’s look at a practical example where we’re loading configuration data from an external JSON file:

JSON config file

{
	"sku": {
		"name": "Standard",
		"tier": "Standard"
	},
	"kind": "StorageV2",
	"properties": {
		"supportsHttpsTrafficOnly": true
	}
}

Un-Typed Variable

// ** Variables **
// ***************

var resourceConfig = loadJsonContent('./Config/resource.config.json')

With the un-typed approach above, resourceConfig is treated as a generic object. This means:

• No compile-time validation of the JSON structure
• No documentation about what the configuration should contain

Now let’s see how typed variables transform this experience:

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for importing a JSON File resource with SKU, kind, and properties.')
type resourceImportType = {
  @description('The SKU details for the resource.')
  sku: {
    @description('The name of the SKU.')
    name: string
    @description('The tier of the SKU (e.g., Standard, Premium).')
    tier: string
  }
  @description('The kind of the resource.')
  kind: string
  @description('The properties of the resource.')
  properties: {
    @description('Indicates whether only HTTPS traffic is supported.')
    supportsHttpsTrafficOnly: bool
  }
}

// ** Variables **
// ***************

var typedResourceConfig resourceImportType = loadJsonContent('./Config/resource.config.json')

With the typed variable approach, we gain several significant benefits:

• Compile-time validation: If the JSON file doesn’t match the defined structure, Bicep will catch this during authoring and compilation
• Rich IntelliSense: When you type typedResourceConfig., your editor will show you the available properties with their descriptions
• Self-documenting code: The type definition serves as living documentation of the expected configuration structure
• Refactoring safety: If you change the type definition, all usages will be validated automatically

This approach is particularly valuable when working with complex configuration files or when multiple team members need to understand the expected data structure.

Summary

Typed variables are a game changer for Bicep development, offering compile-time validation, enhanced IntelliSense, and self-documenting code that makes your templates more robust and maintainable. Make sure to give them a try, and happy Bicep-ing!

In Bicep templates, we sometimes encounter scenarios where certain parameters should be mandatory based on the value of another parameter. For example, when deploying to production environments, you might require additional configuration parameters that are optional for development environments.

One of the common ways in which I have seen this handled is through documentation, which can lead to deployment failures and inconsistent configurations across environments. This post explores how to implement fail-fast validation using Bicep’s built-in capabilities to enforce these conditional requirements at deployment time.

Example of a Documentation-Only Approach

Handling conditional parameter requirements through documentation alone:

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('Resource configuration - REQUIRED for prod environment!')
param resourceConfig string = ''

// Additional parameters that should be required in prod
@description('Monitoring configuration - REQUIRED for prod environment!')
param monitoringConfig object = {}

@description('Backup configuration - REQUIRED for prod environment!')
param backupRetentionDays int = 0

Problems with this approach:

• No enforcement at deployment time
• Deployments can succeed with missing critical configuration
• Relies on human memory and documentation
• Inconsistent environments due to missing parameters
• Production issues from misconfiguration

Recommended Approach: Fail-Fast Validation

I would recommend using the Bicep fail() function combined with conditional logic to validate parameters early in the deployment process. This approach provides immediate feedback and prevents deployments with invalid configurations, such as in the following examples:

• Production environments - Storage deployments requiring backup retention settings for production
• Key Vault requiring network access rules when public access is disabled

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('''Resource Configuration:
                - **Optional** When environment is dev / test.
                - **Required** When environment is prod.''')
param resourceConfig string = ''

@description('Resource Configuration Validation Result')
var resourceConfig_Result = environment == 'prod' && empty(resourceConfig)
  ? fail('resourceConfig is required to deploy this template in the prod Environment.')
  : {
      value: resourceConfig
      valueProvided: !empty(resourceConfig)
    }

⚠️ Note: Make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue.

Why this approach is useful

• Enforces deployment rules: Prevents deployment in “prod” if critical configuration is missing, ensuring required configuration is provided before any resources are created.
• Fail-fast validation: Catches configuration errors at the start of deployment, saving time and preventing partial deployments.
• Conditional resource creation: You can use the valueProvided property to conditionally deploy resources or set properties only when configuration is supplied.
• Parameter validation: Centralizes validation logic, making it easier to maintain and extend checks for other environments or parameters in the future.
• Compliance requirements: Ensures production environments always meet security and operational standards.

Summary

Conditional mandatory parameters in Bicep templates are a powerful way to enforce deployment standards and prevent configuration errors. Remember to make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue. Hope this helps, and happy Bicep-ing!

This week is a simple one, but works wonders in maintainability and consistency.

There are often cases where you will need to define static values that don’t change frequently, if at all, and more importantly, you seem to be setting these up frequently for multiple templates. Here are some examples that I have seen:

1. Multi-Environment Deployments

   Different environments (dev, staging, prod) that share common configuration but need environment-specific values:

   var environmentConfig = {
     dev: {
       sku: 'Basic'
     }
     staging: {
       sku: 'Standard'
     }
     prod: {
       sku: 'Premium'
     }
   }
   

2. Organisational Standards

   When you need to enforce company-wide conventions and policies.

   var mandatoryTags = {
     costCenter: 'IT-001'
     dataClassification: 'internal'
     businessUnit: 'engineering'
     version: deployment().properties.template.contentVersion
   }
   

3. Object or Resource Configurations

   When you have configurations that would be repeated across multiple templates.

   var subnetConfigurations = [
     {
       name: 'web-subnet'
       addressPrefix: '10.0.1.0/24'
       serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
     }
     {
       name: 'api-subnet'
       addressPrefix: '10.0.2.0/24'
       serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
     }
   ]
   
   // OR
   
   var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'
   

You might think, “Hey, the values don’t change very often, so what’s the big deal? So what if I set them up many times across my templates?” Not to be a pessimist, but it’s usually at this point that Murphy’s Law comes into effect and the values will need to change! Would you not rather there be a single point where you can update these values and they ripple through your templates like a stone hitting water?

Well, you can. Simply put, Shared Variables.

Recommended Approach

My recommended approach is to leverage Bicep Imports. Create a Common folder within your IaC directory, and then a variables.bicep file within:

IaC
  ↳ Common
    ↳ variables.bicep
  ↳ main.bicep

This will form the basis of your shared variables that can be used across your deployment templates.

Then find all the relevant candidates and move these across to the shared variables template. Include the @export() decorator to each variable; this is used to allow the variable to be imported into other Bicep files.

For Example

/**********************************
  Bicep Template: Shared Variables
  Author: Andrew Wilson
***********************************/

@export()
@description('Shared Variable for environment configurations')
var environmentConfig = {
  dev: {
    sku: 'Basic'
  }
  staging: {
    sku: 'Standard'
  }
  prod: {
    sku: 'Premium'
  }
}

@export()
@description('Shared Variable for tagging resources')
var mandatoryTags = {
  costCenter: 'IT-001'
  dataClassification: 'internal'
  businessUnit: 'engineering'
  version: deployment().properties.template.contentVersion
}

@export()
@description('Shared Variable for resource configuration')
var subnetConfigurations = [
  {
    name: 'web-subnet'
    addressPrefix: '10.0.1.0/24'
    serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
  }
  {
    name: 'api-subnet'
    addressPrefix: '10.0.2.0/24'
    serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
  }
]

@export()
@description('Shared Variable for Key Vault Secrets User Role Definition ID')
var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'

These can then be used in your deployment templates as follows:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { keyVaultSecretsUserRoleDefId } from './Common/variables.bicep'

// ** Parameters **
// ****************

...

// ** Variables **
// ***************

...

// ** Resources **
// ***************

resource roleassignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(logicAppName, keyVaultSecretsUserRoleDefId)
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', keyVaultSecretsUserRoleDefId)
    ...
  }
}

Best Practices for Using Shared Variables

1. Keep it Simple: Only share variables that are common and stable.
2. Tight Control: Treat shared variables as critical infrastructure code.
3. Documentation: Clearly document and describe what each variable represents or is used for.
4. Selective Imports: Don’t import everything with *; be selective about what needs to be imported into deployment templates.

When NOT to Use Shared Variables

• For values that change frequently or are deployment-specific
• For simple, one-off configurations
• For sensitive values (use parameters or Key Vault references instead)

Summary

Shared variables help eliminate duplication and improve consistency across your Bicep templates. This simple approach gives you a single point of truth for common configurations, making updates easier and reducing the risk of inconsistencies across environments. Hope this helps, and happy Bicep-ing!

One of my bugbears is seeing either a complete lack of naming conventions or manual naming mechanisms that introduce human error through mistakes and misunderstandings. Naming conventions are incredibly important, but equally critical is how they’re implemented and maintained. Let’s explore a better approach.

What is a Naming Convention and Why Do We Need One?

A naming convention is a set of rules for naming Resource Groups and Resources (among other Azure components). These rules define the structure and composition of names, ensuring clarity, consistency, and compliance with Azure naming requirements such as length limits, valid characters, and scope uniqueness.

Common components that make up resource names include:

• Location
• Environment
• Project Prefix
• Resource Abbreviation

Naming conventions aren’t one-size-fits-all and require tailoring to your specific needs. Any changes should be considered across all systems to maintain a single source of truth. Well-defined naming conventions significantly improve the readability and maintainability of your Azure estate, aligning with best practices outlined in the Cloud Adoption Framework.

Example convention: {Resource Type}-{Project}-{Environment}-{Location}
Result: LogicAppName: logic-btt-dev-ukwest

Anti-patterns to Avoid

Hard-coded resource names:

name: 'MyLogicApp'

Issues: Poor maintainability, readability, consistency, and convention adherence

Hard-coded naming variables:

var lgName = 'MyLogicApp'

Issues: Poor maintainability across templates, inconsistency, and no convention

Hard-coded naming convention:

var lgName = 'logic-${project}-${environment}-${location}'

Issues: Poor maintainability across templates, template inconsistency, and scattered convention logic

Recommended Approach

My recommended approach leverages User-defined functions to provide consistent and maintainable naming conventions. Combined with Bicep Imports, this ensures consistency across all templates.

For enhanced maintainability, I also recommend implementing centralized core parameters with types and constructors. This approach significantly reduces the number of function parameters needed for each naming operation.

Implementation Structure

Create a Common folder within your IaC directory:

IaC
  ↳ Common
    ↳ types.bicep
    ↳ nameConventionFunctions.bicep
  ↳ main.bicep

• types.bicep - Contains core parameter user-defined types and constructor functions
• nameConventionFunctions.bicep - Contains naming convention functions

Core Types Setup

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Location Short Name for resource naming')
  locationShortName: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  locationShortName string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  locationShortName: locationShortName
  environment: environment
  projectPrefix: projectPrefix
}

Naming Convention Functions

I’ve structured my naming conventions using these key parameters:

• Resource Abbreviation - Identifies the resource type (Azure abbreviations reference)
• Project Prefix - Identifies the project
• Environment - Identifies the deployment environment
• Location - Identifies the deployment location (optional for global resources)
• Context - Describes the resource’s purpose (optional)

The following functions cover some common naming scenarios:

/*******************************************
  Bicep Template: Name Constructor Functions
  Author: Andrew Wilson
*******************************************/

// ** Shared Imports **
// ********************

import { coreParams } from './types.bicep'

// Resource Name Constructors
//***************************

// Basic
@export()
@description('Generates a resource name based on the provided parameters (used for common usage resources)')
func basicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a resource name based on the provided parameters but ignoring the location (used for common usage resources that are not location specific)')
func unlocalisedBasicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}'

// Context Specific
@export()
@description('Generates a Context Specific Resource Name based on the provided parameters')
func csResource(resourceAbbreviation string, coreParameters coreParams, contextName string) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

// Resource Group
@export()
@description('Generates a Resource Group name based on the provided parameters')
func resourceGroup(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a Resource Group name based on the provided parameters but without an env specified')
func resourceGroupNonEnvSpecific(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.location}-shared'

// Storage Account
@export()
@description('Generates a Storage Account Resource Name based on the provided parameters')
func storageAccountResource(coreParameters coreParams, contextName string?) string =>
  empty(contextName)
    ? 'st${coreParameters.projectPrefix}${coreParameters.environment}${coreParameters.locationShortName}'
    : 'st${coreParameters.projectPrefix}${contextName}${coreParameters.environment}${coreParameters.locationShortName}'

Usage Example

Here’s how to use these functions in your main deployment template:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'
import * as newName from './Common/nameConventionFunctions.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string

@description('Location Short Name for resource naming')
param locationShortName string

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myproject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, locationShortName, environment, projectPrefix)

// Standard Logic App Resource Names
var logicAppName = newName.basicResource('logic', coreParameters)
var appServicePlanName = newName.csResource('asp', coreParameters, 'lg')
var storageAccountName = newName.storageAccountResource(coreParameters, 'lg')

// ** Resources **
// ***************

...

Generated Names:

• Logic App: logic-myproject-dev-ukwest
• App Service Plan: asp-myproject-lg-dev-ukwest
• Storage Account: stmyprojectlgdevukw

Summary

Implementing a robust naming convention is crucial for Azure resource management, but the mechanism matters just as much as the convention itself. By using Bicep user-defined functions combined with centralized core parameters, you can:

• Eliminate human error from manual naming processes
• Ensure consistency across all templates and environments
• Improve maintainability with centralized naming logic
• Enhance readability of your Infrastructure as Code
• Align with best practices from the Cloud Adoption Framework

This approach transforms naming from a scattered, error-prone process into a centralized, reliable system that scales with your infrastructure needs. The initial setup investment pays dividends in reduced maintenance overhead and improved deployment reliability. Happy Bicep-ing!

When building IaC templates we strive to enable them to be environment agnostic, configurable even. One of the mechanisms that we do this is through lots of “Core Parameters” that disseminate the fundamental details of our deployment and resources. The number of core parameters is often variable but the verdict is always true, three or more usually does the trick. These Core Parameters are passed into the main deployment template and any other sub deployment template (Module) too. These may include but are not limited to:

• Environment
• Location/Region
• Project/Application Prefix

But why am I going on about this, why is it a problem. Well it’s not a problem as much as it’s a readability and maintainability issue. Think about it, every template now requires three or more core parameters defined, with every module call having to define them as parameters to be passed in. Following this, if there is a change, the change will need to occur everywhere, and let’s hope that the descriptions/metadata has been kept up to date too!

My recommendation to resolve this issue involves three Bicep concepts:

1. User-defined data types
2. User-defined functions
3. Imports

Recommendation broken down

1. Define our source of truth Core Parameters | User-defined data type

User-defined data types provide us a way to define our own data object containing all the core parameters that we use throughout such as the following:

// Bicep

@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

The decorator @sealed() means that you are only permitting the use of properties specifically included in the type definition. This helps with making sure there is only one single source of truth for the coreParams definition.

The type definition means that we can pass through a single parameter to our deployment templates, and manage change in a single place.

2. Create a Constructor to setup our Core Parameters | User-defined function

To aid in the initialization of the coreParams type, I typically create a user-defined function (Constructor) which sets up the initial state by assigning values to the respective properties. This ensures the Core Params object starts in a valid, predictable state. The function would look like this:

// Bicep

@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

3. Promote Shared Use of the Type and Constructor | Imports

The user defined type and function alone would not make this an effective recommendation due to the duplication of both the type and function definition on all templates. However, due to the recent introduction of exports and imports, we can continue on the path of a single and reusable single source of truth.

To make this work, what I would suggest is to create a new folder in your IaC location called Common, in this folder create a new bicep file called types.bicep. This is the shared bicep file that we are going to use for our new type and constructor.

An example of this setup is as follows:

• IaC → Common → types.bicep

Shared Types Template

// Bicep

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

The @export() decorator is used to allow the type and function to be imported into other Bicep files.

Now we can use the import syntax in our main and sub deployment (module) templates, allowing use of the single defined type and function. In the main template we import the constructor and assign the initialized object to our coreParameters variable. For our sub deployment (module) templates we import the coreParams type so we can use it as a parameter definition. Both combined allow simplified module reference definitions and assignments. This can be seen in the following example templates:

Main Deployment Template

// Bicep

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string = resourceGroup().location

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myProject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, environment, projectPrefix)

// ** Resources **
// ***************

@description('Demonstration of the core parameters being passed to a submodule')
module subDeploy './subDeploy.bicep' = {
  name: 'subDeploy'
  params: {
    coreParameters: coreParameters
  }
}

Sub Deployment (Module) Template

// Bicep

/***************************************
Bicep Template: Resources Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { coreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Core Parameters for the deployment')
param coreParameters coreParams

// ** Variables **
// ****************

@description('The name of the resource to deploy')
var resourceName = '${coreParameters.projectPrefix}-${coreParameters.environment}-resource'

Summary

Managing core parameters in Bicep templates can quickly become unwieldy as your infrastructure grows. By leveraging user-defined types, constructors, and imports, you can centralize your parameter definitions, improve readability, and simplify maintenance. This approach ensures consistency across your deployments and makes future changes easier to manage. Happy Bicep-ing!

For those who know me well, starting a bicep tips and tricks series would not be a surprise to them. The moment the Bicep language was introduced, I knew I would be completely obsessed. I love writing bicep templates and even more the clever refinement to make them reusable, configurable, manageable, readable… I really enjoy sharing my experiences with Bicep, so here it begins on the wider front. From one Bicep nerd to another, I hope you find these tips useful, happy templating!

Why is versioning important

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

• Why apply a version to your templates?

  Applying versioning to templates ensures you can track changes, maintain consistency, and know exactly which version of your infrastructure code was used for any deployment. It supports best practices like binary promotion, simplifies troubleshooting, and helps teams coordinate updates and rollbacks with confidence.

• Why apply the version as a tag to Azure Resources?

  Tagging Azure resources with the template version gives you direct visibility into what was deployed, right from the Azure portal or API. This makes audits, governance, and troubleshooting much easier, as you can instantly see which template version created or updated a resource. It also helps correlate infrastructure changes with application releases and supports compliance requirements for traceability.

ARM templates have a Json property right at the top of the file underneath $schema called contentVersion. By default and if never changed, this will always be 1.0.0.0. As part of our versioning practice we can make sure that the templates that we deploy make use of the same version that is applied to other built artifacts. This allows us to track deployments and their respective templates through versions.

How to version templates using Azure DevOps

As part of a YAML CI/CD pipeline I typically have a build stage, with a inner Test and Version ARM Templates Job. The focus of the job is to do two things:

1. Using the az cli - Build the Bicep templates
   • I also include the Bicep linting file, this means that as the templates are being transpiled into ARM I am also getting any build errors and warnings. I output these as logissues to the Azure DevOps Pipeline for visibility.
2. Version the built ARM JSON artifacts to support Binary promotion and align with versioning practices.

I use the following tasks to complete the tasks:

1. AzureCLI@2 - used to build the Bicep templates (transpile into ARM) and log any warnings or errors.
2. VersionJSONFile@3 - used to version stamp the ARM templates.
3. CopyFiles@2 - Used to copy the versioned ARM artifacts to the staging directory.
4. PublishPipelineArtifact@1 - used to publish the ARM artifacts to the pipeline so they can be downloaded in future deployment stages.

Here is a sample YAML template:

# Yaml

...

- task: AzureCLI@2
  displayName: 'Build Bicep Files'
  inputs:
    azureSubscription: 'xxyyzz'
    scriptType: 'ps'
    scriptLocation: 'inlineScript'
    useGlobalConfig: true
    powershellerrorActionPreference: 'continue'
    inlineScript: |
      # create folder if it doesn't exist
      if (!(Test-Path -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput)) {
        New-Item -ItemType Directory -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput
      }
      write-host "Build the Bicep file"
      $output = az bicep build --file $(Build.SourcesDirectory)\{YourPath}\IAC\template.azuredeploy.bicep --outdir $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput 2>&1      
  
      write-host "Process the output"
      $output | foreach-object {
         if ($_ -match 'Error') {
            Write-Host "##vso[task.logissue type=error]$_"
         } 
         if ($_ -match 'Warning') {
             Write-Host "##vso[task.logissue type=warning]$_"
         }
      }

- task: VersionJSONFile@3
  displayName: 'Version stamp ARM templates'
  inputs:
    Path: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    recursion: True
    VersionNumber: $(Build.BuildNumber) # an example versioning option but can also be options like gitversion
    useBuildNumberDirectly: False
    VersionRegex: \d+\.\d+\.\d+\.\d+
    versionForJSONFileFormat: '{1}.{2}.{3}.{4}'
    FilenamePattern: '\w+.json'
    Field: 'contentVersion' # Versioning is applied to the templates contentVersion field
    OutputVersion: OutputedVersion

- task: CopyFiles@2
  displayName: 'Copy ARMOutput to Artifact Staging Directory'
  inputs:
    SourceFolder: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    Contents: '**/*.json'
    TargetFolder: '$(Build.ArtifactStagingDirectory)/templates'
    flattenFolders: true

- task: PublishPipelineArtifact@1
  displayName: 'Publish ARMOutput as template build artifact'
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)/templates'
    publishLocation: 'pipeline'
    artifactName: 'ARMtemplates'

This setup ensures your ARM templates are built, versioned, and published as pipeline artifacts in a repeatable, traceable way. By stamping each template with a version number and making it available as an artifact, you enable binary promotion through environments and make it easy to track exactly which template version was used for each deployment. This improves auditability, supports rollback scenarios, and aligns with best practices for infrastructure as code in CI/CD pipelines.

How to apply the template version as a tag to Azure Resources

Versioning our ARM templates is one part of the transparency and traceability. But it would also be nice to be able to see which template version deployed the Azure Resources from the Azure Resources themselves. We can do this by applying a tag onto our resources and tying it back to our ARM contentVersion property field. We can do this by using the deployment() function as such deployment().properties.template.contentVersion.

On a resource it would look like the following:

// Bicep

resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
	...
    version: deployment().properties.template.contentVersion
  }
  ...
}

Applying template versioning and tagging resources with the deployed template’s version brings transparency and traceability to your Azure infrastructure. You’ll always know which version of your code and templates are running in each environment, making troubleshooting and governance much easier. These small practices help teams stay organised, reduce deployment risks, and build confidence in their automation. Happy Bicep-ing!

The Bicep existing keyword is a powerful capability that allows us to reference a resource that wasn’t deployed as part of the current Bicep file.

One of the typical use cases that I often see is where a resource is deployed as part of a module called by the parent template, the resource that was deployed as part of the module is then required later in the parent template and therefore an existing resource definition is used. As part of the template configuration there would be an explicit dependency between the existing resource definition and the module reference.

An example diagram of this is shown below:

For Bicep v0.34.1 and lower, there are two scenarios that can be observed when deploying the templates:

• Scenario 1: Successful deployment. The existing resource has been found and the explicit dependency between Existing Resource and Module Ref 1 has been honoured.
• Scenario 2: Deployment Failure. The Resource XYZ under resource group 'XXYYZZ' was not found.. The existing resource has not been found and the explicit dependency between Existing Resource and Module Ref 1 has not been honoured.

For most that fall into scenario 2, without much explanation of what may be going on behind the scenes, their typical solution to this particular problem may be to force the dependency chaining by extracting further of the parent template into a further module.

An example of this can be seen below:

Yes this is a valid solution, but why is there a problem in the first place?

Explanation

It all comes down to whether your template is compiled with symbolic name code generation.

Symbolic Name Code Generation allows the ARM template layer to use a new schema to represent resources as an object dictionary rather than an array of objects. This feature improves the semantic equivalence of the Bicep and ARM templates, resulting in more reliable code generation.

In a symbolic name template, an existing resource can depend on other resources or modules, and this will cause the backend to delay reading the resource until those dependencies are completed. This allows you to deploy a resource in a module, then refer to it with an existing declaration in the module parent. In non-symbolic name templates, existing resources are compiled to reference(resourceId()) expressions and are all handled in the first wave of deployment jobs.

In a non-symbolic name compiled template the existing reference looks like this:

reference(resourceId('Microsoft.xxx/yyy', parameters('resourceName'))), '2023-05-01', 'full')

In a symbolic name compiled template the existing reference and dependencies look like this:

reference('existingResource', '2023-05-01', 'full')

"dependsOn": [
  "existingResource",
  "ModuleRef1"
]

This explains why in some template deployment cases the deployment succeeds and in others it fails (the template is not setup for symbolic name code generation). But how do you enable symbolic name code generation?

Solution

Symbolic name code generation is part of the languageVersion 2.0 functionality and can be enabled automatically by using any of the following Bicep Features:

• user-defined types
• user-defined functions
• compile-time imports
• experimental features

For most of you up until this point like me, you will have unintentionally and thankfully enabled symbolic name code generation by using features as described above and therefore not suffered from the problem case as described.

Symbolic name code generation can also be explicitly enabled by adding the following to your bicepconfig.json:

	"experimentalFeaturesEnabled": {
		"symbolicNameCodegen": true
	 }

Or the preferred option use Bicep v0.34.44 or higher where languageVersion2.0 is used automatically when an existing resource has an explicit DependsOn dependency stipulated.

If you are unsure as to whether your templates are compiled using symbolic name code generation, have a look at the first few lines of your compiled Bicep template. The ARM template should specify languageVersion 2.0 if enabled and missing this line if not.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",

Hope this helps and have fun.

Prior to the Christmas break I was involved in writing some integrations that used a mixture of Logic Apps Standard and Function Apps. It was agreed as part of the architecture that user-assigned identities would be the best fit. As part of the implementation, I observed that the differences in configuration setup between system-assigned and user-assigned wasn’t widely understood. This article aims to show a brief run through of both.

Setup and Difference with System-Assigned

System-Assigned

The general process when using a System-Assigned identity is as follows:

1. Create a Key Vault Instance.

2. Create secrets required by the application.

3. Create the app resource (Logic App / Function App)

   • As part of the configuration, specify the identity as System Assigned.

   • Reference the key vault secret(s) in your App Settings.

4. Authorise the applications identity read access to key vault or specifically the key vaults secret.

The main points with System-Assigned setup is:

• The identity is tied to the created app resource and its life-cycle
• The resource cannot reference key vault secrets at the point of creation
  • Authorisation to read the key vault secrets has not occurred at this point
• The identity cannot be associated with other resources

User-Assigned

The general process when using a User-Assigned identity is as follows:

1. Create a Key Vault instance

2. Create secrets required by the application(s)

3. Create the user-assigned identity

4. Authorise the user-assigned identity read access to key vault or specifically the key vaults secret.

5. Create the app resource (Logic App / Function App)

   As part of the resource configuration

   • Specify the identity as user-assigned and reference the created identity in step 3

   • Specify the identity to be used for key vault reference operations by setting the keyVaultReferenceIdentity property to the resource ID of the user-assigned identity

   • Reference the key vault secret(s) in your App Settings.

The main points with User-Assigned setup is:

• The identity is managed outside the context of a resource and its life-cycle
• A resource that uses the identity can read secrets from keyvault at the point of creation
  • Given that the authorisation has occurred prior to the resource creation.
• The identity can be associated with on or more resources

⚠️ Note One of the most common gotchas [user-assigned] is missing or forgetting to specify the identity to be used for key vault reference operations (keyVaultReferenceIdentity property - Step 5).

Hope this helps and have fun.

Overview

The recent work that I have been doing with Standard Logic Apps and linking them as backends to Azure API Management has relied on the use of the Logic App Workflow SAS key for security. This is a valid authentication approach, but there are risks that you need to be aware of as well as best practices that you need to be abiding by. Such as:

• Some Potential Risks:

  • If a SAS is leaked, it can be used by anyone who obtains it to call your Logic App Workflow.
  • If a SAS expires and the API Management API has not been updated to make use of the updated SAS, then the integration functionality will be hindered.

• Some SAS Best Practices to mitigate risks:

  • Always use HTTPS - If a SAS is passed over HTTP and intercepted, an attacker can perform a man-in-the-middle attack and read the SAS.
  • Have a revocation plan - Make sure that you are prepared to respond if a SAS is compromised.
  • Have a rotation plan - Look to replace the SAS with new ones at regular intervals and include shorter time intervals for the expiration period.

There are other features that can be used to further restrict access to your Logic App, for instance adding IP Address Restrictions to limit traffic to only your API Management Instance.

But what if you require further governance whereby the Logic App requires a valid Entra ID bearer token in order to be invoked. To implement this we are going to make use of Easy Auth.

Easy Auth

Easy Auth is a built-in authentication and authorisation capability provided by Azure App Services and Azure Functions. Easy Auth makes use of federated identity whereby a third-party identity provider manages the user identities and authentication flow for you. Fortunately for us, Standard Logic Apps have the same foundations as Azure Functions and therefore Easy Auth is also extended to Logic Apps Standard.

Easy Auth is a platform feature running on the same virtual machine as your application. Once enabled, any incoming HTTP requests will pass through this feature prior to being handled by your application. Easy Auth runs separately from your application code and can be configured using ARM settings or using a configuration file.

Using Easy Auth and Linking to API Management

As mentioned above, I would like to use Easy Auth to protect my HTTP Triggered Azure Logic App (Standard) workflows, but more importantly, I would like Azure API Management to be the only identity that can be used to make requests to my workflows as shown in the diagram below:

Note:

As we will be invoking the Logic App HTTP triggered workflows with Easy Auth, we no longer need to specify the following parameters in the request:

• sp: The permissions; generally ‘read’ or ‘write’
• sv: The version number of the query parameters
• sig: Shared-Access-Signature

Furthermore, I have opted for Infrastructure as Code (IaC) as my method of implementation, specifically Bicep.

For setup, we will need to conduct the following four steps:

1. Configure the Logic App to Use Microsoft Entra sign-in.

   Working through the Microsoft instructions in the link above, you will require as minimum the following when setting up the Logic App Application Registration:

   • Select the supported account type. (I’m using Current tenant - single tenant)

   • Setup a Redirect URI for your Logic App:

     Select Web for platform and set the URI to <app-url>/.auth/login/aad/callback. For example, https://contoso.azurewebsites.net/.auth/login/aad/callback.

   • Make not of the Application (client) ID.

   • Create a Client Secret and store this securely (I’m using Azure DevOps Secure Library Variables as part of a deployment).

     This is a secret value that the application uses to prove its identity when requesting a token. This value is saved in your app’s configuration as a slot-sticky application setting named MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. If the client secret isn’t set, sign-in operations from the service use the OAuth 2.0 implicit grant flow, which isn’t recommended.

   • Expose an API > Add > Save. This value uniquely identifies the application when it’s used as a resource, allowing tokens to be requested that grant access. It’s used as a prefix for scopes you create.

     I am using a single-tenant app and therefore using the default value. Appears as such api://<application-client-id>

   • Add the user_impersonation scope to your App Registration allowing Admins and users to consent.

2. Make sure that API Management has been setup with Managed Identity. I am using System Assigned.

   @description('Deployment of the APIM instance')
   resource apimInstanceDeploy 'Microsoft.ApiManagement/service@2022-08-01' = {
     ...
     identity: {
       type: 'SystemAssigned'
     }
     ...
   }
   

3. Store the App Registration Secret in KeyVault and Reference in your Logic App Settings to allow the Logic App to prove its identity.

   ...
   
   @secure()
   @description('The client secret for the Easy Auth App Registration')
   param applicationEasyAuthClientSecret string
   
   ...
   
   @description('Role Definition Id for the Key Vault Secrets User role')
   var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'
   
   ...
   
   @description('Deploy the Application Easy Auth App Registration Secret to Keyvault')
   resource vaultLogicAppRegSecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
     name: '${applicationLogicAppName}-EasyAuth-Secret'
     parent: applicationKeyVaultDeploy
     properties: {
       contentType: 'string'
       value: applicationEasyAuthClientSecret
     }
   }
   
   ...
   
   @description('Deploy the Application Standard Logic App')
   resource applicationLogicAppStandardDeploy 'Microsoft.Web/sites@2024-04-01' = {
     name: applicationLogicAppName
     location: location
     identity: {
       type: 'SystemAssigned'
     }
     ...
     resource config 'config@2024-04-01' = {
       name: 'appsettings'
       properties: {
         ...
         MICROSOFT_PROVIDER_AUTHENTICATION_SECRET: '@Microsoft.KeyVault(VaultName=${applicationKeyVaultDeploy.name};SecretName=${vaultLogicAppRegSecret.name})'
         ...
       }
     }
   }
   
   ...
   
   @description('Create the RBAC for the Logic App to Read the Secret from Key Vault')
   resource applicationLogicAppRBACWithKV 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: guid(applicationKeyVaultDeploy.id, applicationLogicAppStandardDeploy.id, keyVaultSecretsUserRoleDefId)
     scope: vaultLogicAppRegSecret
     properties: {
       principalId: applicationLogicAppStandardDeploy.identity.principalId
       roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', keyVaultSecretsUserRoleDefId)
       principalType: 'ServicePrincipal'
     }
   }
   

4. Enable Easy Auth on the Standard Logic App using ARM/Bicep Template AuthSettingsV2 or ARM REST API. I am using a Bicep Template.

   @description('Setup the Easy Auth config settings for the Standard Logic App')
   resource applicationAuthSettings 'Microsoft.Web/sites/config@2023-01-01' = {
     name: 'authsettingsV2'
     parent: applicationLogicAppStandardDeploy // Existing Standard Logic App for Easy Auth to be enabled
     properties: {
       globalValidation: {
         requireAuthentication: true
         unauthenticatedClientAction: 'AllowAnonymous' // Do not change: See note below.
       }
       httpSettings: {
         requireHttps: true
         routes: {
           apiPrefix: '/.auth'
         }
         forwardProxy: {
           convention: 'NoProxy'
         }
       }
       identityProviders: {
         azureActiveDirectory: {
           enabled: true
           registration: {
             openIdIssuer: uri('https://sts.windows.net/', tenant().tenantId)
             clientId: logicAppEasyAuthClientId
             clientSecretSettingName: 'MICROSOFT_PROVIDER_AUTHENTICATION_SECRET'
           }
           validation: {
             allowedAudiences: environment().authentication.audiences // Azure Management Plane [management.core.windows.net and management.azure.com]
             defaultAuthorizationPolicy: {
               allowedPrincipals: {
                 identities: [
                   apimInstance.identity.principalId // APIM System Assigned Principal Id
                 ]
               }
             }
           }
         }
       }
       platform: {
         enabled: true
         runtimeVersion: '~1'
       }
     }
   }
   

   Note:

   ¹EasyAuth is managed by AppService, and for an incoming request, it is a hop that comes before LA Runtime. When EasyAuth is enabled for a Logicapp standard, all incoming requests are validated against the policies in your V2 Auth settings.

   If you have “unauthenticatedClientAction”: “Return401” and when the request fails with EasyAuth, those requests are not routed to LA runtime and will fail with 401 from AppService. Therefore, you will also observe broken portal experience with Return401. When you set it to “AllowAnonymous”, all calls (failed and successful) will be routed to the LA runtime. The LA runtime will know if the request failed with EasyAuth or was successful and will process the request accordingly. For example, to get run histories, we authenticate it on SAS specific to that run generated based on the Logic Apps access keys. LA runtime will know that this request failed with EasyAuth but it will be processed successfully as it has valid SAS. The underlying AppService platform will have no knowledge of validating other auth like SAS.

5. Configure API Management to obtain a valid Bearer token and add it to the request Authorization Header. Implemented through APIM Policy.

   <!-- API ALL OPERATIONS SCOPE -->
   <policies>
       <inbound>
           <base />
           <!-- Uses System Assigned Managed Identity of the APIM Instance -->
             <authentication-managed-identity resource="https://management.azure.com/" output-token-variable-name="msi-access-token" ignore-error="false" />
             <set-header name="Authorization" exists-action="override">
    	         <value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
             </set-header>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

6. Configure API Management to Append the Logic App Workflow api-version query parameter to the request. Implemented through APIM Policy.

   <!-- API OPERATION SCOPE -->
   <policies>
       <inbound>
           <base />
           <rewrite-uri template="__uri__" />
           <set-query-parameter name="api-version" exists-action="append">
               <value>__api-version__</value>
           </set-query-parameter>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

Summary

In short, we have defined our three A’s (Access, Authentication, Authorisation) providing further governance on our Standard Logic App and API Management through the use of Easy Auth. To see my worked example, have a look at my GitHub repository along with a README that explains how to get started.

Hope this helps and have fun.

Overview

The recent work that I have been doing with Function Apps and linking them as backends to Azure API Management has relied on the use of the Function Apps Function SAS key for security. This is a valid authentication approach, but there are risks that you need to be aware of as well as best practices that you need to be abiding by. Such as:

• Some Potential Risks:

  • If a SAS is leaked, it can be used by anyone who obtains it to call your Function.
  • If a SAS expires and the API Management API has not been updated to make use of the updated SAS, then the integration functionality will be hindered.

• Some SAS Best Practices to mitigate risks:

  • Always use HTTPS - If a SAS is passed over HTTP and intercepted, an attacker can perform a man-in-the-middle attack and read the SAS.
  • Have a revocation plan - Make sure that you are prepared to respond if a SAS is compromised.
  • Have a rotation plan - Look to replace the SAS with new ones at regular intervals and include shorter time intervals for the expiration period.

But what if you require further governance whereby the Function App requires a valid Entra ID bearer token in order to be invoked. To implement this we are going to make use of Easy Auth.

Easy Auth

Easy Auth is a built-in authentication and authorisation capability provided by Azure App Services, Azure Functions, and Standard Logic Apps. Easy Auth makes use of federated identity whereby a third-party identity provider manages the user identities and authentication flow for you.

Easy Auth is a platform feature running on the same virtual machine as your application. Once enabled, any incoming HTTP requests will pass through this feature prior to being handled by your application. Easy Auth runs separately from your application code and can be configured using ARM settings or using a configuration file.

Using Easy Auth and Linking to API Management

As mentioned above, I would like to use Easy Auth to protect my HTTP triggered functions, but more importantly, I would like Azure API Management to be the only identity that can be used to make requests to my functions as shown in the diagram below:

Note:

As we will be invoking the Function App HTTP triggered Functions with Easy Auth, we no longer need to specify the following parameters or details:

• Parameter code: Shared-Access-Signature
• AuthorizationLevel: When Easy Auth is enabled, the HTTP triggered Functions no longer need to have the AuthorizationLevel set to Function but rather set to Anonymous. This is because Easy Auth will conduct the authorisation prior to reaching your code and no longer requires a SAS key to be provided of which the Function AuthorisationLevel requires.

For setup, we will need to conduct the following steps:

I have opted for Infrastructure as Code (IaC) as my method of implementation, specifically Bicep. I have also opted for Microsoft Entra as my Identity Provider.

1. Configure the Function App to Use Microsoft Entra sign-in.

   Working through the Microsoft instructions in the link above, you will require as minimum the following when setting up the Function App Application Registration:

   • Select the supported account type. (I’m using Current tenant - single tenant)

   • Setup a Redirect URI for your Function:

     Select Web for platform and set the URI to <app-url>/.auth/login/aad/callback. For example, https://contoso.azurewebsites.net/.auth/login/aad/callback.

   • Make not of the Application (client) ID.

   • Create a Client Secret and store this securely (I’m using Azure DevOps Secure Library Variables as part of a deployment).

     This is a secret value that the application uses to prove its identity when requesting a token. This value is saved in your app’s configuration as a slot-sticky application setting named MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. If the client secret isn’t set, sign-in operations from the service use the OAuth 2.0 implicit grant flow, which isn’t recommended.

   • Expose an API > Add > Save. This value uniquely identifies the application when it’s used as a resource, allowing tokens to be requested that grant access. It’s used as a prefix for scopes you create.

     I am using a single-tenant app and therefore using the default value. Appears as such api://<application-client-id>

   • Add the user_impersonation scope to your App Registration allowing Admins and users to consent.

2. Make sure that API Management has been setup with Managed Identity. I am using System Assigned.

   @description('Deployment of the APIM instance')
   resource apimInstanceDeploy 'Microsoft.ApiManagement/service@2024-05-01' = {
     ...
     identity: {
       type: 'SystemAssigned'
     }
     ...
   }
   

3. Store the App Registration Secret in KeyVault and Reference in your Function App Settings to allow the Function App to prove its identity.

   ...
   
   @secure()
   @description('The client secret for the Easy Auth App Registration')
   param applicationEasyAuthClientSecret string
   
   ...
   
   @description('Role Definition Id for the Key Vault Secrets User role')
   var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'
   
   ...
   
   @description('Deploy the Application Easy Auth App Registration Secret to Keyvault')
   resource vaultFunctionAppRegSecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
     name: '${applicationFunctionAppName}-EasyAuth-Secret'
     parent: applicationKeyVaultDeploy
     properties: {
       contentType: 'string'
       value: applicationEasyAuthClientSecret
     }
   }
   
   ...
   
   @description('Deploy the Application Function App')
   resource applicationFunctionAppDeploy 'Microsoft.Web/sites@2024-04-01' = {
     name: applicationFunctionAppName
     location: location
     identity: {
       type: 'SystemAssigned'
     }
     ...
     resource config 'config@2024-04-01' = {
       name: 'appsettings'
       properties: {
         ...
         MICROSOFT_PROVIDER_AUTHENTICATION_SECRET: '@Microsoft.KeyVault(VaultName=${applicationKeyVaultDeploy.name};SecretName=${vaultFunctionAppRegSecret.name})'
         ...
       }
     }
   }
   
   ...
   
   @description('Create the RBAC for the Function App to Read the Secret from Key Vault')
   resource applicationFunctionAppRBACWithKV 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: guid(applicationKeyVaultDeploy.id, applicationFunctionAppDeploy.id, keyVaultSecretsUserRoleDefId)
     scope: vaultFunctionAppRegSecret
     properties: {
       principalId: applicationFunctionAppDeploy.identity.principalId
       roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', keyVaultSecretsUserRoleDefId)
       principalType: 'ServicePrincipal'
     }
   }
   

4. Enable Easy Auth on the Function App using ARM/Bicep Template AuthSettingsV2.

   @description('Setup the Easy Auth config settings for the Function App')
   resource applicationAuthSettings 'Microsoft.Web/sites/config@2024-04-01' = {
     name: 'authsettingsV2'
     parent: applicationFunctionAppDeploy
     properties: {
       globalValidation: {
         requireAuthentication: true
         unauthenticatedClientAction: 'Return401'
       }
       httpSettings: {
         requireHttps: true
         routes: {
           apiPrefix: '/.auth'
         }
         forwardProxy: {
           convention: 'NoProxy'
         }
       }
       identityProviders: {
         azureActiveDirectory: {
           enabled: true
           registration: {
             openIdIssuer: uri('https://sts.windows.net/', tenant().tenantId)
             clientId: functionAppEasyAuthClientId
             clientSecretSettingName: 'MICROSOFT_PROVIDER_AUTHENTICATION_SECRET'
           }
           validation: {
             allowedAudiences: environment().authentication.audiences
             defaultAuthorizationPolicy: {
               allowedPrincipals: {
                 identities: [
                   apimInstance.identity.principalId
                 ]
               }
             }
           }
         }
       }
       platform: {
         enabled: true
         runtimeVersion: '~1'
       }
     }
   }
   

   Note:

   EasyAuth is managed by the AppService, and for an incoming request, it is a hop that comes before FA Runtime. When EasyAuth is enabled for a Function App, all incoming requests are validated against the policies in your V2 Auth settings.

5. Configure API Management to obtain a valid Bearer token and add it to the request Authorization Header. Implemented through APIM Policy.

   <!-- API ALL OPERATIONS SCOPE -->
   <policies>
       <inbound>
           <base />
           <!-- Uses System Assigned Managed Identity of the APIM Instance -->
             <authentication-managed-identity resource="https://management.azure.com/" output-token-variable-name="msi-access-token" ignore-error="false" />
             <set-header name="Authorization" exists-action="override">
    	         <value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
             </set-header>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

Summary

In short, we have applied further governance on our Function App and API Management through the use of Easy Auth. To see my worked example, have a look at my GitHub repository along with a README that explains how to get started.

Hope this helps and have fun.

There have been few times where I have landed into this particular predicament whereby either by my own doing or through the use of another’s code base, a deep nested or thoroughly utilised (parameter/variable/or other defined item) has been created with the same name as a Bicep function. As by Murphy’s law, its only once you have reached this point of no return that you realise that your items name conflicts.

Now if you are like many in your unawares, your thoughts and actions will conclude to a singular one of ’that sucks… followed by a nasty refactor'.

Solution - Namespaces

Namespaces are a declarative scope in which identifiers such as the names of types, functions, and variables can be declared. These namespaces are used to organise code into logical groups and to prevent name collisions such as the one you are currently experiencing.

Thankfully, in Bicep there are two namespaces where all functions are split, az and sys.

• az | Contains functions that are specific to an Azure deployment such as:
  • deployment
  • environment
  • resourceGroup
  • subscription
• sys | Contains functions that are used to construct values, and decorators for parameters and resource loops. This includes but is not limited to:
  • [Array] concat
  • [File] loadJsonContent
  • [Lambda] filter
  • [Logical] bool
  • [Numeric] int
  • [String] contains

To make use of these namespaces, simply add the namespace identifier in front of the function. The example below shows a real world example of this issue where a parameter name ‘environment’ has been extensively utilised in this template and many others. This particular template is being used to deploy an AuthProvider in API Management, and the author wishes to utilise the environment function for the authentication.loginEndpoint. Without the use of the az namespace, the environment parameter would need to be refactored both in this template and wider templates for consistency.

/******************************************
Bicep Template: Function Namespace Example
Author: Andrew Wilson
******************************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('The environment to deploy the resources to.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string = 'dev'

...

// ** Variables **
// ***************

var ApiManagementName = toLower('apim-${projectName}-${environment}-${location}')

// ** Resources **
// ***************

...

// Create a new Auth Provider in APIM Credential Manager
resource AuthorizationProvider 'Microsoft.ApiManagement/service/authorizationProviders@2023-05-01-preview' = {
  ...
  properties: {
    ...
    oauth2: {
      ...
      grantTypes: {
        clientCredentials: {
          loginUri: az.environment().authentication.loginEndpoint
        }
      }
    }
  }
}

As always, have a play, and hope this helps.

I have recently been adding email alerting to some Logic App Standard workflows as part of the error handling flow. In doing so I made use of an existing Office 365 Outlook Connector in the Azure Subscription; the connector is not built in for Standard Logic Apps but is rather part of the Managed Api Connections.

Managed Api Connectors require more than just the connection details to be detailed in the Logic Apps connections.json configuration as shown below:

{
  "managedApiConnections": {
    "office365": {
      "api": {
        "id": "@appsetting('office365_apiId')"
      },
      "authentication": {
        "type": "ManagedServiceIdentity"
      },
      "connection": {
        "id": "@appsetting('office365_connectionId')"
      },
      "connectionRuntimeUrl": "@appsetting('office365_connectionRuntimeUrl')"
    }
  }
}

The Managed API Connector also requires that the Logic App has been granted access to the Connector through the use of Access Policies. This can be configured through the Azure Portal or through infrastructure deployments, in my case I have opted for infrastructure deployments with the use of Bicep templates.

It was at this point that I realised that the Access Policy resource which is a child resource to Microsoft.Web/connections has not been documented, obtainable through an Azure Portal template export, or through the Resource Explorer.

Solution

From digging around the Access Policy resource has the following ARM Template Schema:

{
   "type": "Microsoft.Web/connections/accessPolicies",
   "apiVersion": "2016-06-01",
   "name": "[concat('<connection-name>'),'/','<object-ID>')]",
   "location": "<location>",
   "dependsOn": [
      "[resourceId('Microsoft.Web/connections', parameters('connection_name'))]"
   ],
   "properties": {
      "principal": {
         "type": "ActiveDirectory",
         "identity": {
            "objectId": "<object-ID>",
            "tenantId": "<tenant-ID>"
         }
      }
   }
}

Resource Properties

Parameter	Description
<connection-name>	The name for your managed API connection, for example office365
<object-ID>	The object ID for your Microsoft Entra identity, for example the system assigned managed identity of the logic app
<tenant-ID>	The tenant ID for your Microsoft Entra identity

In Bicep this takes on the following form:

@description('Create the access policy for the Logic App to access the managed Api Connection ')
resource managedAPIConnectionAccessPolicy 'Microsoft.Web/connections/accessPolicies@2016-06-01' = {
  name: logicApp.name // Using the Logic App Name for readability
  parent: managedAPIConnector
  location: Location
  properties: {
    principal: {
      type: 'ActiveDirectory'
      identity: {
        tenantId: subscription().tenantId
        objectId: logicApp.identity.principalId // Using the System Assigned Managed Identity of the Logic App
      }
    }
  }
}

Note

The Bicep tooling will give you the following warning but will not hinder in both the transpilation into ARM or in the deployment of the resource:

Resource type "Microsoft.Web/connections/accessPolicies@2016-06-01" does not have types available.

Over the years of developing Infrastructure as Code (IaC) with either ARM templates or Bicep (since it was released in 2020), I have made it my best practice where possible to use well-defined base type parameters (Strings | Integers | Booleans) so that the templates are usable and maintainable by collaborators apart from myself. This usually equated to where possible avoiding the use of Object and Array parameters, although in many cases the use of these types was inevitable given the complexity of the infrastructure and resources being deployed.

In the situations where I needed to make use of Object or Array parameters, I would heavily rely on defining attributes, comments, and defaults to allow the template to retain some kind of reusability and maintainability, such as:

Example: Array of Objects

@description('Array of API operations')
@minLength(1)
param apimAPIOperations array = [
  {
    name: '' // Name of API Operation
    displayName: '' // Friendly Name of API Operation
    method: '' // HTTP Method -  GET | POST | PUT | DELETE | PATCH
    lgWorkflowName: '' // Name of the Backing Logic App Workflow
    lgWorkflowTrigger: '' // Name of the Backing Logic App Workflow HTTP Trigger
  }
]

Although this approach provides nice documentation around what is expected of the parameter,

• There is no enforcement on the object structure allowing users to pass in a variation of the object causing issues further on.
• The parameter has a default value for documentation purposes, but if a user is unaware, they might use the default, again resulting in issues further on.
• There is no intellisense when using the parameter. You will completely rely on the fact that you have referenced the properties and structuring within correctly.

I promise, its not all doom and gloom, the light at the end of the tunnel has arrived…

My New Best Practice

As of December 2023 Bicep Version 0.24.24 User Defined Types are no longer experimental! Bicep CLI version 0.12.X or higher is required to use this feature.

⚠️ NOTE:

When transpiled into ARM, the user-defined types uses the new Language Version 2.0.

• The current release of the Azure Resource Manager Tools extension for Visual Studio Code does not recognize the enhancements made in languageVersion 2.0.
• The Azure Portal Custom deployment does not currently recognize the enhancements made in languageVersion 2.0.

User Defined Types allow us to define our own custom types with ambient types Strings | Integers | Booleans, primitive literals for validation (allowed options) = 'bicep' | 'arm' | 'azure' and markings for optional properties ?. There is more configurations and abilities with this feature so for more information see User-defined data types in Bicep.

User Defined Types removes my problem space. I can now create a defined type that represents my complex object or array. This new Type can then be used on a parameter with full intellisense support and validation so incorrect usage is flagged early with a Fail Fast approach.

The problem case example shown earlier can now be represented as follows:

// ** User Defined Types **
// ************************

@description('Configuration properties for setting up a LG App stnd APIM API Operation')
@metadata({
  name: 'Name of the API Operation'
  displayName: 'User friendly name of the API Operation'
  method: 'The API Operations HTTP method'
  lgWorkflowName: 'Name of the Standard Logic App Workflow to use for the Operation Backend'
  lgWorkflowTrigger: 'Name of the Workflow HTTP Trigger'
})
@sealed()
type apimAPIOperation = {
  name: string
  displayName: string
  method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE'
  lgWorkflowName: string
  lgWorkflowTrigger: string
}

@description('One or more APIM API Operations to configure')
@minLength(1)
type apimAPIOperationArray = apimAPIOperation[]

// ** Parameters **
// ****************

@description('Array of API operations')
param apimAPIOperations apimAPIOperationArray

The example above shows the use of:

• @description decorator to provide a high-level summary of the type

• @metadata decorator being used to document the object properties.

• @sealed decorator being used to mark the object parameter as only permitting properties specifically included in the type definition.

• Primitive Literals for Validation, the value specified can only be one of the following: method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE'.

• Union of types by creating an array type of a user-defined object type:

  type apimAPIOperationArray = apimAPIOperation[]

Have a go and see if this also becomes your new best practice. For more configurations and abilities with this feature see User-defined data types in Bicep.

Azure role-based access control (Azure RBAC) provides fine grained control over access to Azure resources. Azure RBAC is founded on top of the Azure Resource Manager which allows us to provide access authorisation at differing scope levels ranging from the Management Group through to individual resources.

With RBAC enabled key vaults we can manage access to the resource and data stored in the vault. We can also manage access for individual keys, secrets, and certificates.

Scenario

In this scenario we have an application that has stored all its secrets in its own application specific key vault. Part of this application makes use of an Azure Function that we would like to place into Azure API Management (APIM).

An Application can be a single or group of related services.

When deploying the Azure Function we are placing the Function Authorisation Key into the Application Specific Key Vault. As part of the APIM API Backend we would like to add the Function Authorisation Key as a header and obtain this key from the application specific key vault.

If we provide APIM access to the entire application key vault we would be compromising our security boundary.

Best Practice

Security Boundary - We do not want to provide complete access to the application Key Vault. If there is a breach of security we do not want to compromise the application and widen the blast radius.

To mitigate this, we can specify granular access to the specific secret in the key vault that APIM requires. In this case, if there were to be a security breach, we have limited the reach and access to which damage could spread.

Solution

To setup the RBAC permission between APIM and the application specific Key Vault, we will need to have the following configured:

1. For a deployment principle to add role assignments, you must have Microsoft.Authorization/roleAssignments/write and Microsoft.Authorization/roleAssignments/delete permissions setup, such as one of the following:
   • Key Vault Data Access Administrator (preview)
   • User Access Administrator
   • Owner
2. Make sure your Application Key Vault is RBAC Enabled.

resource symbolicname 'Microsoft.KeyVault/vaults@2022-07-01' = {
  name: 'string'
  location: 'string'
  properties: {
    ...
    enableRbacAuthorization: true
    ...
  }
}

3. Azure API Management is setup to use System Assigned Managed Identity.

resource symbolicname 'Microsoft.ApiManagement/service@2023-03-01-preview' = {
  name: 'string'
  location: 'string'
  sku: {
    ...
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    ...
  }
}

4. The Azure Function Auth Key added into Key Vault as a secret.

Note: The function default host key is created and only accessible after the function code is provisioned. The following IaC would need to be conducted as a secondary deployment.

@description('Retrieve the Application Key Vault instance to store secrets')
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

@description('Retrieve the Function App for linking as a backend')
resource functionApp 'Microsoft.Web/sites@2022-09-01' existing = {
  name: functionName
  ...
}

@description('Vault the Function App Key as a secret')
resource vaultFunctionAppKey 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'functionAppKey'
  parent: keyVault
  properties: {
    contentType: 'string'
    value: listkeys('${functionApp.id}/host/default/', '2021-02-01').functionkeys.default
  }
}

5. Grant APIM Identity Role permissions to access the Key Vault Secret
   • Granting Key Vault Reader Role.
   • Property Scope is pointing at the Key Vault Secret so access is confined to only that secret.

@description('APIM Instance')
resource apimInstance 'Microsoft.ApiManagement/service@2022-08-01' = {
  name: apimInstanceName
  ...
}

@description('Grant APIM Key Vault Reader for the function API key secret')
resource grantAPIMPermissionsToSecret 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(keyVault.id)
  scope: vaultFunctionAppKey
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalId: apimInstance.identity.principalId
    principalType: 'ServicePrincipal'
  }
}

6. Setup a APIM Backend with a Named Value to make use of the Key Vault Secret

@description('Create the backend for the Function API')
resource functionBackend 'Microsoft.ApiManagement/service/backends@2022-08-01' = {
  name: apiName
  parent: apimInstance
  properties: {
    protocol: 'http'
    url: 'https://${functionApp.properties.defaultHostName}/api'
    resourceId: 'https://management.azure.com${functionApp.id}'
    tls: {
      validateCertificateChain: true
      validateCertificateName: true
    }
    credentials: {
      header: {
        'x-functions-key': [
          '{{${apiName}-key}}'
        ]
      }
    }
  }
  dependsOn: [
    functionBackendNamedValues
  ]
}

@description('Create the named value for the function API backend')
resource functionBackendNamedValues 'Microsoft.ApiManagement/service/namedValues@2022-08-01' = {
  name: '${apiName}-key'
  parent: apimInstance
  properties: {
    displayName: '${apiName}-key'
    tags: [
      'key'
      'function'
    ]
    secret: true
    keyVault: {
      identityClientId: null
      secretIdentifier: '${keyVault.properties.vaultUri}secrets/${vaultFunctionAppKey.name}'
    }
  }
  dependsOn: [
    grantAPIMPermissionsToSecret
  ]
}

Summary

And there we have it, APIM now has granular access to the secrets it requires without compromising our security boundaries that have been put in place to protect the backing application.

Have a play and have fun.

An Azure Tenant is hierarchically structured with the following make up:

• Tenant
• One or more Management Groups
• One or more Subscriptions
• One or more Resource groups
• One or more Resources

Deployment Scopes {Tenant, Management Group, Subscription, Resource Group} allow us to deploy respective types of resources at each level.

A Scope is dictated by two attributes, the selected scope level, and the identifier of the item at that scope level. For example, if I am to deploy at the Subscription Scope, I need to both Identify that I am doing a Subscription Deployment, and I need to provide the identifier of the Subscription. Resource Groups are the lowest in the list of Scope Levels.

Single Scope Deployment

In a single scoped deployment, we essentially design our Bicep templates to target a single scope level such as Resource group. In this type of deployment we only deploy respective resources to a specific Resource Group and no other. For Example:

In Bicep this would appear as follows:

targetScope = 'resourceGroup'

// Parameters
...
// Variables
...
// Resources

resource keyVault 'Microsoft.KeyVault/vaults@2023-02-01' = {
	...
}

resource storageaccount 'Microsoft.Storage/storageAccounts@2021-02-01' = {
	...
}

// Outputs
...

Parent Child Deployment Scope Hopping

Parent Child Deployment Scope Hopping is where we choose a parent scope that will effectively be our starting point in conducting deployments. In this type of deployment, we can conduct deployments in the parent scope and in each child. For Example:

In Bicep this would appear as follows:

targetScope = 'subscription'

// Parameters
@description('Name of the Second existing Resource Group')
param resourceGroup2Name string
...
// Variables
...
// Resources

// Deploy Resource Group 1
resource RG1Deploy 'Microsoft.Resources/resourceGroups@2022-09-01' = {
...
}

// Deploy Resources into Resource Group 1
module rg1 'rg1.bicep' = {
	scope: RG1Deploy
	...
}

// Deploy Resources into Existing Resource Group 2
module rg2 'rg1.bicep' = {
	scope: ResourceGroup(resourceGroup2Name) // Use the ResourceGroup function to obtain the reference to the second RG
	...
}

// Outputs
...

If we choose the Management Group Scope for our deployment, we can conduct deployments in the selected Management Group, each linked Subscription, and furthermore each Resource group under each Subscription.

Sibling Scope Hop

Sibling Deployment Scope Hopping is where we choose a scope that will effectively be our starting point in conducting deployments, but from this scope move to deploy into another scope but on the same scope level.

An example would be where we wish to deploy resources into different resource groups. The Subscriptions can be different, all that is required is the deployment principal be provided the relevant rights to the Resource Groups such as Contributor. The benefit of this approach is rights do not need to be supplied to a higher scope of which would be applied to child items.

In the diagram above, we are looking to use the first Resource Group as the starting scope. Each hop will then point to a different Resource Group but in the same scope level. For the second and third hop, we will also need to provide a Subscription Id as we will not be able to reference by Resource Group name only.

The corresponding Bicep for the diagram above would appear as such:

targetScope = 'resourceGroup'

// Parameters
@description('Name of the Second existing Resource Group')
param resourceGroup2Name string

@description('Subscription Id for the 3rd Resource Group')
param subscription2Id string
@description('Name of the 3rd existing Resource Group')
param resourceGroup3Name string

@description('Subscription Id for the 4th Resource Group')
param subscription3Id string
@description('Name of the 4th existing Resource Group')
param resourceGroup4Name string

...
// Variables
...
// Resources

// Deploy Resources into Resource Group 1
// No Scope applied as we are deploying to the starting scope
module rg1 'rg.bicep' = {
	...
}

// Deploy Resources into Resource Group 2
// Only need to specify ResourceGroup function with a name as still under the same subscription
module rg2 'rg.bicep' = {
	scope: ResourceGroup(resourceGroup2Name)
	...
}

// Deploy Resources into Resource Group 3
// Need to specify ResourceGroup function with a name and subscription
module rg3 'rg.bicep' = {
	scope: ResourceGroup(subscription2Id, resourceGroup3Name)
	...
}

// Deploy Resources into Resource Group 4
// Need to specify ResourceGroup function with a name and subscription
module rg4 'rg.bicep' = {
	scope: ResourceGroup(subscription3Id, resourceGroup4Name)
	...
}

// Outputs

Mix and Match

Usage of these methods can vary and can also be combined. For instance you could combine both a Parent Child Scope hop with Sibling hops. How you structure your deployments will depend on the architecture and resource dependencies at play.

You may find yourself looking to deploy Key Vault in one Resource Group and a Web App in another. Your Web App might require access to the Key Vault instance and therefore an Access Policy will need deploying. Rather than navigating a potential parent child deployment, why not do a sibling hop?

I have recently been looking at creating multiple of the same resource using Bicep. There is however a condition where I would wish for the set of resources not to be deployed. The following stages show my work through of this particular problem (using a storage account resource as an example):

Conditional Deployment

Conditional Deployment is used where you may or may not wish to deploy a given resource depending on the outcome of a given condition (if statement).

/**********************************
Bicep Template: Conditional Storage
***********************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

param name string

param location string

param deployStorage bool

// ** Variables **
// ***************

// ** Resources **
// ***************

resource storageAccountDeployment 'Microsoft.Storage/storageAccounts@2021-02-01' = if (deployStorage) {
  name: name
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Premium_LRS'
  }
}

// ** Outputs **
// *************

In the instance shown above, if the deployStorage parameter is True then the storageAccountDeployment will be deployed, if False then the storageAccountDeployment will not be deployed. As an ARM template the instance above will appear as follows:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "deployStorage": {
      "type": "bool"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployStorage')]",
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-02-01",
      "name": "[parameters('name')]",
      "location": "[parameters('location')]",
      "kind": "StorageV2",
      "sku": {
        "name": "Premium_LRS"
      }
    }
  ]
}

Looping Resources

Iterative loops in Bicep utilise the For syntax as shown below:

/**********************************
Bicep Template: Iterative Storage
***********************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

param location string

param storageAccounts array

// ** Variables **
// ***************

// ** Resources **
// ***************

resource storageAccountDeployment 'Microsoft.Storage/storageAccounts@2021-02-01' = [for storage in storageAccounts: {
  name: storage.name
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Premium_LRS'
  }
}]

// ** Outputs **
// *************

The syntax above will deploy a number of storage accounts based on the number of storage items in the parameter array. In ARM this appears as follows:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "storageAccounts": {
      "type": "array"
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storageaccountDeployment",
        "count": "[length(parameters('storageAccounts'))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-02-01",
      "name": "[parameters('name')]",
      "location": "[parameters('location')]",
      "kind": "StorageV2",
      "sku": {
        "name": "Premium_LRS"
      }
    }
  ]
}