Skip to the content.

← back to home

Wires this platform to an Azure subscription: the identity it authenticates with, the permissions it needs, and the storage account that holds Terraform state. When you finish, the platform is ready for its first Azure - Provision & Reconcile Application Resources run.

Do the GitHub setup first. This guide assumes the repository is already on GitHub and its dev / staging / prod Environments exist — the federated credentials below are scoped to that repository slug and those environment names.

It assumes you have Owner rights on the target Azure subscription.

What you’ll end up with

Estimated time: 10–15 minutes the first time.


Prerequisites

Tooling on your workstation, on top of what the GitHub guide lists:

Tool Minimum version Notes
az 2.60 App Registration + RBAC + federated credentials
jq (optional) 1.6 Useful for inspecting az output

Azure access:


Step 1 — Create the Azure App Registration

# Sign in to the right tenant if you have several
az login

# Make sure you're operating against the intended subscription
az account set --subscription "<your-subscription-id-or-name>"

# Create the App Registration
az ad app create --display-name "sp-platform-eng-github"

# Capture the appId — this is the value you'll pass as `azure_client_id`
APP_ID=$(az ad app list \
  --display-name "sp-platform-eng-github" \
  --query "[0].appId" -o tsv)

# Create the matching Service Principal in your tenant
az ad sp create --id "$APP_ID"

# Capture the SP object ID — needed for RBAC role assignments
SP_OBJECT_ID=$(az ad sp show --id "$APP_ID" --query id -o tsv)

# Capture the tenant ID — you'll pass this as `azure_tenant_id`
TENANT_ID=$(az account show --query tenantId -o tsv)

# Capture the subscription ID — you'll pass this as `azure_subscription_id`
SUBSCRIPTION_ID=$(az account show --query id -o tsv)

cat <<EOF

Save these three values — you'll feed them to the workflow as inputs:

  azure_tenant_id : $TENANT_ID
  azure_subscription_id : $SUBSCRIPTION_ID
  azure_client_id : $APP_ID

  (SP object ID, only used in the next steps: $SP_OBJECT_ID)
EOF

Tip. The App Registration’s appId and the Service Principal’s objectId are different identifiers. RBAC assignments and federated credentials work with the SP. Keep both handy.


Step 2 — Configure federated credentials (OIDC)

The workflows authenticate to Azure with short-lived OIDC tokens issued by GitHub Actions. Azure validates each token against a federated credential on the App Registration. The token’s subject claim must match exactly.

You need four credentials because two different subject formats apply:

Credential Used by Subject
Branch-scoped every job in provision-infrastructure.yml without an environment: key — resolve-inputs, preflight, fmt, checkov, bootstrap-tfstate, create-app-repo, create-run-issue, configure-environments, configure-federated-credentials, observe-ci, finalize; and the standalone bootstrap-tfstate.yml repo:<org>/<repo>:ref:refs/heads/main
Environment dev every job pinned to environment: dev — plan, apply, the verify-infrastructure.yml reusable workflow repo:<org>/<repo>:environment:dev
Environment staging same set of jobs, pinned to environment: staging repo:<org>/<repo>:environment:staging
Environment prod same set of jobs, pinned to environment: prod repo:<org>/<repo>:environment:prod

Check your repo’s subject format first. GitHub embeds immutable IDs in the subject claim of any repository created (or renamed/transferred) after July 15, 2026: the prefix becomes repo:<org>@<owner-id>/<repo>@<repo-id> instead of repo:<org>/<repo>, and Entra matches subjects verbatim. Query the exact prefix your platform repo presents and use it in the four subjects below:

gh api "repos/$REPO/actions/oidc/customization/sub" --jq .sub_claim_prefix

The snippets below assume the legacy prefix, which is what a platform repo created before that date presents. The app repos the platform creates need no such care from you — the configure-federated-credentials job queries each new repo’s actual prefix before registering its credentials.

Create all four:

REPO="<your-org>/<repo-name>"   # e.g. deors/workshop-platform-eng

