Skip to main content
Azure

Azure Onboarding Process (script)

Connect Azure EA, MCA, or CSP partner billing accounts using the org-level Cloud Shell script and a client-secret wiv_account service principal, with a billing-export-only mode for CSP / MSP partners.

Written By Dotan Cohen

Last updated 27 days ago

Connect Azure to Wiv using the Cloud Shell script. The script configures org-level billing access for Enterprise Agreement (EA), Microsoft Customer Agreement (MCA), and CSP partner billing accounts. Cost data is exported as daily FOCUS Parquet files to Blob storage.

The script asks how far the permissions should reach. Full onboarding grants read roles on every subscription billed through the account. CSP / MSP partners can choose billing export only, which skips the per-subscription permissions a partner login cannot grant in customer tenants. A POC option limits those roles to subscriptions you pick. See CSP and MSP partner mode (billing export only) below.

Note: Prefer no client secret? Use Azure Onboarding Process (in-app wizard) or Generate Integration Link in Wiv.

Warning: This path requires a billing account visible to your login (EA, MCA, or CSP partner). Customer tenants with no billing account cannot use this script. CSP partners should sign in to the partner tenant that owns the billing account and answer y to the billing export only prompt.

Architecture

Billing account (EA / MCA / CSP partner)
        │
        ▼
  FOCUS daily export (Parquet/Snappy)
        │
        ▼
  Storage account in rg-wiv (shared key disabled)
        │
        ▼
  Wiv reads blobs directly

Prerequisites

  1. Billing agreement: EA (EnterpriseAgreement), MCA (MicrosoftCustomerAgreement), or CSP partner (MicrosoftPartnerAgreement, or an MCA partner account). The script exits on any other agreement type.

  2. Register Cloud Shell for your subscription.

  3. EA only: Enable Account owners can view charges under Cost Management + Billing → Policies.

Permissions

Sign in to Cloud Shell as a user who holds every role below:

Scope

Role you need

Used for

Microsoft Entra ID

Application Administrator or Cloud Application Administrator

Create the wiv_account app registration, service principal, and client secret

Microsoft Entra ID (optional)

Global Administrator or Privileged Role Administrator

Grant admin consent for Microsoft Graph User.Read.All and Group.Read.All. Skip if you answer n to that prompt

Billing account

Billing account owner or Billing account contributor (MCA / CSP partner); Enterprise Administrator (EA)

Assign Billing account reader or Enrollment Reader to the app, and create the FOCUS export at billing-account scope (the export is created with your identity). Without the role the script prints manual steps for the grant and names the role to add before re-running for the export

Host subscription

Owner (or Contributor plus User Access Administrator)

Create rg-wiv and the storage account, register the Microsoft.Storage and Microsoft.CostManagementExports providers, and assign Cost Management Reader and Storage Blob Data Reader to the app

Every billed subscription

Owner or User Access Administrator, directly or inherited from a management group

Assign Reader, Monitoring Reader, and Cost Management Reader to the app. Full mode only — POC grants them on the subscriptions you pick and CSP / MSP billing-export-only mode skips them. Subscriptions owned by other tenants are detected and skipped automatically

Tenant-level reservation scope /providers/Microsoft.Capacity

User Access Administrator at tenant level. Global Administrator, subscription Owner, and management-group Owner are not enough

Assign Reservations Reader (full and POC modes). The script stops if this grant is denied

Management group (optional)

Owner or User Access Administrator at that group; Management Group Contributor at the tenant root group to create one

Assign Reader and Monitoring Reader, or create a new group (full mode only)

Global Administrators must elevate access first (Microsoft Entra ID → Properties → Access management for Azure resources), then sign in again. If the Reservations Reader grant is denied, the script stops before any per-subscription roles or the export; elevate access, sign in again, and re-run — it reuses everything already created. Do not assign the role by hand. CSP / MSP partners who answer y to billing export only skip this grant entirely.

What the script does

