Fabric Prerequisites

This guide provides step-by-step instructions for configuring Microsoft Fabric prerequisites required by the provider to manage Fabric tenant settings, domains, and workload resources via the subscriptions.data.fabric configuration block.

These steps are in addition to the Azure Prerequisites and only required when the subscriptions.data block is configured on a tenancy.

The following prerequisites must be completed before deploying the data subscription template:

Activate Microsoft Fabric on the Tenant
Create the Fabric API Admin Security Group
Create the Fabric Admin Security Group (Optional)
Enable Admin API Access for Service Principals
GitHub PAT for Fabric Git Integration
GitHub EMU Entra ID App Role Assignments (EMU Orgs)
Tenant and Fabric Capacity Region Alignment (VNet Data Gateway)

Once these manual steps are completed, the data template handles everything else automatically (capacity creation, tenant settings, domains, workloads).

Warning

Do NOT add any Power BI Service API permissions (Application or Delegated) to the Service Principal app registration used by provider. Admin-consent required permissions on Power BI Service block the SP from authenticating to the Fabric Admin API. The SP relies solely on the admin portal toggle and capacity admin membership for authentication.

1. Activate Microsoft Fabric on the Tenant

Microsoft Fabric must be registered on the Entra ID tenant before the Fabric API (https://api.fabric.microsoft.com) becomes available.

Steps

Sign in with a Global Administrator account to https://app.fabric.microsoft.com
Complete the self-service sign-up when prompted

Notes

This is a one-time manual step per tenant
The sign-up registers the tenant with Microsoft's Fabric backend
No paid license or trial is required — the sign-up alone activates the Fabric API
Without tenant registration, capacity creation via azurerm_fabric_capacity fails with "Tenant wasn't recognized by Microsoft Fabric"

Warning

If self-service sign-up is disabled on the tenant (AllowAdHocSubscriptions = false), a Global Administrator must enable it first via PowerShell: shell Set-MsolCompanySettings -AllowAdHocSubscriptions $true

2. Create the Fabric API Admin Security Group

Create a security group in Entra ID to hold the Service Principal that runs Terraform. This group is used in the next step to scope the admin API access.

Naming Convention

Recommended Use: <tenancy_abbreviation>_microsoft_fabric_api_admin_role

The <tenancy_abbreviation> is the value configured in configuration.abbreviation of the <no value>_tenancy_azure resource.

This is separate from any human admin groups (e.g. <tenancy_abbreviation>_microsoft_fabric_admin_role) — it is specifically for programmatic API access by service principals.

Provider Configuration

The group name must be specified in subscriptions.data.fabric.admin_groups.api_admin:

fabric = {
  admin_groups = {
    api_admin = "<tenancy_abbreviation>_microsoft_fabric_api_admin_role"
  }
  # ... rest of fabric config
}

Using the Azure Portal

Navigate to Microsoft Entra ID > Groups > New group
Set the following values:
- Group type: Security
- Group name: <tenancy_abbreviation>_microsoft_fabric_api_admin_role
- Group description: "Service principals allowed to manage Fabric via Admin API"
Click Create
Open the group > Members > Add members
Search for the Service Principal (e.g. svp_terraform) and add it

Using the Azure CLI

# Create the security group
az ad group create \
  --display-name "<tenancy_abbreviation>_microsoft_fabric_api_admin_role" \
  --mail-nickname "<tenancy_abbreviation>-microsoft-fabric-api-admin-role" \
  --security-enabled true

# Get the SP object ID
SP_OBJECT_ID=$(az ad sp show --id <service-principal-client-id> --query id -o tsv)

# Add the SP to the group
az ad group member add \
  --group "<tenancy_abbreviation>_microsoft_fabric_api_admin_role" \
  --member-id "${SP_OBJECT_ID}"

3. Create the Fabric Admin Security Group (Optional)

Create a security group for human administrators who need visibility and management access to Fabric connections and workspaces. Members of this group receive Owner role on all Fabric connections and Admin role on all Fabric workspaces created by the module.

This group must be created manually because it requires assignable_to_role = true (for M365 role assignment), which needs Privileged Role Administrator permissions that the deployer service principal does not have.

Naming Convention

Recommended: <tenancy_abbreviation>_microsoft_fabric_admin_role

Using the Azure Portal

Navigate to Microsoft Entra ID > Groups > New group
Set the following values:
- Group type: Security
- Group name: <tenancy_abbreviation>_microsoft_fabric_admin_role
- Group description: "Human administrators for Fabric — Owner on connections, Admin on workspaces"
- Microsoft Entra roles can be assigned to the group: Yes
Click Create
Open the group > Members > Add members
Add the platform engineers / data engineers who need connection and workspace visibility

Using the Azure CLI

# Create the security group (assignable to roles)
az ad group create \
  --display-name "<tenancy_abbreviation>_microsoft_fabric_admin_role" \
  --mail-nickname "<tenancy_abbreviation>-microsoft-fabric-admin-role" \
  --security-enabled true \
  --is-assignable-to-role true

Assign the Fabric Administrator Role

Assign the Fabric Administrator Entra ID directory role to the group so its members can administer Fabric at the tenant level (view all workspaces, gateways, capacities, and tenant settings in the admin portal). This is why the group must be created with assignable_to_role = true.

Using the Azure Portal:

Navigate to Microsoft Entra ID > Roles and administrators
Search for and select Fabric Administrator
Select Add assignments
Add the <tenancy_abbreviation>_microsoft_fabric_admin_role group
Click Add

Using the Azure CLI:

# Get the group object ID
GROUP_ID=$(az ad group show \
  --group "<tenancy_abbreviation>_microsoft_fabric_admin_role" \
  --query id -o tsv)

# Assign the Fabric Administrator directory role to the group
az rest --method POST \
  --uri "https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments" \
  --headers "Content-Type=application/json" \
  --body "{
    \"principalId\": \"${GROUP_ID}\",
    \"roleDefinitionId\": \"a9ea8996-122f-4c74-9520-8edcd192826c\",
    \"directoryScopeId\": \"/\"
  }"

