Skip to main content

Azure Onboarding with the PowerShell Script

Use the PowerShell path when your Azure admin team prefers a local guided script.

The script is idempotent, so it can be rerun to repair interrupted setup, add missing permissions, or update recommended access.

Choose A Setup Mode​

The first question selects the permission profile:

  • Recommended read-only access is the default. Press Enter to automatically onboard all subscriptions and configure the complete supported Azure and Microsoft Graph reader set without answering each capability question.
  • Custom setup lets you select specific subscriptions and keeps the individual monitoring, governance, commitment, Graph, billing, and write capability questions.
  • Check prerequisites (no Azure changes) assesses the signed-in operator across all visible subscriptions, management groups, Reservations, Savings Plans, and Azure resource-role PIM before an app or permission is created.

After the reader setup, Recommended mode separately offers Cost Management billing exports and defaults that prompt to yes. Decline the prompt to leave exports and storage unchanged.

Use the prerequisite check when an admin is unsure whether their active or eligible access covers the tenant. Successful subscription and management-group checks are counted; only scopes that need action, PIM activation, or manual review are expanded. The check reports eligible PIM separately from active permission. Activate the suggested role, reconnect the Azure session, and rerun the check before starting Recommended setup.

The check does not create or change Azure applications, secrets, permissions, role assignments, exports, storage, policies, or provider registrations. It may install missing PowerShell modules locally and uses the local Azure session/context for read requests.

The automatic PIM assessment covers Azure resource roles. It does not request extra Microsoft Graph access to inspect Microsoft Entra app-management roles, Graph admin-consent roles, or Entra directory-role PIM. Confirm those roles manually using the Azure onboarding operator permissions guide.

Recommended read-only access automatically includes Reader, Management Group Reader, Monitoring Reader, Log Analytics Reader, Security Reader, Key Vault Reader, Reservations Reader, Savings plan Reader, and the complete Microsoft Graph governance permission set.

Key Vault Reader lets Spotto list secret, key, and certificate expiry metadata for proactive notifications. It cannot read secret values or private key material. For all-subscriptions setup, the wizard prefers one assignment at the exact tenant-root management group and falls back to every selected subscription when that assignment cannot be confirmed. Specific-subscription setup assigns it only to those subscriptions. This covers vaults using Azure RBAC; legacy access-policy vaults need per-vault List permissions.

For Reader coverage, the wizard first tries one inherited assignment at tenant root scope (/). If Azure cannot validate or create that assignment, the wizard automatically validates every selected subscription and assigns Reader one subscription at a time. Existing assignments are reused. The fallback must succeed for every selected subscription; it does not silently skip failed scopes.

Management-group discovery is separate. The wizard recognizes tenant root only when the management-group ID equals the selected tenant ID. If that exact group is unavailable, it uses the management groups visible to the signed-in operator and attempts each scope independently. In recommended or Custom all-subscriptions setup, it assigns Reader, Management Group Reader, Monitoring Reader, and Log Analytics Reader at those scopes. A failure on one group is reported without stopping the remaining groups.

Custom setup with specific subscriptions keeps monitoring roles at those subscriptions. Its separate prompt for Reader and Management Group Reader across every visible management group defaults to no, preventing a narrow subscription choice from silently expanding to wider management-group monitoring access.

Recommended mode excludes Reservations Contributor, Advisor/Storage Inventory write access, and Azure Policy exemption access. After configuring reader permissions, it separately offers the recommended Cost Management billing-export workflow with a default of yes.

When the Spotto application already has credentials, the wizard reuses the valid credential with the latest expiry if it has at least three months remaining. If it has less than three months remaining—or no valid credential exists—the wizard creates a replacement secret. Exactly three months remaining is treated as reusable.

important

“Read-only” describes the lasting permissions added to the Spotto service principal. The signed-in setup operator still creates or updates the app registration and role assignments. If you accept the separate billing-export prompt, the operator also authorizes setup-time export and storage changes while the Spotto service principal retains read-only access. Existing write assignments on a reused service principal are not removed; review that principal in Azure IAM when strict read-only access is required.

Before running the script, confirm the Azure admin has the required temporary setup privileges. If your organization uses PIM or just-in-time access, see Operator Permissions And PIM.

For subscription Reader coverage, recommended mode works with permission to assign roles at tenant root scope (/), or with role-assignment permission on every selected subscription through the automatic fallback. Management-group roles require role-assignment authority at the exact tenant root or at each visible management group the wizard processes. A visible group can still reject assignment if the operator has read access but not Microsoft.Authorization/roleAssignments/write. Custom billing-export setup additionally needs resource-management access: use Owner, or Contributor plus User Access Administrator, at the relevant subscription and storage scopes.

What The Script Configures​

