Onboarding Guide

From your first sign-in to your first cost recommendation — in under 30 minutes.

Also available in the Platform

This guide mirrors the Setup guide inside the Zation FinOps Platform at platform.zation.io → Settings → Tenants. You can follow either — both result in the same App Registration and role assignments.

Prerequisites

Before you start, make sure you have:

• An active Microsoft Entra ID tenant
• A Global Administrator account for the initial App Registration and admin consent
• For Azure FinOps: Owner or User Access Administrator on the Tenant Root Group (Management Group)
• For Microsoft 365 FinOps: a Microsoft 365 tenant connected to the same Entra ID
• About 15–20 minutes to walk through the Azure Portal steps

Permissions required for setup

The setup itself needs elevated rights (Global Administrator, Owner on the Management Group). Once setup is complete, the Zation Platform only holds read-only permissions on the assigned scopes. See Permissions for the full list.

Step 1 — Sign in to the Platform

Open platform.zation.io and click Sign in with Microsoft. On first sign-in from your tenant, Microsoft shows the consent screen for the Zation Platform multi-tenant app:

One-time admin consent

A Global Administrator grants tenant-wide consent once: tick Consent on behalf of your organization, then click Accept. This registers the Zation Enterprise application for the whole tenant — afterwards regular accounts sign in without re-consenting. The admin doesn't need their own Platform account; they can open platform.zation.io solely to grant this consent.

After accepting, the Platform automatically opens the Onboarding Wizard:

The wizard walks you through the four steps below: App Registration → Permissions → Verify. Click Get started to begin Step 2.

Step 2 — Create the App Registration

In this step you create a dedicated App Registration that the Zation Platform uses to read your data.

1. In the Azure Portal, open Microsoft Entra ID → App registrations → + New registration.
2. Configure the registration:
   • Name: Zation Platform Connector
   • Supported account types: Single tenant
   • Redirect URI: leave empty
3. Click Register.
4. From the Overview page, copy the Directory (tenant) ID and Application (client) ID, and paste them into the Setup guide form in the Platform.
5. Open Certificates & secrets → + New client secret:
   • Description: Zation Platform
   • Expires: 24 months (recommended)
6. Click Add, then copy the secret value immediately and paste it into the Setup guide.

Secret is only shown once

The client secret value is visible only at creation time. If you navigate away before copying it, you'll need to create a new secret.

Step 3 — Grant Microsoft Graph permissions

Skip this step if you don't plan to use the Microsoft 365 module. You can return to it later.

1. Inside the Zation Platform Connector App Registration, open API permissions → + Add a permission → Microsoft Graph → Application permissions.

2. Add the following permissions:

   Permission	Used for
   User.Read.All	Users, license assignments, manager, and extension attributes
   Organization.Read.All	License subscriptions, contract end dates, tenant country
   GroupMember.Read.All	Licensed groups and their member counts (never member lists)
   Reports.Read.All	Microsoft 365 usage reports (Adoption module)
   AuditLog.Read.All	Sign-in activity for the Adoption module, plus MFA registration state for the Security tile
   DeviceManagementManagedDevices.Read.All	Intune-managed devices
   DeviceManagementApps.Read.All	Intune app-protection (MAM) registrations — mobile-only detection for BYOD tenants (optional)
   TeamsUserConfiguration.Read.All	Teams user configuration
   CallRecords.Read.All	Teams call quality and usage metrics

   note

   Directory.Read.All is still accepted. If you already granted it, you don't need to change anything. It covers User.Read.All, Organization.Read.All, and GroupMember.Read.All.

3. Click Grant admin consent for <Tenant> → Yes.

Admin consent step is mandatory

Without admin consent, the permissions appear as Not granted and the Microsoft 365 sync will fail with Insufficient privileges. Granting consent requires a Global Administrator or Privileged Role Administrator.

Step 4 — (Optional) Enable audit-based usage signals — Dynamics 365, Copilot & Power BI

Dynamics 365 needs more than this step

This step covers the permission and the first two auditing layers. Dynamics 365 evidence comes in three levels, and write-level seat rightsizing additionally needs auditing enabled per table — a layer that is easy to miss, because the admin center reports auditing as on without it. The full walkthrough, including how to tell which level is missing, is in How Zation gets Dynamics 365 data.

Grant the activity permission

This audit evidence comes from the Office 365 Management APIs — a different resource than Microsoft Graph, so it is added separately:

1. In the Zation Platform Connector App Registration, open API permissions → + Add a permission → APIs my organization uses, then search for and select Office 365 Management APIs.

2. Choose Application permissions and add:

   Permission	Used for
   ActivityFeed.Read	Audit-event metadata (which user used which app or workload, and when) driving three signal families: Dynamics 365 inactive-user/module-mismatch/attach-candidate detection, Copilot interaction-frequency evidence, and Power BI usage evidence. Metadata only; no record content, no Copilot prompt/response text.

3. Click Grant admin consent for <Tenant> → Yes.

Turn on unified audit log (required)

These audit events only reach the Platform when the tenant's unified audit log is on. Dynamics 365 additionally needs per-environment auditing:

• The tenant's unified audit log — Microsoft Purview → Audit → Start recording user and admin activity. Required for all three areas (Dynamics 365, Copilot, Power BI).
• Auditing per environment — Power Platform admin center → the environment → Settings → Audit and logs → Audit settings → Start auditing. Dynamics 365 only.

Without auditing, signals fall back or every D365 user looks inactive

If the unified audit log is off, none of the three areas get audit evidence — Dynamics 365, Copilot, and Power BI all fall back to their proxy/last-activity signals. If only a Dynamics 365 environment's own auditing is off, that environment specifically returns no events and the module reports every user there as inactive. Turn auditing on before the first sync.

