Bicep Tips and Tricks | #11 | Working with Role Assignments

Problem Space

Role assignments are one of those areas in Azure that look simple on the surface, but can become awkward pretty quickly once you start automating them properly.

Anyone who has worked with RBAC through IaC for long enough will usually run into the same set of problems.

There are usually three things in play:

• The role assignment name needs to be deterministic
• The roleDefinitionId is represented by a GUID that is not especially readable nor indicative of which role it is referring
• When something already exists, the resulting deployment error has not always been particularly helpful

Thankfully, there have been some recent improvements here that are worth knowing about. Some help with troubleshooting, some help with authoring, and one in particular helps with conformance across tooling.

In this post I wanted to walk through three of them:

1. Improved ARM error messages when a role assignment already exists
2. A defined standard for role assignment ID generation
3. Bicep support for resolving role definition IDs from the friendly role name

Improved Error Message for Existing Role Assignments

Historically, if you attempted to deploy a role assignment that already existed but with a different name ID, ARM would return the following:

{
	"code": "RoleAssignmentExists",
	"message": "The role assignment already exists."
}

Technically correct, but not overly helpful.

You knew something was already there, but not which role assignment, not what its ID was, and not how quickly you could correlate that back to the target scope. In environments with multiple deployment paths or platform teams supporting shared subscriptions, that usually meant extra investigation.

The updated message is much better:

{
	"code": "RoleAssignmentExists",
	"message": "The role assignment already exists. The ID of the existing role assignment is a3f1c9e2-7b4d-4e8a-bf62-1d0c5a9e34f7."
}

This is a small change, but a useful one. You can now go straight to the existing assignment, confirm the scope and principal, and decide whether the issue is:

• A valid existing assignment that your deployment should align to
• A duplicate assignment attempt from another deployment path
• A stale or unexpected assignment that needs to be cleaned up

From an operational perspective, this should make diagnosis much quicker, especially when you are dealing with shared scopes or multiple deployment paths.

Standardised Role Assignment ID Generation

For me, this is one of the more important changes because it helps establish consistency across teams and tooling.

There is now a defined standard for how role assignment IDs should be generated across Portal, Bicep, AzCLI, PowerShell, and Terraform:

guid(scope, principalId, roleDefinitionId)

This matters because role assignments should not have arbitrary names. If one tool or team generates the assignment name using one set of inputs and another tool uses something different, you can end up with the same assignment intent represented by different assignment names. That is exactly the sort of inconsistency that makes troubleshooting harder than it needs to be.

Using the standard generation pattern gives you a few benefits:

• Consistent behaviour across tooling
• Better conformance with the broader Azure platform expectation
• Easier reasoning when comparing manually created and IaC-created assignments
• Fewer surprises when different teams or delivery tools interact with the same scope

If you are still generating the role assignment name using arbitrary values, or values that do not include the scope, principal ID, and role definition ID, it is worth correcting that.

For example, this is the pattern I would now avoid:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid('contributor', principalId) // <-- Avoid
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

And this is the pattern to prefer:

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinitionId)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

It is deterministic, aligned to the standard, and much easier to reason about when you need to compare behaviour across tools.

Friendly Role Definition Lookup in Bicep

The next improvement is the Bicep roleDefinitions() function introduced in v0.42.1.

This allows you to retrieve the role definition ID from the friendly role name:

properties: {
	roleDefinitionId: roleDefinitions('Data Factory Contributor').id
	...
}

From a readability point of view, this is a nice improvement, and probably the part most people will notice first.

If you compare a friendly name such as Data Factory Contributor to a raw GUID, it is immediately obvious which role is being assigned. That helps with:

• Code reviews
• Onboarding team members into your templates
• General maintainability when revisiting code months later

Compare the older style:

var contributorRoleDefinitionGuid = 'b24988ac-6180-42a0-ab88-20f7382dd24c'

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinitionId)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinitionId
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

With the newer style:

var contributorRoleDefinition = roleDefinitions('Contributor')

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
	name: guid(resourceGroup().id, principalId, contributorRoleDefinition.id)
	scope: resourceGroup()
	properties: {
		roleDefinitionId: contributorRoleDefinition.id
		principalId: principalId
		principalType: 'ServicePrincipal'
	}
}

I think there is a very fair maintainability argument in favour of the second example. The intent is clearer and there is less mental translation required when reading the template.

The Trade-Off

This is where I would urge a little caution.

Whilst roleDefinitions() improves readability, it also introduces a dependency on the display name of the role definition. The underlying role definition ID may remain stable, but the role display name can change over time, even when the underlying role definition ID remains the same.

Is that likely to happen frequently? No, probably not.

Is it impossible? Also no.

That is the trade-off.

If a built-in role display name changes and your template is resolving the role definition by name, then your deployment can break even though the underlying role definition itself still exists and still has the same stable ID.

So I think the balanced view here is:

• If readability and authoring clarity are your primary concern, roleDefinitions() is a very welcome improvement
• If you are optimising for resilience and want to minimise dependency on mutable display names, stable GUID-based references are still a valid approach

This is also a good argument for centralising stable role definition GUIDs if you choose to keep using them, for example through shared variables or imports. That way you still gain maintainability benefits without scattering raw IDs throughout your codebase.

Recommended Practice

My current view would be:

• Always generate the role assignment name using guid(scope, principalId, roleDefinitionId)
  • Treat that pattern as the standard regardless of whether you are using Portal, Bicep, AzCLI, PowerShell, or Terraform
• Use roleDefinitions() where readability and maintainability are more valuable than the small risk of role display name changes
• Use stable GUID-based role definition references where deployment resilience is the higher priority

The important point is not that one of these approaches is universally right and the other universally wrong. It is that you should make the choice consciously.

What I do think should now be treated as non-negotiable is the role assignment naming pattern. That should follow the platform standard.

Conclusion

Recent changes around role assignments are moving things in the right direction.

The improved RoleAssignmentExists message makes diagnosis easier. The defined standard for role assignment ID generation improves conformance across teams and tooling. And the roleDefinitions() function in Bicep improves readability and maintainability when you want friendlier authoring.

For me, the key takeaway is fairly simple: adopt the standard assignment naming pattern everywhere, and then decide whether friendly-name lookup or stable GUID references are the better fit for your environment.

Hope this helps, and happy Bicep-ing!

• ← Previous Post