Configure Azure Blueprint Role Assignment Artifacts

The azure-native:blueprint:RoleAssignmentArtifact resource, part of the Pulumi Azure Native provider, defines role assignments within Azure Blueprints that grant permissions to users or groups when the blueprint is deployed. This guide focuses on two capabilities: management group and subscription scoping, and parameter-driven principal assignment.

Role assignment artifacts belong to blueprints and reference Azure role definitions, management groups or subscriptions, and blueprint parameters that supply principal IDs. The examples are intentionally small. Combine them with your own blueprint definitions and parameter configurations.

Assign roles to principals at management group scope

Organizations using Azure Blueprints often need to grant permissions to users or groups when deploying resources across multiple subscriptions under a management group.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const roleAssignmentArtifact = new azure_native.blueprint.RoleAssignmentArtifact("roleAssignmentArtifact", {
    artifactName: "ownerAssignment",
    blueprintName: "simpleBlueprint",
    displayName: "enforce owners of given subscription",
    kind: "roleAssignment",
    principalIds: "[parameters('owners')]",
    resourceScope: "providers/Microsoft.Management/managementGroups/ContosoOnlineGroup",
    roleDefinitionId: "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
});

import pulumi
import pulumi_azure_native as azure_native

role_assignment_artifact = azure_native.blueprint.RoleAssignmentArtifact("roleAssignmentArtifact",
    artifact_name="ownerAssignment",
    blueprint_name="simpleBlueprint",
    display_name="enforce owners of given subscription",
    kind="roleAssignment",
    principal_ids="[parameters('owners')]",
    resource_scope="providers/Microsoft.Management/managementGroups/ContosoOnlineGroup",
    role_definition_id="/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7")

package main