Optional — licence-tier recommendations (Dynamics 365 only)

Professional / Enterprise / Premium tier recommendations need one more read-only grant inside each environment: the Zation License Reader application user and role. Optional, and addable later — see Permissions → Dynamics 365, Copilot, and Power BI.

Step 5 — Assign Azure RBAC roles

Skip this step if you don't plan to use the Azure FinOps module.

The Platform reads cost, metric, and resource data at the Management Group scope, so a single set of role assignments covers every Azure subscription in your tenant.

Roles on the Tenant Root Group

1. In the Azure Portal, open Management Groups → Tenant Root Group → Access control (IAM) → + Add role assignment.

2. Assign these built-in roles to the Zation Platform Connector service principal:

   Role	Purpose
   Reader	Resource inventory, tags, diagnostic settings, utilization metrics, Log Analytics workspaces, and backup vaults — all via its */read action
   Cost Management Reader	Cost and usage data (required for Enterprise Agreement billing scopes, where Reader is not sufficient)
   Carbon Optimization Reader	Microsoft-measured CO₂e emissions per subscription and resource for Azure GreenOps

Carbon Optimization Reader

Carbon Optimization Reader unlocks Microsoft-measured emissions on Azure GreenOps. Without it, Azure GreenOps shows Zation's proxy estimates instead of measured data. The role is required for the Azure module.

Grace period for existing customers

Existing customers get a grace period after the requirement is introduced. During it, the Platform lists the role as recommended, not required. The permission reminder e-mail states the exact date from which the role is required. The PowerShell setup script assigns the role for new connections right away.

Enable Prod-AzureSustainability in your tenant

Microsoft's Carbon service also needs the Enterprise App Prod-AzureSustainability enabled in your tenant. Check under Microsoft Entra ID → Enterprise applications. If a tenant admin disabled it, the role alone isn't enough.

Assign the role at the Management Group scope so every subscription inherits it. The PowerShell script below does this for you. New Azure data appears from the 19th day of the following month.

Reservations Reader and Savings plan reader

These two roles are not inherited from the Management Group, because Reservations and Savings Plans are tenant-level resources. Assign each one once at tenant scope — a single assignment covers every current and future commitment, so you never have to revisit this when new Reservations or Savings Plans are purchased.

Prerequisite for these two roles

Assigning roles at tenant scope requires Global Administrator AND Access management for Azure resources set to Yes under Microsoft Entra ID → Properties. The toggle can be reverted once the assignments are done.

• Reservations Reader — Reservations → Role assignment (top toolbar). Scope: /providers/Microsoft.Capacity.
• Savings plan reader — Savings plans → Role assignment (top toolbar). Scope: /providers/Microsoft.BillingBenefits.

PowerShell auto-setup (recommended)

The Setup guide and Onboarding Wizard in the Platform offer a download for zation-rbac-setup.ps1 that assigns the three Management Group roles (Reader, Cost Management Reader, and Carbon Optimization Reader) plus the two tenant-scope roles (Reservations Reader and Savings plan reader) in one run.

The script prompts for the Tenant Root Group name and uses the Client ID from your App Registration. RBAC propagation can take up to 30 minutes.

Step 6 — Verify and first sync

Back in the Platform, click Verify in the Setup guide. The Platform validates the App Registration, the granted Graph permissions, and the RBAC assignments.

When verification succeeds, the initial data sync starts automatically. Depending on the size of your environment this takes 5–20 minutes. You can continue using the Platform in the meantime — recommendations appear as soon as enough data is available.

Troubleshooting

Symptom	Likely cause	Fix
Verify returns AADSTS70011	Wrong tenant signed in to Azure Portal	Sign in to the Portal with an account from the customer tenant before running the steps
Graph permissions stay Not granted	Admin consent step skipped	Open the App Registration, then API permissions → Grant admin consent for <Tenant>
Azure RBAC assignment fails at tenant scope (Reservations / Savings Plans)	Access management for Azure resources toggle is off	Set the toggle to Yes under Microsoft Entra ID → Properties, retry, then revert
Azure GreenOps lists subscriptions without the Carbon Optimization Reader role	The role is missing on those subscriptions, or the assignment hasn't propagated	Assign Carbon Optimization Reader to the Zation Platform Connector at Management Group level. Measured data appears with the next monthly sync. See Carbon Optimization Reader troubleshooting
Sync stays at 0% after 30 minutes	RBAC propagation still in progress	Wait up to 30 minutes; re-run Verify afterwards
Insufficient privileges on first M365 sync	Graph permission missing or not consented	Re-check the table in Step 3

Carbon Optimization Reader troubleshooting

Access denied on a subscription. Microsoft's API answers Denied per subscription where the role is missing. Assign Carbon Optimization Reader to the Zation Platform Connector at Management Group level so every subscription inherits it. Microsoft requires the permission at subscription level, so a role on a resource group or resource doesn't cover emissions data.

Failed to send request to Microsoft.Carbon due to AAD authentication error. The Enterprise App Prod-AzureSustainability is disabled in your tenant. Ask a tenant admin to enable it under Microsoft Entra ID → Enterprise applications.

No data right after granting the role. Microsoft registers a tenant the first time it uses the Carbon service. This can take 30 minutes to one hour.

The current month is missing. Microsoft publishes emissions for a month by the 19th day of the following month. New subscriptions and changed resource configurations appear in that later data.

Older months are missing. Microsoft keeps 12 months of emissions data.

Next steps

• Permissions — full reference of every role and scope Zation uses
• FAQ — common questions from new customers

---

Did this help? Send feedback to info@zation.io.