# 1. Branch-scoped credential (bootstrap jobs)
az ad app federated-credential create --id "$APP_ID" --parameters '{
  "name":     "github-main-branch",
  "issuer":   "https://token.actions.githubusercontent.com",
  "subject":  "repo:'"$REPO"':ref:refs/heads/main",
  "audiences": ["api://AzureADTokenExchange"]
}'

# 2-4. One credential per GitHub Environment
for ENV in dev staging prod; do
  az ad app federated-credential create --id "$APP_ID" --parameters '{
    "name":     "github-env-'"$ENV"'",
    "issuer":   "https://token.actions.githubusercontent.com",
    "subject":  "repo:'"$REPO"':environment:'"$ENV"'",
    "audiences": ["api://AzureADTokenExchange"]
  }'
done

# Verify
az ad app federated-credential list --id "$APP_ID" \
  --query "[].{name:name, subject:subject}" -o table

You should see exactly four rows.


Step 3 — Assign Azure RBAC roles

The Service Principal needs two roles at subscription scope. The second one — Storage Blob Data Contributor — is the easy-to-miss one: the bootstrap script creates the state storage account with allow-shared-key-access=false, so the only way the script can then create the container is via RBAC. The role must be in place before the first run.

SCOPE="/subscriptions/$SUBSCRIPTION_ID"

# Manage control-plane resources (RGs, App Service, networking, …)
az role assignment create \
  --assignee-object-id      "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role  "Contributor" \
  --scope "$SCOPE"

# Read/write state blobs (Contributor does NOT cover the data plane).
# The condition document (checked into this repo) restricts the grant to
# blobs in containers named `tfstate` — every platform state container has
# that fixed name, so the SP can touch state files and no other blob data.
# Run this from a checkout of this repo.
az role assignment create \
  --assignee-object-id      "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role  "Storage Blob Data Contributor" \
  --scope "$SCOPE" \
  --condition "$(cat setup/azure-policies/sbdc-tfstate-containers-only.condition.txt)" \
  --condition-version "2.0"

# Verify
az role assignment list --assignee "$SP_OBJECT_ID" --scope "$SCOPE" \
  --query "[].roleDefinitionName" -o table

Expected output:

Result
-------------------------------
Contributor
Storage Blob Data Contributor

Why subscription scope? During bootstrap the resource group and storage account don’t exist yet, so any role on a narrower scope wouldn’t apply. Once we evolve the platform to provision infrastructure for many apps in many subscriptions, this RBAC model will be revisited (likely a per-subscription identity rather than a single shared SP).