The script performs these steps, in this order:

  1. Verify tooling — checks for az, curl, and python3.

  2. Sign in — runs az login if needed and prints the signed-in user.

  3. Host subscription — lists subscriptions and asks which one hosts rg-wiv and the billing storage. This is not the cost scope.

  4. App registration and client secret — creates or reuses the wiv_account app registration and service principal. Every run mints a new client secret (2-year expiry); earlier secrets stay valid, so existing integrations keep working.

  5. Billing account — lists billing accounts and asks you to paste the Name, then grants the billing role via the Billing REST API: Enrollment Reader for EnterpriseAgreement, Billing account reader for MicrosoftCustomerAgreement / MicrosoftPartnerAgreement (CSP partner). Any other agreement type exits. If the automatic grant fails, the script prints manual steps and continues.

  6. Smoke test — after you press Enter, queries Cost Management at billing-account scope as the service principal and reports the row count or explains a 401 / 403 / 404 / 400 / 429.

  7. Billing storage setup — reuses rg-wiv (and its region) or asks for a region (default northeurope) and creates it; registers the Microsoft.Storage and Microsoft.CostManagementExports resource providers when missing.

  8. Cost Management Reader — assigns it to the app on the billing account and on the host subscription.

  9. Permission scope — asks Billing export only (MSP)? (default y for MicrosoftPartnerAgreement, n otherwise). y skips Reservations Reader, all per-subscription roles, and the management group — see CSP and MSP partner mode below. Otherwise it assigns Reservations Reader at /providers/Microsoft.Capacity (and stops if the grant is denied), then asks Apply ARM roles on selected subscription(s) only (POC)? — y grants Reader, Monitoring Reader, and Cost Management Reader only on the subscription IDs you enter; n grants them on every subscription billed through the account (billingSubscriptions API), skipping subscriptions owned by other tenants or no longer resolvable with a per-tenant summary.

  10. FOCUS billing export — reuses an existing FOCUS export named WivFocusDailyExport (or legacy DailyBillingExport) and its storage, upgrading it to Parquet + Snappy with month overwrite when needed; otherwise creates a wivbill<suffix> storage account in rg-wiv, the billing-exports container, and a daily FOCUS 1.0 export at billing-account scope with a system-assigned managed identity, then queues a 12-month backfill plus an immediate month-to-date run. The export is created with your identity; if Azure denies it, the script names the billing role to add.

  11. Blob access — hardens the storage account (allowSharedKeyAccess=false, no public blob access) and grants Storage Blob Data Reader to the service principal.

  12. Management group (optional, full mode only) — numbered list with 0) Skip as the default; assigns Reader and Monitoring Reader at the chosen group so subscriptions under it inherit access. When none are listed, offers to create one and move subscriptions into it. Skipped automatically in CSP / MSP and POC modes.

  13. Microsoft Graph (optional) — grants User.Read.All and Group.Read.All with admin consent if you answer y.

  14. Output — prints Tenant ID, App (Client) ID, SP Object ID, host subscription, billing account and cost scope, management group, an ARM roles: skipped line in CSP / MSP mode, the FOCUS export details, the client secret, and a ready-to-paste Wiv integration JSON.

Note: Cost is exported once at billing-account scope. The export includes only subscriptions billed through the billing account you select — if a subscription belongs to another billing account, grant your user access to that account and select it during onboarding.

CSP and MSP partner mode (billing export only)

Use this mode when you are a Cloud Solution Provider (CSP) or MSP partner onboarding a partner billing account. Customer subscriptions billed through a partner account live in the customers' Microsoft Entra tenants, so a login to the partner tenant cannot assign ARM roles on them. The billing account itself is in the partner tenant, so the FOCUS export — which covers every customer's cost — can still be created from there.

Sign in to Cloud Shell in the partner tenant that owns the billing account, run the script, and when it asks:

🏢 MSP / CSP partner mode (optional)
   Billing export only — skip subscription/ARM permissions (MSP)? (y/n) [y]:

answer y (or press Enter — y is the default when the billing account's agreement type is MicrosoftPartnerAgreement). If your partner billing account is listed as MicrosoftCustomerAgreement, the default is n, so type y explicitly. For EA and direct MCA accounts keep n.

What the skip keeps and what it skips:

Still set up

Skipped

wiv_account app registration and a new client secret

Reservations Reader at /providers/Microsoft.Capacity

Billing account reader (or Enrollment Reader) on the billing account

Reader, Monitoring Reader, and Cost Management Reader on billed subscriptions

Cost Management Reader on the billing account and the host subscription

The POC prompt

FOCUS export, 12-month backfill, and Storage Blob Data Reader on the export storage

The management group prompt

The Microsoft Graph prompt is still asked. With this mode Wiv receives all customers' cost from the billing-account FOCUS export. It does not receive per-subscription inventory, Azure Monitor metrics, or reservation orders, because those APIs need roles inside each customer tenant. The script marks the choice in its final output:

📄 Management group:    (skipped: MSP billing-export-only)
📄 ARM roles:           skipped (MSP billing-export-only: no per-subscription roles, no Reservations Reader)

Note: To add inventory, metrics, or reservation visibility for a customer later, onboard that customer tenant separately — for example with Generate Integration Link from the Azure integrations page — or delegate the customer subscriptions to the partner tenant with Azure Lighthouse. Re-running this script in the partner tenant cannot grant those roles.

If you answer n on a partner account, the script runs the regular flow instead: it must be able to assign Reservations Reader in the partner tenant (otherwise it stops), asks the POC question, and in full mode probes every billed subscription and skips the ones owned by customer tenants automatically, printing a per-tenant summary such as:

ℹ️  Skipped subscriptions billed by this account but owned by other tenants.
    Their cost is still included in the billing-account FOCUS export. Granting ARM
    roles on them (inventory, metrics, reservations) needs a sign-in to that tenant
    or Azure Lighthouse delegation:
    - tenant <customer tenant id>: 12 subscription(s) — az login --tenant <customer tenant id>

POC: selected subscriptions only. When you answer n to billing export only, the script assigns Reservations Reader and then asks:

🧪 POC permissions (optional)
   Apply ARM roles on selected subscription(s) only (POC)? (y/n):

Answer y to run a proof of concept on a few subscriptions. The script lists the subscriptions visible to your login, asks for comma-separated subscription IDs (default: the host subscription), and grants Reader, Monitoring Reader, and Cost Management Reader only there. It skips the all-billed-subscriptions loop and the management group, and the final output shows Management group: (POC: selected subscriptions only). Reservations Reader is still assigned in POC mode. To expand later, re-run the script and answer n, or assign the three roles on each additional subscription by hand.

Run the script

Open Azure Cloud Shell and run:

curl -sO https://raw.githubusercontent.com/wiv-ai/AzureOnBoarding/main/.cloudshell/startup.sh && chmod +x startup.sh && ./startup.sh

Prompt

What to enter

Subscription ID to host the app registration

Any subscription where you can create app registrations and rg-wiv resources (typically management or shared-services)

Billing account Name

The Name column from the listed table (EA, MCA, or CSP partner)

Press Enter to run the smoke test

Press Enter after the billing role is granted (allow a few minutes for propagation)

Azure region for rg-wiv [northeurope]

Shown only when rg-wiv does not exist yet. Press Enter for northeurope or type another region

Billing export only — skip subscription/ARM permissions (MSP)? (y/n)

y for CSP / MSP partner accounts (the default when the agreement type is MicrosoftPartnerAgreement); n for EA / MCA full onboarding. See CSP and MSP partner mode above

Apply ARM roles on selected subscription(s) only (POC)? (y/n)

Shown only after n above. n for full onboarding; y to limit roles to subscriptions you pick

Comma-separated subscription IDs for Reader + Monitoring Reader

POC only. Press Enter to use the host subscription, or list subscription IDs separated by commas

Management group: Select a number [0-N]

Full mode only. A number from the list, or 0 / Enter to skip (new subscriptions will not inherit MG-scoped access)

Create a management group now? / ID / Display name / Move subscriptions (all / specific / no)

Shown only when no groups are listed — answer y to create one and optionally move subscriptions into it

Grant Microsoft Graph User.Read.All and Group.Read.All? (y/n)

Answer y only if your Wiv integration requires Microsoft Graph directory read access

Prompts appear in this order; some are shown only in certain modes. If automatic billing-role assignment fails, the script prints manual steps for EA (REST API) or MCA (Azure portal IAM) and continues. If Reservations Reader cannot be assigned (full and POC modes), the script stops — elevate access, sign in again, and re-run.

Wait for the first export

The first FOCUS export can take 5–30 minutes. In the Azure portal, open the billing account → Exports → WivFocusDailyExport → Run now, then confirm part_*.snappy.parquet files appear in storage.

The script is idempotent — safe to re-run. It reuses the app registration, rg-wiv, the storage account, and the export, and skips role assignments that already exist. Each run mints a new client secret; earlier secrets stay valid until they expire (2 years), so a re-run never breaks an existing integration.

Save the script output

Copy the Wiv integration secret JSON printed at the end of the script before closing Cloud Shell. It includes Tenant ID, App ID, SP Object ID, the client secret (a new secret is printed on every run — store it in your secret manager), billing account name, billing storage account and its resource ID, host subscription ID, and the export path defaults (billing-exports, billing-data, WivFocusDailyExport).

{
  "auth_method": "client_secret",
  "tenant_id": "<tenant>",
  "app_id": "<app id>",
  "client_secret": "<secret>",
  "sp_object_id": "<service principal object id>",
  "billing_account_name": "<billing account name>",
  "billing_query_backend": "blob",
  "billing_storage_account": "<storage account>",
  "billing_storage_resource_id": "/subscriptions/<host subscription id>/resourceGroups/rg-wiv/providers/Microsoft.Storage/storageAccounts/<storage account>",
  "billing_container": "billing-exports",
  "billing_root_folder": "billing-data",
  "billing_export_name": "WivFocusDailyExport",
  "subscription_id": "<host subscription id>"
}

The JSON is the same in CSP / MSP and POC modes — the modes change which ARM roles the app holds, not the export. If the FOCUS export was not deployed in this run, the script prints a shorter JSON without the storage and export fields and a note saying so; fix the cause (see Troubleshooting) and re-run before connecting in Wiv.

Connect in Wiv

  1. Sign in to Wiv → Integrations → Azure → New Azure Integration.

  2. Enter values from the script output JSON: Tenant ID, App ID, Client Secret, Billing account name, Billing storage account, and host subscription ID (plus container / root / export name if you changed the defaults).

  3. Click Save.

Note: The script prints a ready-to-paste Wiv integration JSON at the end (auth_method client_secret, billing_query_backend blob, including sp_object_id and billing_storage_resource_id) — see Save the script output above.

Adding Entra ID permissions (post deployment)

  1. Entra ID → App registrations → wiv_account.

  2. Open API permissions.

  3. Under Microsoft Graph → Application permissions, confirm User.Read.All + Group.Read.All, or Directory.Read.All.

  4. Click Grant admin consent for your tenant and confirm green checkmarks in the Status column.

Troubleshooting

Symptom

Action

No billing accounts listed

Sign in to the partner/EA/MCA tenant with billing admin rights

Agreement type … is not supported

Select an EA, MCA, or MicrosoftPartnerAgreement billing account; the script exits on other agreement types

Smoke test 403

Wait for role propagation; for EA, confirm view-charges policy

Could not assign Reservations Reader and the script stops

Your login lacks User Access Administrator at tenant level (Global Administrator alone is not enough). Elevate access, sign in again, re-run. CSP / MSP partners: answer y to billing export only instead

Skipped subscriptions … owned by other tenants

Expected for CSP — those subscriptions live in customer tenants and their cost is still in the export. For inventory and metrics, onboard the customer tenant separately or use Azure Lighthouse

Subscription missing in Wiv

The app lacks ARM roles on it (full mode not run, POC did not include it, or it is in another tenant). Re-run in full mode (grants via billingSubscriptions) or assign Reader / Monitoring Reader / Cost Management Reader manually

Not authorized to create the billing export

The export is created with your identity. Grant Cost Management Contributor or a billing account Owner / Contributor role on the billing account, run az logout && az login, re-run

Export create fails (shared key)

Re-run script — export uses managed identity

Storage create fails with SubscriptionNotFound

Microsoft.Storage is not registered on the host subscription. The script registers it and retries; if it still fails, register it manually and re-run

No inventory, metrics, or reservation data

Expected in billing export only (CSP / MSP) mode — see CSP and MSP partner mode above for how to add customer-tenant access

No cost data

Run Run now on WivFocusDailyExport

AADSTS700016 in workflows

Re-onboard — app registration was deleted or tenant ID is wrong