import (
	blueprint "github.com/pulumi/pulumi-azure-native-sdk/blueprint/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := blueprint.NewRoleAssignmentArtifact(ctx, "roleAssignmentArtifact", &blueprint.RoleAssignmentArtifactArgs{
			ArtifactName:     pulumi.String("ownerAssignment"),
			BlueprintName:    pulumi.String("simpleBlueprint"),
			DisplayName:      pulumi.String("enforce owners of given subscription"),
			Kind:             pulumi.String("roleAssignment"),
			PrincipalIds:     pulumi.Any("[parameters('owners')]"),
			ResourceScope:    pulumi.String("providers/Microsoft.Management/managementGroups/ContosoOnlineGroup"),
			RoleDefinitionId: pulumi.String("/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var roleAssignmentArtifact = new AzureNative.Blueprint.RoleAssignmentArtifact("roleAssignmentArtifact", new()
    {
        ArtifactName = "ownerAssignment",
        BlueprintName = "simpleBlueprint",
        DisplayName = "enforce owners of given subscription",
        Kind = "roleAssignment",
        PrincipalIds = "[parameters('owners')]",
        ResourceScope = "providers/Microsoft.Management/managementGroups/ContosoOnlineGroup",
        RoleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.blueprint.RoleAssignmentArtifact;
import com.pulumi.azurenative.blueprint.RoleAssignmentArtifactArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var roleAssignmentArtifact = new RoleAssignmentArtifact("roleAssignmentArtifact", RoleAssignmentArtifactArgs.builder()
            .artifactName("ownerAssignment")
            .blueprintName("simpleBlueprint")
            .displayName("enforce owners of given subscription")
            .kind("roleAssignment")
            .principalIds("[parameters('owners')]")
            .resourceScope("providers/Microsoft.Management/managementGroups/ContosoOnlineGroup")
            .roleDefinitionId("/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7")
            .build());

    }
}

resources:
  roleAssignmentArtifact:
    type: azure-native:blueprint:RoleAssignmentArtifact
    properties:
      artifactName: ownerAssignment
      blueprintName: simpleBlueprint
      displayName: enforce owners of given subscription
      kind: roleAssignment
      principalIds: '[parameters(''owners'')]'
      resourceScope: providers/Microsoft.Management/managementGroups/ContosoOnlineGroup
      roleDefinitionId: /providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7

When the blueprint deploys, Azure creates role assignments for each principal ID in the array. The principalIds property uses blueprint parameter syntax ([parameters('owners')]) to accept user or group identities at deployment time. The roleDefinitionId points to the built-in Owner role, and resourceScope targets a management group, applying the assignment across all subscriptions within that hierarchy. The kind property must be set to “roleAssignment” to identify this artifact type.

Assign roles to principals at subscription scope

When blueprints target a single subscription rather than a management group hierarchy, role assignments scope to that subscription’s resources.

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const roleAssignmentArtifact = new azure_native.blueprint.RoleAssignmentArtifact("roleAssignmentArtifact", {
    artifactName: "ownerAssignment",
    blueprintName: "simpleBlueprint",
    displayName: "enforce owners of given subscription",
    kind: "roleAssignment",
    principalIds: "[parameters('owners')]",
    resourceScope: "subscriptions/00000000-0000-0000-0000-000000000000",
    roleDefinitionId: "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
});

import pulumi
import pulumi_azure_native as azure_native

role_assignment_artifact = azure_native.blueprint.RoleAssignmentArtifact("roleAssignmentArtifact",
    artifact_name="ownerAssignment",
    blueprint_name="simpleBlueprint",
    display_name="enforce owners of given subscription",
    kind="roleAssignment",
    principal_ids="[parameters('owners')]",
    resource_scope="subscriptions/00000000-0000-0000-0000-000000000000",
    role_definition_id="/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7")

package main

import (
	blueprint "github.com/pulumi/pulumi-azure-native-sdk/blueprint/v3"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := blueprint.NewRoleAssignmentArtifact(ctx, "roleAssignmentArtifact", &blueprint.RoleAssignmentArtifactArgs{
			ArtifactName:     pulumi.String("ownerAssignment"),
			BlueprintName:    pulumi.String("simpleBlueprint"),
			DisplayName:      pulumi.String("enforce owners of given subscription"),
			Kind:             pulumi.String("roleAssignment"),
			PrincipalIds:     pulumi.Any("[parameters('owners')]"),
			ResourceScope:    pulumi.String("subscriptions/00000000-0000-0000-0000-000000000000"),
			RoleDefinitionId: pulumi.String("/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using AzureNative = Pulumi.AzureNative;

return await Deployment.RunAsync(() => 
{
    var roleAssignmentArtifact = new AzureNative.Blueprint.RoleAssignmentArtifact("roleAssignmentArtifact", new()
    {
        ArtifactName = "ownerAssignment",
        BlueprintName = "simpleBlueprint",
        DisplayName = "enforce owners of given subscription",
        Kind = "roleAssignment",
        PrincipalIds = "[parameters('owners')]",
        ResourceScope = "subscriptions/00000000-0000-0000-0000-000000000000",
        RoleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.azurenative.blueprint.RoleAssignmentArtifact;
import com.pulumi.azurenative.blueprint.RoleAssignmentArtifactArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var roleAssignmentArtifact = new RoleAssignmentArtifact("roleAssignmentArtifact", RoleAssignmentArtifactArgs.builder()
            .artifactName("ownerAssignment")
            .blueprintName("simpleBlueprint")
            .displayName("enforce owners of given subscription")
            .kind("roleAssignment")
            .principalIds("[parameters('owners')]")
            .resourceScope("subscriptions/00000000-0000-0000-0000-000000000000")
            .roleDefinitionId("/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7")
            .build());

    }
}

resources:
  roleAssignmentArtifact:
    type: azure-native:blueprint:RoleAssignmentArtifact
    properties:
      artifactName: ownerAssignment
      blueprintName: simpleBlueprint
      displayName: enforce owners of given subscription
      kind: roleAssignment
      principalIds: '[parameters(''owners'')]'
      resourceScope: subscriptions/00000000-0000-0000-0000-000000000000
      roleDefinitionId: /providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7

This configuration mirrors the management group example but changes resourceScope to target a specific subscription. The role assignment applies only to resources within that subscription. The principalIds and roleDefinitionId properties work identically, pulling principal identities from blueprint parameters and referencing Azure’s built-in role definitions.

Beyond these examples

These snippets focus on specific role assignment artifact features: role assignment at management group and subscription scopes, and parameter-driven principal assignment. They’re intentionally minimal rather than full blueprint definitions.

The examples reference pre-existing infrastructure such as Azure Blueprints (blueprintName references), management groups or subscriptions (resourceScope targets), and blueprint parameters for principal IDs. They focus on configuring the role assignment artifact rather than defining the complete blueprint.

To keep things focused, common artifact patterns are omitted, including:

  • Resource group scoping (resourceGroup property)
  • Artifact dependencies (dependsOn for deployment ordering)
  • Custom role definitions (examples use built-in Owner role)
  • Display names and descriptions for documentation

These omissions are intentional: the goal is to illustrate how role assignment artifacts are wired, not provide drop-in blueprint modules. See the RoleAssignmentArtifact resource reference for all available configuration options.

Let's configure Azure Blueprint Role Assignment Artifacts

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Configuration & Scope
What properties are required to create a role assignment artifact?
You must specify kind (set to “roleAssignment”), principalIds (array of Azure AD user/group identities), and roleDefinitionId (Azure resource ID of the role definition).
What's the difference between management group and subscription scope?
Use resourceScope with management group format (/providers/Microsoft.Management/managementGroups/{managementGroup}) to apply the role assignment across multiple subscriptions, or subscription format (/subscriptions/{subscriptionId}) to apply it to a single subscription.
How do I scope a role assignment to a specific resource group?
Set the resourceGroup property to the target resource group name. If you leave resourceGroup empty, the role assignment scopes to the entire subscription.
Can I use blueprint parameters for principal IDs?
Yes, you can reference blueprint parameters using the syntax [parameters('parameterName')], as shown in the examples with [parameters('owners')].
Immutability & Lifecycle
What properties can't be changed after creating the artifact?
The artifactName, blueprintName, and resourceScope properties are immutable and cannot be modified after creation. You’ll need to recreate the artifact to change these values.
Dependencies & Ordering
How do I ensure artifacts deploy in a specific order?
Use the dependsOn property to specify an array of artifact names that must be deployed before this role assignment artifact.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides GCP Guides