Prerequisites¶

This page lists what must be in place before the portal can be deployed into an environment. It is written for the platform team and for the people who fulfil each item on the customer side. In the self-managed operating model the platform team fulfils all items itself; see Operating models.

This is a reference design: confirm the values with the engineer who deploys, because your environment may differ. Items marked (for: feature) are needed only when that feature is in scope.

Summary¶

Area	Item
Azure	Two subscriptions (non-production and production), a deployment identity with Owner on each
Network	VNet and subnets per environment, outbound HTTPS to Azure control plane and Microsoft Graph
Identity	Entra app registration per environment, Graph application permissions for the managed identity
Access	Reader roles for the portal's managed identity
Repositories	Read access to repositories to ingest, contribute access on the configuration repositories
Providers	Resource providers registered where AI Foundry or cost exports are used
Optional	DNS zone and certificate, WAF, GitHub App, private module registry

Azure subscriptions and deployment identity¶

Two Azure subscriptions, one for the non-production and one for the production environment.
A deployment service principal for each subscription with the Owner role. Federated credentials are preferred over client secrets (Deployment and environments).
(for: AI agents) These resource providers registered on the subscription that hosts AI Foundry: Microsoft.App, Microsoft.ContainerService, Microsoft.CognitiveServices, Microsoft.KeyVault, Microsoft.Network, Microsoft.Search, Microsoft.Storage. The Terraform module for Foundry also registers resource providers; see AI setup.
(for: cost insights) Microsoft.CostManagement registered on every subscription that is in scope. The portal does not register providers. Without registration it skips that subscription and tries again on the next run.

az provider register --namespace Microsoft.CostManagement --subscription <subscription-id>

Network¶

Create one virtual network per environment and region, with a non-overlapping address range. In a managed platform this is a spoke (Spoke canvas).

Subnet	Example range	Purpose
default	`10.x.x.0/26`	Private endpoints, for example storage and key vault
app service (delegated)	`10.x.x.64/26`	VNet integration of the web app
agents (delegated to `Microsoft.App/environments`)	`10.x.x.128/27`	Only for AI agents that use bring-your-own Foundry resources
PostgreSQL (delegated)	`10.x.x.160/28`	PostgreSQL Flexible Server

Rules:

Keep the purposes separate. Do not put web app integration and PostgreSQL in the same subnet.
A Container Apps environment with workload profiles needs a dedicated delegated subnet of at least /27.
Reserve free address space for growth and for network controls that the customer requires.
In a hub-and-spoke network, routes and firewall rules must allow the web app subnet to reach:
- outbound HTTPS to the service tags AzureResourceManager, AzureActiveDirectory and AzureMonitor
- outbound HTTPS to graph.microsoft.com

Subnet names differ between sources

The reference Terraform names its subnets default, appsvc, postgresql and containerapp. The human-readable guidance uses different names. Use the names that your Terraform expects and check them with the engineer.

Role assignments for the portal's managed identity¶

After the first deployment, grant the portal's managed identity read access to the Azure estate. The scopes below assume a management group hierarchy that follows the Cloud Adoption Framework. Narrower scopes are possible.

Role	Scope	Why
Reader	Landing zones management group (or the group that contains the workloads to ingest)	Discovers subscriptions and resources, and the workload, team, domain and organisation groupings derived from tags. New subscriptions under the scope are picked up automatically.
Reader	Scope that contains the Azure Firewall resources	Discovers firewalls whose logs the portal queries
Monitoring Reader	Same scope as the previous row	Log Analytics queries for firewalls
Reader	Scope that contains the Application Gateways	Discovers gateways
Monitoring Reader	Same scope as the previous row	Log Analytics queries for gateways
Cost Management Contributor (for: cost insights)	Landing zones management group, or the scope with the in-scope subscriptions	Creates and runs a Cost Management export per subscription

The Terraform modules also assign roles for the portal's identities to the environment's own resources (Key Vault secrets user, registry pull, cost export storage roles).

Entra app registration¶

Create one app registration per environment (for example acceptance and production).

Item	Value
Delegated Graph permissions	`email`, `offline_access`, `openid`, `profile`, `User.Read`, with admin consent
Redirect URI	`https://<portal-domain>/api/auth/microsoft/handler/frame`

Choose how the secret and redirect URI are managed:

Recommended: make the deployment service principal owner of the app registration and its enterprise application, and give it the Graph application permission Application.Read.All. The deployment then rotates the secret and adds redirect URIs automatically.
Alternative: create the client secret by hand and add the redirect URI yourself.

After the first deployment an Entra administrator grants the portal's managed identity these Graph application permissions with admin consent, so the catalog can ingest users and groups:

User.Read.All
GroupMember.Read.All

Hand over a script

This step needs administrator rights in the tenant. Give the Entra administrator a script instead of a list.

Repositories¶

Read access for the portal's identity on the Azure DevOps repositories whose catalog-info.yaml files should be ingested.
Contribute access on the configuration repositories that agents change (spoke and integration configuration). The access must include reading main, creating branches and opening pull requests. The identity also needs a Basic access level in the Azure DevOps organisation.
(for: GitHub integration) A GitHub App at organisation or enterprise level, with read and write on contents and pull requests. See Configuration.

Optional items¶

Item	When
DNS zone, CNAME or A record and a TLS certificate	Custom domain (WAF and custom domain)
Web Application Firewall in front of the portal	In place before deployment starts, if the customer wants one
Resource tags on workloads, with agreed keys	Always. The catalog is built from tags (Catalog and entity model)
Private module registry	Module registry
Private connections from the provider network	When the provider deploys from its own network (Onboarding a customer)

Who does what¶

Role	Responsibility
Delivery manager (provider)	Customer communication, kick-off, tracking, acceptance
Engineer (provider or customer platform team)	Prepares the environment definition, deploys, demonstrates at hand-over
Second engineer	Validates the deployment, a different person from the one who deployed
Solution lead	Decides whether a request fits the shared code base
Customer project manager	Single contact, owns the questionnaire, signs acceptance
Cloud platform administrator	Subscriptions, service principals, network, role assignments
Entra administrator	App registrations, admin consent, Graph permissions
Azure DevOps and GitHub administrator	Repository access, GitHub App
Security contact	Reviews data residency and the access model
Developer representative (optional)	Attends the MCP walkthrough

In the self-managed model, one team can hold several of these roles.