scaffolding-multi-tenant-azure-apps

Scaffolding Multi-Tenant Azure Apps

Multi-tenant pattern with one resource group per tenant on a shared subscription. One tenant parameter drives the RG and every resource name. Adding a tenant = redeploy with a new param value.

When to use this pattern

Workflow checklist

Copy this checklist and tick items off:

Onboarding a new tenant:
- [ ] Step 1: Agree on the tenant slug (kebab-case, ≤20 chars, no Azure reserved words)
- [ ] Step 2: Verify the derived storage account name fits (≤24 chars, alphanumeric) — provide override if not
- [ ] Step 3: Copy infra/environments/prod.parameters.json → infra/environments/{tenant}.parameters.json
- [ ] Step 4: Edit tenant slug + storageAccountName override if needed
- [ ] Step 5: Create a new branch for this tenant if using branch-per-tenant (recommended for full isolation)
- [ ] Step 6: Add OIDC SP + federated credential bound to the new branch (skill: configuring-azure-oidc-for-github-actions)
- [ ] Step 7: Generate per-tenant SQL password + add as GitHub secret
- [ ] Step 8: Push to the tenant branch → workflow provisions the isolated stack
- [ ] Step 9: Verify per-tenant cost reporting: `az resource list --tag tenant=$SLUG -o table`

The core idea

main.bicep accepts a tenant param. Default value matches your original (single-tenant) naming so the first deployment doesn't need to migrate anything:

@description('Tenant slug — drives all resource names + the RG.')
param tenant string = 'acme-default'

// Storage account name can\'t have hyphens, ≤24 chars. Provide an override
// for tenants whose slug doesn\'t yield a valid storage name.
@description('Storage account name override (no hyphens, ≤24 chars). Empty = derive from tenant.')
param storageAccountName string = ''

module rg 'modules/resourceGroup.bicep' = {
  name: 'deploy-rg-${environment}'
  params: { name: '${tenant}-rg-${environment}' }
}

module storage 'modules/storage.bicep' = {
  scope: resourceGroup('${tenant}-rg-${environment}')
  params: {
    name: empty(storageAccountName) ? toLower(replace('${tenant}store', '-', '')) : storageAccountName
  }
}

// ... every other module follows the same pattern