Setup-SpottoAzure.ps1 can configure:

  • A Spotto Entra ID app registration and service principal, reusing an existing Spotto app where present.
  • A client secret for Spotto when no healthy credential exists or the latest valid credential has less than three months remaining.
  • Reader access at tenant root when available, with automatic per-subscription fallback for all selected subscriptions.
  • In all-subscriptions setup, Reader, Management Group Reader, Monitoring Reader, and Log Analytics Reader at the exact tenant root when available, otherwise on the management groups visible to the signed-in operator.
  • Reservations Reader and Savings plan Reader. Reservations Contributor is available only through Custom setup.
  • Microsoft Graph governance permissions with admin consent, including Policy.Read.All and LicenseAssignment.Read.All for tenant policy and subscribed-license posture. See the complete permission list.
  • Monitoring Reader, Log Analytics Reader, and Security Reader on every selected subscription, applied automatically with recommended read-only access.
  • Key Vault Reader at the tenant-root management group when available, with automatic selected-subscription fallback for expiry metadata and notifications.
  • When accepted in Recommended or Custom setup, Cost Management exports to customer-owned Azure Storage.
  • When accepted, Cost Management Reader on linked billing scopes where compatible billing-scope exports are discovered and the scope is available.
  • When accepted, Storage Blob Data Reader on the billing export container.
  • Optional custom write access for supported Spotto actions.
  • Separately optional Azure Policy exemption access, with a second exact-scope confirmation for inherited management-group assignments.

The policy exemption prompt is independent of Advisor/Storage writes and defaults to no. See Azure Policy exemption permissions for the exact actions and rollback guidance.

Run The Script​

  1. Open the Spotto Azure onboarding script repository: Spotto Azure onboarding tools.
  2. Review the script and prerequisites with your Azure admin team.
  3. Run Setup-SpottoAzure.ps1 from a PowerShell session.
  4. Choose a mode:
    • Press Enter for recommended read-only access, then select the tenant. All subscriptions are selected automatically.
    • Choose Check prerequisites first when you need to validate operator access or identify Azure resource PIM roles to activate.
    • Choose Custom setup when specific subscriptions or individual capability choices are required.
  5. Keep the generated SpottoAzureOnboarding-*.json file available for the portal handoff. It contains the tenant and client IDs, a newly created secret when applicable, and accepted billing export sources.
  6. For a new manual cloud account, choose PowerShell Setup (marked Recommended) and paste the complete file into Import PowerShell Setup Details. A valid paste imports automatically; if you typed or edited the JSON, select Import Details. Review the populated fields.
  7. If the JSON file could not be created, copy the displayed values into their matching fields instead.
  8. Validate and save the Azure account using these Spotto Portal steps.

The JSON can contain a client secret. Use it only on a trusted device and securely delete it when it is no longer needed.

Billing Exports​

Recommended and Custom setup both offer billing export setup separately from the reader permissions and default the prompt to yes. You can decline it without failing the rest of onboarding or changing exports and storage.

When enabled, the script can:

  • Detect compatible existing daily exports and reuse them.
  • Discover accessible billing accounts, billing profiles, invoice sections, management groups, and selected subscriptions, then check those scopes for compatible exports.
  • Accept known billing-scope resource IDs when Azure cannot automatically list the intended scope.
  • Prefer an eligible tenant-root management-group Usage export, or topmost visible child management groups when tenant-root export access is unavailable.
  • Keep subscription Actual and Amortized exports as the completeness fallback where Azure supports them.
  • Create or select customer-owned export storage. Creating or reusing the script's deterministic dedicated storage account is the recommended default.
  • Ensure a private container, defaulting to spotto-cost-exports.
  • Grant Storage Blob Data Reader on the export container.
  • Create daily actual and amortized Cost Management exports where supported.
  • Queue historical backfill for recent closed months.

The script queues export runs and backfill requests with Azure, but it does not wait for Azure Cost Management to finish generating export files. Billing files can appear later depending on Azure export timing.

Accepted recurring export locators and their storage destinations are included in the generated onboarding JSON. The script keeps its handoff within a conservative 50-source and 24-KiB limit and retains non-conventional locators before canonical scopes and names that cloud-engine can rediscover. If anything is still omitted, the script warns you to review it because arbitrary child-management-group, nested billing-scope, or custom-named export locators are not guaranteed to be rediscovered automatically.

Without billing exports, Spotto can still validate Azure access and complete onboarding. Export-first billing ingestion will not be available, and some billing-driven views may be delayed or incomplete depending on the other billing data paths available to the account. If you reuse a billing-scope export, make sure Spotto also has reader access at that billing scope and network access to the export storage account.

Billing export setup needs resource-management permission as well as role-assignment permission. Use Owner for the simplest PIM activation, or Contributor plus User Access Administrator if your organization separates resource changes from RBAC assignment.

For the complete export-first and API gap-filling behavior, see Azure Billing Exports.

When To Use Another Path​

Use Automatic Azure Connect if your admin can complete setup directly from Spotto.

Use Terraform Module if your organization wants the app registration, role assignments, and billing export resources managed as infrastructure as code.