What the SP deliberately cannot do. Neither role can create role assignments — Contributor excludes Microsoft.Authorization/*/write — so the identity GitHub Actions becomes can never grant itself (or anyone else) additional access, and the conditioned data-plane grant keeps it out of every blob that is not a Terraform state file. The default platform path never needs more: Key Vault access policies are control-plane writes Contributor covers, and the only role assignment the webapp template can create is gated on pulling from Azure Container Registry with managed identity (see below).

Only if your apps pull from Azure Container Registry with managed identity

When the container registry URL ends in .azurecr.io and no registry username is supplied, the webapp template grants the app’s managed identity AcrPull on your registry — a role assignment, which the two baseline roles cannot create. Grant the SP delegation power constrained to exactly that one role (the condition document is checked into this repo):

# From a checkout of this repo
az role assignment create \
  --assignee-object-id      "$SP_OBJECT_ID" \
  --assignee-principal-type ServicePrincipal \
  --role  "Role Based Access Control Administrator" \
  --scope "$SCOPE" \
  --condition "$(cat setup/azure-policies/rbac-admin-acrpull-only.condition.txt)" \
  --condition-version "2.0"

The condition limits the delegation to creating and deleting AcrPull assignments only (7f951dda-4ed3-4680-a7ca-43fe172d538d) — the SP cannot hand out Owner, Contributor, or anything else. With the default ghcr.io registry this section does not apply; skip it.

Recorded decision — Contributor stays at subscription scope. A custom role limited to the resource providers the template uses (the Azure twin of the AWS guide’s scoped policy set) is deliberately deferred: resource groups are created dynamically so narrower scoping is impossible, every new template capability would mean maintaining the provider list, and with User Access Administrator gone Contributor cannot be escalated. Revisit if the platform outgrows the workshop.

Allow the SP to manage its own federated credentials

After the platform provisions infrastructure for a new app, it must register three additional federated credentials on this same App Registration — one per environment, scoped to the new app repo (subjects repo:<owner>/<app>:environment:{dev,staging,prod}, or the immutable-ID variant repo:<owner>@<id>/<app>@<id>:environment:{…} that GitHub mints for repos created after July 15, 2026 — the workflow queries the new repo for whichever prefix it actually presents). Without these, deploy workflows in the new repo fail at azure/login with AADSTS700213.

The platform workflow does this automatically (see job configure-federated-credentials), but the SP needs two things to be allowed to write to its own App Registration:

  1. Self-ownership of the App Registration object (directory-level), and
  2. The Application.ReadWrite.OwnedBy application permission on Microsoft Graph, with admin consent.

Ownership alone is sufficient for user-delegated flows but not for application-only flows like the OIDC token a workflow runs under, even in your own tenant — the corporate Entra default policy denies the call with Insufficient privileges to complete the operation.

The infrastructure template also creates Entra objects during apply: two app registrations per environment (the sign-in app app-<app>-<env> and its end-to-end test client app-<app>-<env>-e2e, both owned by this SP) and the role assignment that lets the test client call the API. That takes two more Graph application permissions, granted the same way:

Permission Used for
Application.ReadWrite.OwnedBy federated credentials on this SP; the app registrations the template creates (it owns them)
AppRoleAssignment.ReadWrite.All assigning the test client to the E2E.Access role of the sign-in app
Application.Read.All reading the service principals and roles involved in that assignment

1. Add the SP as owner of its own App Registration

APP_OBJECT_ID=$(az ad app show --id "$APP_ID" --query id -o tsv)

az ad app owner add \
  --id              "$APP_OBJECT_ID" \
  --owner-object-id "$SP_OBJECT_ID"

# Verify
az ad app owner list --id "$APP_OBJECT_ID" --query "[].id" -o tsv

2. Grant the Microsoft Graph application permissions

This step requires admin consent in the tenant: a Global Administrator, Privileged Role Administrator, Cloud Application Administrator, or Application Administrator must run it (or grant consent in the portal). In a corporate tenant this typically means filing an internal request.

# Microsoft Graph's well-known appId
GRAPH_APP_ID="00000003-0000-0000-c000-000000000000"
GRAPH_SP_ID=$(az ad sp show --id "$GRAPH_APP_ID" --query id -o tsv)

for PERMISSION in Application.ReadWrite.OwnedBy AppRoleAssignment.ReadWrite.All Application.Read.All; do
  # AppRoleId of the permission on Graph
  ROLE_ID=$(az ad sp show --id "$GRAPH_APP_ID" \
    --query "appRoles[?value=='${PERMISSION}'].id | [0]" -o tsv)

  # Grant it (admin consent required to execute this call)
  az rest --method POST \
    --uri "https://graph.microsoft.com/v1.0/servicePrincipals/${SP_OBJECT_ID}/appRoleAssignments" \
    --headers "Content-Type=application/json" \
    --body "{
      \"principalId\": \"${SP_OBJECT_ID}\",
      \"resourceId\":  \"${GRAPH_SP_ID}\",
      \"appRoleId\":   \"${ROLE_ID}\"
    }"
done

# Verify — one row per permission granted above
az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/${SP_OBJECT_ID}/appRoleAssignments" \
  --query "value[].{resource:resourceDisplayName, roleId:appRoleId}" -o table

Portal alternative

Entra ID → App registrations → your app → API permissions → Add a permission → Microsoft Graph → Application permissions → tick Application.ReadWrite.OwnedBy, AppRoleAssignment.ReadWrite.All and Application.Read.All → Add. Then click Grant admin consent for <tenant>.

Why OwnedBy and not All? Application.ReadWrite.OwnedBy only lets the SP write to App Registrations where it is an owner (set in step 1 above, and automatic for the ones the template creates). Application.ReadWrite.All would let it write to any App Registration in the tenant — a much wider blast radius. AppRoleAssignment.ReadWrite.All has no owner-scoped variant, which is why it is listed separately rather than folded into a broader grant.

Bootstrap storage account — security model

The state storage account is created with:

If your threat model requires network-level isolation, switch to a Private Endpoint and run the workflows on a self-hosted runner inside the VNet. That trade-off is intentionally out of scope for the workshop baseline.

Backend implication. Because the SA forbids shared-key auth, the azurerm backend must also be told to use Azure AD against the blob endpoint (not just for credential acquisition). The workflow sets both use_oidc=true and use_azuread_auth=true (plus ARM_USE_AZUREAD=true). Without the second flag, tofu init hits 403 KeyBasedAuthenticationNotPermitted even with a valid OIDC token.

Web App network exposure — per-environment policy

Application Web Apps follow a deliberate per-env split:

Env Private Endpoint Public endpoint Rationale
dev enabled enabled GitHub-hosted runners are not in the VNet and have no fixed egress IP. The dev environment intentionally accepts public traffic so the application repo’s CI/CD can run an HTTP smoke test against https://<webapp>.azurewebsites.net/health after each deploy.
staging enabled disabled PE-only. Mirrors the production posture so any data flowing through staging is treated with the same network sensitivity as prod.
prod enabled disabled PE-only. The only path in is from the integration subnet via the private endpoint.

The toggle is a module variable, public_network_access_enabled (default false). Dev sets it to true explicitly; staging/prod inherit the secure default. CKV_AZURE_222 (Public network access disabled) is enforced for prod and skipped for dev/staging in .checkov.nonprod.yaml so the dev exception doesn’t fail policy.

Deploy validation strategy

The application repository ships two top-level workflows that both delegate to a reusable deploy.yml:

Operators who need real HTTP smoke tests against PE-only environments should run the deploy/release workflows on a self-hosted runner inside webapp_integration_subnet (or a peered VNet). Out of scope for the workshop baseline.


Step 4 — Trigger the first run

In the GitHub UI: Actions → Azure - Provision & Reconcile Application Resources → Run workflow, and provide:

Input Required Value for the first test
app_name yes test-webapp (3–22 chars, lowercase, digits, hyphens)
environment yes dev — promotion order is enforced: staging can only be requested once dev is provisioned, prod once dev and staging both are ready (requesting all, or reconciling an environment that already exists, always passes)
azure_tenant_id no* the tenant GUID captured in step 1 — falls back to the PROVISION_AZURE_TENANT_ID repository variable
azure_subscription_id no* the GUID captured in step 1 — falls back to PROVISION_AZURE_SUBSCRIPTION_ID
azure_client_id no* the appId captured in step 1 — falls back to PROVISION_AZURE_CLIENT_ID
azure_location no* westeurope — Azure region for the tfstate storage account and every provisioned resource; falls back to PROVISION_AZURE_LOCATION. There is deliberately no built-in default: an implicit region silently deploys to the wrong place
infra_template_repo yes the <owner>/<name> of the infrastructure template repo
infra_template_ref no (leave empty — uses the template’s default branch) git ref (tag, branch, or commit SHA) to pin the infra template
app_template_repo no the <owner>/<name> of the application template repo; leave empty to skip the app-repo phase (infra-only run)
app_template_ref no (leave empty — uses the template’s default branch) git ref (tag, branch, or commit SHA) to pin the app template
container_image yes image reference without the registry host, e.g. deors/template-helloworld-express:sha-af53b68. The archetype fixes the container contract — port 8080, health endpoint /health; the image must follow it
container_registry_url no (leave empty — defaults to ghcr.io) registry host for the image
ci_workflow_file no (leave empty — defaults to ci.yml; only used when app_template_repo is set)

Reconcile caveat. container_image only matters on the first apply — afterwards CI/CD workflows own the deployed container image.

* no* = optional per run, but a value must come from somewhere: the input always overrides the repository variable, and when neither is present the run fails fast naming both ways to supply it. See Lock in the target cloud below.

In most organizations the target cloud is locked in, so passing the same identity parameters on every request is boilerplate. Set them once as repository variables and every form/CLI/API request can omit them:

gh variable set PROVISION_AZURE_TENANT_ID       -R <org>/<platform-repo> --body "<tenant-guid>"
gh variable set PROVISION_AZURE_SUBSCRIPTION_ID -R <org>/<platform-repo> --body "<subscription-guid>"
gh variable set PROVISION_AZURE_CLIENT_ID       -R <org>/<platform-repo> --body "<client-guid>"
gh variable set PROVISION_AZURE_LOCATION        -R <org>/<platform-repo> --body "westeurope"

A per-run input always overrides the variable (the provisioning form hides these fields behind an “override the organization’s defaults” checkbox).

The same variables back every workflow that touches cloud resources: the provisioning/reconciling workflow, the delete workflows (single environment and all-environments), the verification workflow, and the tagging workflow all fall back to them when dispatched without explicit cloud parameters. Workflow-to-workflow calls are unaffected — reusable-workflow inputs stay required, and callers always pass explicit values.

What you should observe

Each row below names the job exactly as it appears in the run’s UI. Jobs marked (app phase) only appear when app_template_repo is provided.

Resolve inputs                    ✓ validated inputs, derived sttf<app><sub>
Preflight checks                  ✓ template repos + pinned refs exist, container image anonymously pullable, environment promotion order respected
Checkov · {env}                   ✓ no findings
OpenTofu fmt check                ✓ formatting clean
Bootstrap tfstate storage         ✓ rg-test-webapp-tfstate + storage account + container
Plan · {env}                      ✓ tofu plan generated, artifact uploaded
Apply · {env}                     ✓ tofu apply succeeded, authentication details in the job summary
Verify · {env}                    ✓ control-plane assertions passed
Create application repo           ✓ <owner>/<app_name> created from template   (app phase)
Create run issue                  ✓ per-run tracking issue opened               (app phase)
Configure env · {env}             ✓ GitHub Environment + variables set          (app phase)
Federated credential · {env}      ✓ AAD subject registered on the SP            (app phase)
Observe CI in app repo            ✓ CI watched, build+test+dev-deploy succeeded (app phase, first run only)
Comment on app issue              ✓ summary posted as issue comment             (app phase)
Comment on infra issue            ✓ plan + verify results posted to infra issue
Run report                        ✓ links to the issues + per-environment access details (URL, test identity, credential commands)

The exact storage account name shows up in the bootstrap-tfstate job logs as TFSTATE_STORAGE_ACCOUNT=.... The plan output (and the binary tfplan file) is attached as a workflow artifact named tfplan-test-webapp-dev, retained for 7 days. The plan is then consumed by the apply job, which provisions the resources for real, after which verify runs control-plane assertions against the live infrastructure.

Every environment enforces Microsoft Entra ID sign-in. The Run report job (and the comment on the app repository’s tracking issue) ends with an Access block per environment: the application URL, the two app registrations and their client IDs, the environment’s Key Vault (kv-<app>-<env>) with the names of the five secrets it holds, the exact az keyvault set-policy and az keyvault secret show commands that let you read the end-to-end test credentials, and how people get access — a directory administrator assigns them under Enterprise applications → app-<app>-<env> → Users and groups (unassigned users get AADSTS50105; Global Administrators are exempt). Secret values never appear in logs or summaries.

When app_template_repo is provided, the run also creates the application repository from your template, configures its GitHub Environments + variables (AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_RESOURCE_GROUP, AZURE_WEBAPP_NAME, CONTAINER_REGISTRY_URL when a registry was supplied, and DEPLOY_TARGET_CLOUD=azure — the environment-scoped switch the app repo’s deploy router reads to pick its cloud, so different environments of one app can target different clouds), registers the per-env federated credentials on the platform SP, observes the auto-triggered CI in the new repo, and posts a summary comment on the per-run tracking issue. When app_template_repo is omitted, all of those steps are skipped and only the infra issue and final summary are written.


Step 5 — Configure scheduled drift detection (optional)

The detect-drift.yml workflow compares the recorded Terraform state against the live Azure resources (tofu plan -refresh-only) and opens an issue in the affected application’s infrastructure repo (<app>-infra) when it finds drift or an error. The provision workflow refreshes the state right after apply, so values the provider only reads back after creation are recorded and a sweep on a freshly provisioned environment reports only genuine changes — including settings the application’s own deploy pipeline updates. It has three entry points: a weekly schedule (Mondays at 05:23 UTC — an off-peak minute, since GitHub delays top-of-the-hour schedules the most), manual workflow_dispatch, and workflow_call (so other workflows can reuse it).

To change the cadence, edit the cron expression in detect-drift.yml. It cannot be moved to a repository variable — GitHub does not evaluate $ expressions in the on: block, so a templated cron never fires. Scheduled runs are also best-effort: GitHub delays them under load and disables them after 60 days of repository inactivity.

For each environment the workflow classifies the result from the (managed-state × resource-group) matrix:

Terraform state Resource group Result
empty / missing absent ⏭️ skipped — never provisioned
empty / missing present 🔴 drift — unmanaged/orphaned resource group
has resources absent 🔴 drift — all managed resources missing
has resources present refresh-only plan → ✅ no drift, 🔴 drift, or ⚠️ error

When drift is found the run stays green and reports via an issue; the run only goes red when the check itself errors (init/plan failure, missing directory, unreadable state), so a real problem with the sweep is visible and any workflow_call caller can react. The issue body carries the per-environment status, a follow-up comment carries the structured breakdown (added / removed / replaced / modified / tag-only), and the raw terraform plan output, binary plan and plan JSON are uploaded to the run as the drift-<app> artifact.

Manual and called runs pass their parameters as inputs. The scheduled run cannot — GitHub schedule events carry no inputs — so it reads them from repository variables, all DRIFT_-prefixed to make clear they exist solely to drive the automated sweep:

Repository variable Required Description
DRIFT_AZURE_APP_NAMES yes Application name(s) to check, comma-separated (e.g. myapp,otherapp). The workflow fans out one matrix job per app.
DRIFT_AZURE_ENVIRONMENTS no Environment(s) to check: all (default) or a comma-separated subset of dev/staging/prod.
DRIFT_AZURE_TENANT_ID yes Azure Tenant ID used for the OIDC login.
DRIFT_AZURE_SUBSCRIPTION_ID yes Azure Subscription ID hosting the apps’ resources and tfstate.
DRIFT_AZURE_CLIENT_ID yes Client ID of the platform App Registration.
DRIFT_AZURE_LOCATION yes Azure region of the resources under check (e.g. westeurope). Required by the infra template; a refresh-only plan will not run without it.

Set them under Settings → Secrets and variables → Actions → Variables, or via the CLI:

gh variable set DRIFT_AZURE_APP_NAMES       -R <org>/<platform-repo> --body "test-webapp"
gh variable set DRIFT_AZURE_ENVIRONMENTS    -R <org>/<platform-repo> --body "all"
gh variable set DRIFT_AZURE_TENANT_ID       -R <org>/<platform-repo> --body "<tenant-guid>"
gh variable set DRIFT_AZURE_SUBSCRIPTION_ID -R <org>/<platform-repo> --body "<subscription-guid>"
gh variable set DRIFT_AZURE_CLIENT_ID       -R <org>/<platform-repo> --body "<client-guid>"
gh variable set DRIFT_AZURE_LOCATION        -R <org>/<platform-repo> --body "westeurope"

The drift job authenticates with the branch-scoped federated credential (repo:<org>/<repo>:ref:refs/heads/main) already configured in step 2 — it is read-only and never binds a GitHub Environment, so no extra OIDC subject is needed. Issue creation in the <app>-infra repo uses the same GH_PAT secret configured in the GitHub setup guide.

The DRIFT_AZURE_* variables are the opt-in for the scheduled sweep — the schedule itself ships with the workflow file. If none of them are set, a scheduled run skips cleanly with a notice in its summary. If only some are set (or any other required input is missing), the run fails fast with a clear error: partial configuration is a mistake, and silence would hide it.


Troubleshooting

Azure identity/login failures (AADSTS70021, Insufficient privileges) and Terraform state problems (AuthorizationFailed, Failed to query container, Error refreshing state) are collected in Troubleshooting:

For the Azure resources themselves — App Service, networking, the template’s Checkov baselines — see the infrastructure template’s troubleshooting. —

What’s next

With the first run green end-to-end, the typical follow-up workshop topics are: