Connect Azure (Read-Only)

Read-only collection boundary

Alternative: create the service principal with Azure CLI

An authorized administrator can run this command instead of creating the app manually in the portal. Replace the subscription placeholder with your intended scope. It creates an application, service principal and Reader assignment; add Cost Management Reader in step 3. The command prints a credential, so run it in a private shell and keep its output out of tickets, chat and source control.

az ad sp create-for-rbac \
  --name "Costframe-ReadOnly" \
  --role "Reader" \
  --scopes "/subscriptions/{subscription-id}"

Setup steps

1. 1

   Create an app registration

   In the Azure Portal, open Microsoft Entra ID, click App registrations → New registration. Name the registration Costframe-ReadOnly. Keep default organizational directory options and click Register.

2. 2

   Create a client secret

   Navigate to Certificates & secrets, then click New client secret. Choose a description and set an expiration window, then click Add. Copy the secret value, not the secret ID. Record the expiry in your credential management process so you can replace it before collection fails.

   Stored provider credentials are encrypted with AES-256-GCM. The worker decrypts credentials for collection. Keep secret values within the intended connection setup process.

3. 3

   Assign the subscription roles

   Navigate to your Subscriptions, choose the target scope, click Access control (IAM), and add role assignments. Assign both Reader and Cost Management Reader to the Costframe-ReadOnly service principal associated with your app registration. Check the application ID when selecting it, especially if several apps have the same display name. Grant access only to subscriptions you intend to connect. Billing access can also depend on your Azure agreement's cost-visibility settings.

4. 4

   Optional: Grant Microsoft Graph access for Azure Virtual Desktop

   Reader and Cost Management Reader provide the base cost and resource access, including Azure Virtual Desktop (AVD) host-pool and session-host inventory. User and department lookup requires separate Microsoft Graph access. A Microsoft Entra administrator needs to add one more permission to the same app registration: open API permissions → + Add a permission → Microsoft Graph → Application permissions, add User.Read.All, then select Grant admin consent for your tenant. This grant is tenant-wide and cannot be scoped to one subscription. Skip this step if you do not need directory lookup. It does not provide desktop session activity: that requires separate AVD log evidence. Review identity scope and capability readiness in the workspace before relying on user attribution.

5. 5

   Connect and select your subscriptions

   In your Costframe workspace, open Cloud Connections and enter your Tenant ID, Client ID, and Client Secret. Enter a Subscription ID to target one scope, or leave it empty to discover visible subscriptions. Discovery runs in the background. Newly discovered subscriptions are not included until you select them; finding a subscription does not start its first audit.