az.principal() — Resolve Entra ID object IDs by display name at deploy time (analogous to az.roleDefinitions())

[MDAG21]

az.principal() — Resolve Entra ID object IDs by display name at deploy time (analogous to az.roleDefinitions())

Problem

When authoring role assignments in Bicep, it is common to need the object ID of an Entra ID principal — a security group, user, or service principal — as the principalId. Today there is no way to resolve this by name; authors must look up the GUID out-of-band and hardcode it:

// main.bicepparam
var myTeamId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'   // ← manual lookup required

param configStorageRoleAssignments = [
  {
    principalId: myTeamId
    role: 'Storage Blob Data Contributor'
  }
]

This friction causes several problems:

• Engineers must context-switch from IaC authoring to the portal or CLI to find a GUID
• GUIDs in source code carry no readable intent — reviewers can't tell what xxxxxxxx-xxxx-... refers to without a comment
• GUIDs must be maintained separately per tenant if the same template is reused across tenants

Precedent — az.roleDefinitions()

PR #18457 solved exactly this pattern for RBAC role definitions. Before, authors had to hardcode role definition GUIDs:

// Before
roleDefinitionId: '/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

After, a name-based runtime function resolves the GUID for them:

// After
roleDefinitionId: az.roleDefinitions('Storage Blob Data Contributor').id

The implementation in AzNamespaceType.cs is clean — a FunctionOverloadBuilder declaration whose result is populated at ARM runtime:

yield return new FunctionOverloadBuilder("roleDefinitions")
    .WithReturnResultBuilder(GetRoleDefinitionReturnResult, GetRoleDefinitionReturnType())
    .WithGenericDescription("Gets a role definition that can be used in role assignments.")
    .WithDescription("Returns information about the specified role definition including id and roleDefinitionId.")
    .WithRequiredParameter("roleName", LanguageConstants.String, "The display name of the role definition")
    .Build();

The same pattern should be applicable to Entra ID principals.

Proposed Solution

Add a new az.principal() function to the az namespace that resolves an Entra ID principal's object ID by display name or UPN at ARM deployment time.

Proposed Bicep syntax

// Resolve a security group by display name
principalId: az.principal('My App Dev Team').id

// Resolve a user by UPN
principalId: az.principal('jsmith@contoso.com').id

// Resolve a service principal / managed identity by display name
principalId: az.principal('my-managed-identity').id

Proposed return type

private static ObjectType GetPrincipalReturnType()
{
    return new ObjectType("principal", TypeSymbolValidationFlags.Default, new[]
    {
        new NamedTypeProperty("id",          LanguageConstants.String),  // object ID
        new NamedTypeProperty("displayName", LanguageConstants.String),
        new NamedTypeProperty("type",        LanguageConstants.String),  // User | Group | ServicePrincipal
    }, null);
}

Proposed AzNamespaceType.cs declaration

yield return new FunctionOverloadBuilder("principal")
    .WithReturnResultBuilder(GetPrincipalReturnResult, GetPrincipalReturnType())
    .WithGenericDescription("Gets an Entra ID principal that can be used in role assignments and policy definitions.")
    .WithDescription("Returns the object ID and metadata for the Entra ID user, group, or service principal matching the given display name or UPN.")
    .WithRequiredParameter("displayNameOrUpn", LanguageConstants.String, "The display name or UPN of the principal")
    .Build();

Updated authoring experience

// main.bicepparam — no more manual GUID lookups
param configStorageRoleAssignments = [
  {
    principalId: az.principal('My App Dev Team').id
    role: 'Storage Blob Data Contributor'
  }
]

// main.bicep — role assignment module
module storageRoleAssignment 'br/registry:storageroleassignment:latest' = [
  for (ra, index) in configStorageRoleAssignments: {
    name: 'storageRoleAssignment-${index}'
    params: {
      principalId:        ra.principalId
      roleDefinitionName: ra.role   // already using az.roleDefinitions() pattern
      storageAccountName: storageAccount.outputs.name
    }
  }
]

Implementation Considerations

ARM engine — Graph API access

The main dependency is whether the ARM deployment engine can invoke the Microsoft Graph API during template evaluation, the same way it resolves role definition names today. ARM already has Graph access in some scenarios (e.g., AAD admin assignment for SQL). A scoped Microsoft.Graph/principals read would be the minimal permission surface.

Alternative: Microsoft Graph extensibility provider

If ARM-native resolution is not feasible, this could instead be surfaced as part of the microsoftgraph Bicep extensibility provider as a read-only lookup function rather than a full resource deployment:

import 'microsoftgraph@1.0.0' as graph

module roleAssignment './roleAssignment.bicep' = {
  params: {
    principalId: graph.principal('My App Dev Team').id
  }
}

Ambiguity handling

Display names in Entra ID are not guaranteed to be unique. The function should:

• Throw a deployment error if zero or multiple principals match, with a clear message
• Optionally accept a type parameter ('Group', 'User', 'ServicePrincipal') to disambiguate:

principalId: az.principal('App Dev', 'Group').id

Motivation Summary

Today	With az.principal()
Manual portal/CLI lookup required	Name resolved at deploy time
GUID in source with comment for intent	Self-documenting display name in code
Breaks when reused across tenants	Tenant-portable template
Inconsistent with az.roleDefinitions()	Consistent authoring model

This follows the exact same philosophy as az.roleDefinitions() and would eliminate the last remaining category of "magic GUIDs" in Bicep role assignment authoring.

[slavizh]

@MDAG21 have you looked at https://learn.microsoft.com/en-us/community/content/microsoft-graph-bicep-extension? I doubt that the Bicep team will come with something that does the same thing like the Graph extension. Role definitions are Azure resource thus why they did az.roleDefinitions(). Entra objects are not Azure resource thus the Graph extension.

[MDAG21]

I did and we do use it to create authentication app registrations, which has been huge for use, the issue is it doesn't support users only groups. We could use the existing method to at least query those.

I figured it was going to be an issue with the graph vs azure resource types.

Figured I'd ask regardless as this would make life a bit easier.

[slavizh]

@MDAG21 it supports users. It does not supports user creation but supports getting existing users. Users functionality is the most easy to use as well as you need to input the upn of the users where for the other objects you need unique name. https://learn.microsoft.com/en-us/graph/templates/bicep/reference/users?view=graph-bicep-1.0

[MDAG21]

@MDAG21 it supports users. It does not supports user creation but supports getting existing users. Users functionality is the most easy to use as well as you need to input the upn of the users where for the other objects you need unique name. https://learn.microsoft.com/en-us/graph/templates/bicep/reference/users?view=graph-bicep-1.0

Well then maybe I can work this in. Thanks for the heads up.

[jikuja]

Instead if displayName this should use uniqueName that was added when Graph API bicep extension was added.