Note

a9ea8996-122f-4c74-9520-8edcd192826c is the well-known template ID for the Fabric Administrator role. Members of the group inherit the role, so you manage Fabric admins simply by adding or removing group members.

Provider Configuration

Add the group name to subscriptions.data.fabric.admin_groups.fabric_admin:

fabric = {
  admin_groups = {
    api_admin    = "<tenancy_abbreviation>_microsoft_fabric_api_admin_role"
    fabric_admin = "<tenancy_abbreviation>_microsoft_fabric_admin_role"
  }
  # ... rest of fabric config
}

If omitted, no admin connection or workspace role assignments are created.

4. Enable Admin API Access for Service Principals

Enable the Fabric Admin Portal toggle that allows service principals in the security group to call the admin APIs (read and update tenant settings).

Steps

Sign in to https://app.fabric.microsoft.com as a Fabric Administrator or Global Administrator
Navigate to Admin portal > Tenant settings
Scroll to Admin API settings
Expand "Service principals can access read-only admin APIs"
Set the toggle to Enabled
Select Specific security groups
Add the group created in Step 2 (e.g. <tenancy_abbreviation>_microsoft_fabric_api_admin_role)
Click Apply
Expand "Service principals can access admin APIs used for updates"
Set the toggle to Enabled
Select Specific security groups
Add the same group
Click Apply

Notes

This is a one-time manual configuration per tenant
Both the read-only and update admin API toggles must be enabled for the security group
These settings cannot be managed programmatically by the provider (chicken-and-egg — you need write access to enable write access)
Once enabled, the provider can manage all other tenant settings
Allow up to 15 minutes for the toggles to propagate before first deployment

5. GitHub PAT for Fabric Git Integration

When using GitHub as the git provider for Fabric workspaces, a Personal Access Token (PAT) must be created and stored in the data subscription Key Vault.

PAT Requirements

Token type: Personal access token (classic)
Scopes: admin:org, delete_repo, repo
Expiration: Set an appropriate expiry (recommend 1 year, with rotation)

SAML SSO Authorization (Required for EMU Orgs)

If the GitHub organization uses Enterprise Managed Users (EMU) with SAML SSO enforcement, the PAT must be authorized for the organization:

Navigate to GitHub > Settings > Developer settings > Personal access tokens > Tokens (classic)
Find the PAT created for Fabric integration
Click Configure SSO
Click Authorize next to the target organization

Warning

Without SAML authorization, all Fabric GitHub operations (repo creation, team management, EMU group mappings) will fail with 403 Resource protected by organization SAML enforcement.

Store the PAT in Key Vault

Store the PAT in the data subscription Key Vault before first deployment:

az keyvault secret set \
  --vault-name "<keyvault-name>" \
  --name "<kv_secret_name>" \
  --value '<PAT-value>'

The kv_secret_name must match the value configured in fabric.git_provider.github.kv_secret_name in the provider configuration. Secret names can only contain alphanumeric characters and dashes.

6. GitHub EMU Entra ID App Role Assignments (EMU Orgs)

When using GitHub EMU, the Fabric workspace security groups created by the provider must be provisioned into GitHub so that workspace group members appear as members of the corresponding GitHub teams. This is a manual prerequisite the customer owns.

Why This Is Required

The provider creates Entra ID security groups per Fabric workspace role (admin, contributor, member, viewer). For SCIM to sync these groups and their members to GitHub, the groups must be assigned the "User" app role on the GitHub EMU (OIDC) enterprise application in Entra ID, and mapped to GitHub teams. Without this, users added to workspace groups won't appear as members of the corresponding GitHub teams.

The provider cannot automate this — the GitHub EMU app is a Microsoft-published multi-tenant application, so the deployer service principal cannot own it or assign app roles on it.

What the Customer Needs to Ensure

The customer completes these two tasks using whatever method they prefer (Azure portal, CLI, Terraform, or their existing identity tooling):

Entra app role assignment — assign each Fabric workspace security group the "User" app role on the GitHub EMU enterprise application, so SCIM provisions the groups into GitHub.
GitHub team mapping — map each provisioned group to its corresponding GitHub team (external group mapping) so members flow through to the team.

An org owner PAT (stored in Key Vault, per section 5) is required for the group-to-team mapping, since it reads external groups which needs organization owner permissions.

7. Tenant and Fabric Capacity Region Alignment (VNet Data Gateway)

When using the VNet Data Gateway for private connectivity to data sources, the Power Platform environment region must match the Fabric capacity region (and therefore the Azure VNET region).

Why This Is Required

The VNet Data Gateway runs inside a delegated subnet in your Azure VNET. The Power Platform backend only allows gateway creation in Azure regions that are associated with an existing Power Platform environment. If the Power Platform environment is in a different region than the VNET, the gateway creation will fail with PowerPlatformVirtualNetworkSubnetNotConfiguredForDelegation.

What Must Match

Component	Region	Example
Power Platform environment	Must cover the Azure region	`australia`
Fabric capacity	Azure region	`australiaeast`
Azure VNET + delegated subnet	Same Azure region as capacity	`australiaeast`

Notes

Most Azure tenants already have a default Power Platform environment in the tenant's home region
If the tenant's home region matches the Fabric capacity region (e.g. Australian tenant + Australia East capacity), the gateway works without any additional configuration
If there is a mismatch (e.g. US-based tenant with an Australian capacity), a Power Platform environment must be manually created in the matching region via the Power Platform admin center