Azure Activation Guide

This guide explains how to prepare Azure so the in-app environment wizard (Configuration → Credentials → Validation → Review & create) can create infrastructure successfully.

Core idea: every value you paste into the wizard is an output of Azure setup. Prepare Azure first (usually with the Azure CLI), then copy IDs and secrets into the product.

Quick path

1. Sign in with your user account and select the correct subscription (§ Sign in and select the subscription).
2. Create or reuse an app registration / service principal and save Client ID, Client Secret (value), and Tenant ID (§ Service principal).
3. Grant the service principal Contributor on that subscription (§ RBAC).
4. Register Microsoft.ContainerRegistry and Microsoft.App (§ Resource providers).
5. Log in as the service principal and confirm subscription access (§ Verify the service principal).
6. Open the wizard: Configuration → Credentials → run Validation → Review & create (§ Complete the wizard).
7. If something fails, use § Common issues.

Prerequisites

• Access to the target Azure subscription.
• Permission to assign RBAC (for example Owner or User Access Administrator) when granting the service principal access.
• Azure CLI installed locally, or Azure Cloud Shell.

The CLI is recommended because portal labels and layout change more often than command-line flows.

Field reference

The wizard matches Azure outputs like this:

Subscription ID vs Tenant ID: both look like GUIDs (for example eb620971-347b-41f1-bb45-e9c8b4f5020d), but they are different. Subscription ID belongs in Configuration; Tenant ID belongs in Credentials.

Region: use a valid Azure region identifier (lowercase, no spaces). List names for your subscription:

az account list-locations --query "[].name" -o tsv

Prepare Azure with the CLI

Run the steps below as your Azure user/admin unless noted. Replace placeholders such as <SUBSCRIPTION_ID> and <CLIENT_ID> with your values.

Sign in and select the subscription

az login
az account list --output table
az account set --subscription <SUBSCRIPTION_ID>
az account show --output json

From the JSON output, record:

• subscription.id → Subscription ID
• tenantId → Tenant ID

Create or reuse a service principal

Reuse an existing app registration if you already have one.

Option A — new service principal (quick setup):

az ad sp create-for-rbac --name <APP_NAME>

Note appId (Client ID), password (Client Secret), and tenant (Tenant ID). Save the secret immediately; it is not shown again.

Option B — portal: create an app registration in Microsoft Entra ID, add a client secret under Certificates & secrets, and copy the Value column (not the Secret ID).

Option C — new secret for an existing app:

az ad app credential reset --id <CLIENT_ID> --append

Use --append when rotating so Azure adds a second credential instead of replacing existing credentials. In production, prefer adding a second secret, updating the wizard, verifying deployment, then removing the old secret.

Entra secrets expire. When one expires, create a new secret and update Client Secret in the wizard.

Grant RBAC on the subscription

Validation needs the service principal to read the subscription; provisioning needs permissions to create resources (resource groups, Container Apps, registries, etc.). Contributor at subscription scope is the usual choice.

az login
az account set --subscription <SUBSCRIPTION_ID>

az role assignment create \
  --assignee <CLIENT_ID> \
  --role Contributor \
  --scope /subscriptions/<SUBSCRIPTION_ID>

Verify:

az role assignment list \
  --assignee <CLIENT_ID> \
  --scope /subscriptions/<SUBSCRIPTION_ID> \
  --output table

You should see Contributor for that service principal on the subscription.

For tighter least privilege, some organizations scope Contributor to a resource group instead of the whole subscription. That only works if all resources the worker creates stay inside that group.

Register resource providers

Provisioning fails if the subscription is not registered for the services in use. These namespaces are required for the MCP deployment path described here:

• Microsoft.ContainerRegistry
• Microsoft.App

az account set --subscription <SUBSCRIPTION_ID>

az provider register --namespace Microsoft.ContainerRegistry --wait
az provider register --namespace Microsoft.App --wait

Verify (each should print Registered):

az provider show --namespace Microsoft.ContainerRegistry --query registrationState -o tsv
az provider show --namespace Microsoft.App --query registrationState -o tsv

Depending on what the worker provisions, you may also need:

az provider register --namespace Microsoft.OperationalInsights --wait
az provider register --namespace Microsoft.ManagedIdentity --wait
az provider register --namespace Microsoft.Network --wait

Verify the service principal

This separates Azure misconfiguration from product issues.

az logout

az login --service-principal \
  --username <CLIENT_ID> \
  --password <CLIENT_SECRET_VALUE> \
  --tenant <TENANT_ID>

az account set --subscription <SUBSCRIPTION_ID>

az rest \
  --method get \
  --url "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>?api-version=2020-01-01"

If this returns subscription JSON, authentication and subscription access are working.

Complete the wizard in the app

Use the Field reference for definitions.

Configuration

• Environment Name — label in your app (for example azure).
• Subscription ID — Azure subscription GUID from § Sign in.

Credentials

• Tenant ID, Client ID, Client Secret (secret value), Region — from Entra and the service principal (§ Service principal, § Sign in).

Validation

Run validation in the UI. It should succeed when the secret is valid, tenant and subscription IDs are correct, and the service principal can read the subscription.

Review & create

After validation succeeds, finish creating the environment.

Common issues

Official references

• Create an Azure service principal with Azure CLI
• Azure resource providers and types
• Azure built-in roles
• Install the Azure CLI

Appendix: Copy-paste activation script

The block below repeats Prepare Azure with the CLI in one place for convenience. Replace placeholders before running.

# --- As your Azure user ---

az login
az account list --output table
az account set --subscription <SUBSCRIPTION_ID>

# RBAC (Contributor on subscription)
az role assignment create \
  --assignee <CLIENT_ID> \
  --role Contributor \
  --scope /subscriptions/<SUBSCRIPTION_ID>

az role assignment list \
  --assignee <CLIENT_ID> \
  --scope /subscriptions/<SUBSCRIPTION_ID> \
  --output table

# Required providers
az provider register --namespace Microsoft.ContainerRegistry --wait
az provider register --namespace Microsoft.App --wait

az provider show --namespace Microsoft.ContainerRegistry --query registrationState -o tsv
az provider show --namespace Microsoft.App --query registrationState -o tsv

# --- Test as the service principal ---

az logout

az login --service-principal \
  --username <CLIENT_ID> \
  --password <CLIENT_SECRET_VALUE> \
  --tenant <TENANT_ID>

az account set --subscription <SUBSCRIPTION_ID>

az rest \
  --method get \
  --url "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>?api-version=2020-01-01"

After this succeeds, fill the wizard using the Field reference and complete § Complete the wizard.