Merge pull request #314872 from mumian/0416-roleDefinitions

JillGrant615 · web-flow · commit c4a70ac5b55f · 2026-04-17T17:24:37.000-06:00
Document the roleDefinitions function
diff --git a/articles/azure-resource-manager/bicep/bicep-functions-resource.md b/articles/azure-resource-manager/bicep/bicep-functions-resource.md
@@ -5,7 +5,7 @@ ms.topic: reference
 ms.custom:
   - devx-track-bicep
   - build-2025
-ms.date: 12/22/2025
+ms.date: 04/17/2026
 ---
 
 # Resource functions for Bicep
@@ -661,6 +661,48 @@ output storageID string = storageAccount.id
 
 For more information, see the [JSON template resourceId function](../templates/template-functions-resource.md#resourceid).
 
+## roleDefinitions
+
+`roleDefinisions(roleName)`
+
+Returns information about the specified role definition, including `id` and `roleDefinitionId`. It's a name-based helper for Azure RBAC role assignments. Instead of requiring you to hardcode the GUID of a built-in role definition (like Contributor, Reader, and others), it lets you provide the built-in role’s display name, and the function resolves the corresponding role definition information at deployment time.
+
+Namespace: [az](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| roleName | Yes | string | The display name of the role definition. |
+
+### Return value
+
+An object representing the role definition, including `id` and `roleDefinitionId`.
+
+### Examples
+
+The following Bicep code creates a deterministic Azure RBAC role assignment that grants a specified principal the **Storage Blob Data Reader** built‑in role at the deployment scope by resolving the role definition by name at deployment time.
+
+```bicep
+@description('Specifies the role definition ID used in the role assignment.')
+param roleDefinitionName string = 'Storage Blob Data Reader'
+
+@description('Specifies the principal ID assigned to the role.')
+param principalId string
+
+var roleAssignmentName= guid(principalId, roleDefinitionName, resourceGroup().id)
+resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
+  name: roleAssignmentName
+  properties: {
+    roleDefinitionId: roleDefinitions(roleDefinitionName).id
+    principalId: principalId
+  }
+}
+
+```
+
+For more information, see the [JSON template resourceId function](../templates/template-functions-resource.md#roledefinitions).
+
 ## subscriptionResourceId
 
 `subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)`
diff --git a/articles/azure-resource-manager/bicep/bicep-functions.md b/articles/azure-resource-manager/bicep/bicep-functions.md
@@ -2,7 +2,7 @@
 title: Bicep functions overview
 description: Learn about the functions that can be used in a Bicep file to retrieve values, work with strings and numerics, and retrieve deployment information.
 ms.topic: reference
-ms.date: 09/11/2025
+ms.date: 04/17/2026
 ms.custom:
   - devx-track-bicep
   - build-2025
@@ -158,6 +158,7 @@ The following functions are available for getting resource values. Most of these
 * [providers (deprecated)](./bicep-functions-resource.md#providers)
 * [reference](./bicep-functions-resource.md#reference)
 * [resourceId](./bicep-functions-resource.md#resourceid) - This can be used at any scope, but the valid parameters change depending on the scope.
+* [roleDefinitions](./bicep-functions-resource.md#roledefinitions)
 * [subscriptionResourceId](./bicep-functions-resource.md#subscriptionresourceid)
 * [tenantResourceId](./bicep-functions-resource.md#tenantresourceid)
 * [toLogicalZone](./bicep-functions-resource.md#tologicalzone)
diff --git a/articles/azure-resource-manager/bicep/toc.yml b/articles/azure-resource-manager/bicep/toc.yml
@@ -355,7 +355,7 @@ items:
       displayName: externalInput,getSecret,readEnvironmentVariable
       href: bicep-functions-parameters-file.md
     - name: Resource functions
-      displayName: extensionResourceId,getSecret,listAccountSas,ListKeys,listSecrets,list,managementGroupResourceId,pickZones,providers,reference,resourceId,subscriptionResourceId,tenantResourceId,toLogicalZone,toLogicalZones,toPhysicalZone,toPhysicalZones
+      displayName: extensionResourceId,getSecret,listAccountSas,ListKeys,listSecrets,list,managementGroupResourceId,pickZones,providers,reference,resourceId,roleDefinitions,subscriptionResourceId,tenantResourceId,toLogicalZone,toLogicalZones,toPhysicalZone,toPhysicalZones
       href: bicep-functions-resource.md
     - name: Scope functions
       displayName: managementGroup,resourceGroup,subscription,tenant
diff --git a/articles/azure-resource-manager/templates/template-functions-resource.md b/articles/azure-resource-manager/templates/template-functions-resource.md
@@ -1258,6 +1258,66 @@ The output of default values from the preceding example is:
 | differentSubOutput | String | /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage |
 | nestedResourceOutput | String | /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName |
 
+## roleDefinitions
+
+`roleDefinisions(roleName)`
+
+Returns information about the specified role definition, including `id` and `roleDefinitionId`. It's a name-based helper for Azure RBAC role assignments. Instead of requiring you to hardcode the GUID of a built-in role definition (like Contributor, Reader, and others), it lets you provide the built-in role’s display name, and the function resolves the corresponding role definition information at deployment time.
+
+In Bicep, use the [roleDefinitions](../bicep/bicep-functions-resource.md#roledefinitions) function.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| roleName | Yes | string | The display name of the role definition. |
+
+### Return value
+
+An object representing the role definition, including `id` and `roleDefinitionId`.
+
+### Examples
+
+The following ARM template creates a deterministic Azure RBAC role assignment that grants a specified principal the **Storage Blob Data Reader** built‑in role at the deployment scope by resolving the role definition by name at deployment time.
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "roleDefinitionName": {
+      "type": "string",
+      "defaultValue": "Storage Blob Data Reader",
+      "metadata": {
+        "description": "Specifies the role definition ID used in the role assignment."
+      }
+    },
+    "principalId": {
+      "type": "string",
+      "metadata": {
+        "description": "Specifies the principal ID assigned to the role."
+      }
+    }
+  },
+  "variables": {
+    "roleAssignmentName": "[guid(parameters('principalId'), parameters('roleDefinitionName'), resourceGroup().id)]"
+  },
+  "resources": [
+    {
+      "type": "Microsoft.Authorization/roleAssignments",
+      "apiVersion": "2022-04-01",
+      "name": "[variables('roleAssignmentName')]",
+      "properties": {
+        "roleDefinitionId": "[roleDefinitions(parameters('roleDefinitionName')).id]",
+        "principalId": "[parameters('principalId')]"
+      }
+    }
+  ]
+}
+```
+
+For more information, see the [Bicep roleDefinition function](../bicep/bicep-functions-resource.md#roledefinitions).
+
 ## subscription
 
 See the [`subscription` scope](template-functions-scope.md#subscription) function for more information.
diff --git a/articles/azure-resource-manager/templates/template-functions.md b/articles/azure-resource-manager/templates/template-functions.md
@@ -3,7 +3,7 @@ title: Template functions
 description: Describes the functions to use in an Azure Resource Manager template (ARM template) to retrieve values, work with strings and numerics, and retrieve deployment information.
 ms.topic: reference
 ms.custom: devx-track-arm-template
-ms.date: 07/10/2025
+ms.date: 04/17/2026
 ---
 
 # ARM template functions
@@ -262,6 +262,7 @@ Resource Manager provides the following functions for getting resource values:
 * [reference](template-functions-resource.md#reference)
 * [references](template-functions-resource.md#references)
 * [resourceId](template-functions-resource.md#resourceid) - can be used at any scope, but the valid parameters change depending on the scope.
+* [roleDefinitions](template-functions-resource.md#roledefinitions)
 * [subscriptionResourceId](template-functions-resource.md#subscriptionresourceid)
 * [tenantResourceId](template-functions-resource.md#tenantresourceid)
 
