Add-EntraPermissionToCreateAgentUsersToAgentIdentityBlueprintPrincipal

Module:

Microsoft.Entra.Applications Module v1.3

Grants permission to create Agent Users to the Agent Identity Blueprint Principal.

Add-EntraPermissionToCreateAgentUsersToAgentIdentityBlueprintPrincipal

 [-AgentBlueprintId <String>]
 [<CommonParameters>]

The Add-EntraPermissionToCreateAgentUsersToAgentIdentityBlueprintPrincipal cmdlet adds the AgentIdUser.ReadWrite.IdentityParentedBy permission to the Agent Identity Blueprint Service Principal. This permission allows the blueprint to create agent users that are parented to agent identities. The cmdlet looks up the blueprint's service principal and the Microsoft Graph service principal in the tenant, then creates an app role assignment linking them. Uses the stored AgentBlueprintId from the last New-EntraAgentIdentityBlueprint call if no explicit ID is provided. If no stored ID is available, the cmdlet prompts interactively for the blueprint Application ID.

Connect-Entra -Scopes 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.IdentityParentedBy'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("user1@contoso.com")
New-EntraAgentIdentityBlueprintPrincipal
Add-EntraPermissionToCreateAgentUsersToAgentIdentityBlueprintPrincipal

Name Value
---- -----
id assignment-guid
principalId sp-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb
resourceId graph-sp-id
appRoleId 4aa6e624-eee0-40ab-bdd8-f9639038a614
AgentBlueprintId bbbbbbbb-2222-3333-4444-cccccccccccc
AgentBlueprintServicePrincipalId sp-aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb
PermissionName AgentIdUser.ReadWrite.IdentityParentedBy
PermissionDescription Allows creation of agent users parented to agent identities
MSGraphServicePrincipalId graph-sp-id

This example grants the AgentIdUser.ReadWrite.IdentityParentedBy permission to the Agent Identity Blueprint Service Principal that was just created.

Connect-Entra -Scopes 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.IdentityParentedBy'
Add-EntraPermissionToCreateAgentUsersToAgentIdentityBlueprintPrincipal -AgentBlueprintId "7c0c1226-1e81-41a5-ad6c-532c95504443"

This example grants the permission to a specific Agent Identity Blueprint by providing the blueprint ID.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Returns the app role assignment response object from Microsoft Graph, enriched with the following additional properties:

• AgentBlueprintId - The Application ID of the Agent Identity Blueprint.
• AgentBlueprintServicePrincipalId - The object ID of the blueprint's service principal.
• PermissionName - The permission name (AgentIdUser.ReadWrite.IdentityParentedBy).
• PermissionDescription - A description of what the permission allows.
• MSGraphServicePrincipalId - The object ID of the Microsoft Graph service principal in the tenant.

The base response includes id, principalId, resourceId, and appRoleId.

This cmdlet requires the following Microsoft Graph permissions:

• AgentIdentityBlueprint.UpdateAuthProperties.All
• AgentIdUser.ReadWrite.IdentityParentedBy

This cmdlet requires the Agent Identity Blueprint Service Principal to be created first using New-EntraAgentIdentityBlueprintPrincipal. The cmdlet looks up the blueprint's service principal by filtering on appId, so the blueprint must already have a service principal in the tenant.

The Microsoft Graph Service Principal ID is cached after the first lookup for performance. The cmdlet also stores the blueprint service principal ID in a module-level variable (CurrentAgentBlueprintServicePrincipalId) for use by other cmdlets.

This cmdlet uses the Microsoft Graph v1.0 API endpoint (/v1.0/servicePrincipals).

The specific app role assigned is AgentIdUser.ReadWrite.IdentityParentedBy (ID: 4aa6e624-eee0-40ab-bdd8-f9639038a614).