Docs / Cloud Accounts / Connect Azure Account

Connect Azure Account

Published · Last updated: June 2026 · 10 min read

Overview

CloudAIPilot connects to your Microsoft Azure subscription using a Service Principal — an application identity registered in Microsoft Entra ID (formerly Azure Active Directory). This gives CloudAIPilot scoped, programmatic access to manage Virtual Machines without using any individual user's credentials.

You can revoke access at any time by deleting the client secret or the app registration from the Azure Portal.

Security & PQC Note

Your Azure Client Secret is encrypted at rest using Post-Quantum Cryptography (PQC) standards (ML-KEM-768). It cannot be viewed again after you save the connection in CloudAIPilot.

Before You Begin

You will need:

  • An Azure account with Global Administrator or Application Administrator role in Microsoft Entra ID (to register applications)
  • Owner or User Access Administrator on the target subscription (to assign roles)
  • Your Azure Subscription ID — find it under Azure Portal → Subscriptions, listed in the table

If your organisation's tenant policy restricts App Registration, you will see an error in Step 1. Ask your Azure AD administrator to enable "Users can register applications" under Microsoft Entra ID → User settings, or ask them to complete the registration on your behalf.

Step-by-Step Guide

Step 1: Register the Application in Microsoft Entra ID

  1. Log in to the Azure Portal.
  2. Search for Microsoft Entra ID in the top search bar and open it.
  3. In the left menu, click App registrations → New registration.
  4. Fill in the registration form:
    • Name: CloudAIPilot Orchestrator
    • Supported account types: Accounts in this organizational directory only (single tenant)
    • Redirect URI: leave blank
  5. Click Register.
  6. On the app's overview page, copy and save these two values — you will need them later:
    • Application (client) ID
    • Directory (tenant) ID

Step 2: Create a Client Secret

  1. In the left menu of the app registration, click Certificates & secrets.
  2. Under the Client secrets tab, click New client secret.
  3. Add a description (e.g., CloudAIPilot access) and set an expiration. We recommend 12 months as a balance between security and maintenance overhead.
  4. Click Add.
  5. Copy the Secret Value immediately — Azure hides it after you navigate away from this page. You cannot retrieve it later.

Important — Secret expiry: When the client secret expires, CloudAIPilot loses access to your Azure subscription and all operations (server provisioning, monitoring, backups) will stop working. You must create a new secret and update it in CloudAIPilot before the expiry date. Set a calendar reminder 2 weeks before the expiry date. See KB-01-06: Reconnect or Rotate Credentials Safely for the rotation procedure.

Step 3: Find Your Subscription ID

  1. In the Azure Portal top search bar, search for Subscriptions.
  2. A table of your Azure subscriptions appears. Copy the Subscription ID of the subscription you want CloudAIPilot to manage.

If you manage multiple Azure subscriptions, you will connect them separately — one per CloudAIPilot cloud account. Use the Subscription ID of the specific one you want to manage right now.

Step 4: Assign the Role on the Subscription

CloudAIPilot needs permission to create and manage Virtual Machines on the subscription. You will assign the Contributor role, which grants full create/read/update/delete access to resources but does not grant access to manage role assignments.

  1. In the Subscriptions view, click the subscription you are connecting.
  2. In the left menu, click Access control (IAM).
  3. Click Add → Add role assignment.
  4. On the Role tab, search for Contributor and select it. Click Next.
  5. On the Members tab, choose Assign access to: User, group, or service principal.
  6. Click Select members, search for CloudAIPilot Orchestrator, and select it.
  7. Click Review + assign twice to confirm.

Prefer least privilege? If your security policy does not allow Contributor on the full subscription, you can assign it at the resource group level instead — create a dedicated resource group for CloudAIPilot-managed resources and assign Contributor only on that group. CloudAIPilot will provision all new servers into that resource group.

Step 5: (Optional) Add Billing Reader for FinOps Dashboard

To see Azure cost data in the CloudAIPilot FinOps dashboard, assign an additional role:

  1. From the same Access control (IAM) screen on the subscription, click Add → Add role assignment.
  2. Search for Cost Management Reader (scoped to subscription) and select it.
  3. Assign it to the same CloudAIPilot Orchestrator application.
  4. Click Review + assign.

Without this step, server provisioning still works — only the FinOps dashboard will show no Azure cost data.

Step 6: Connect in CloudAIPilot

  1. In CloudAIPilot, go to Cloud Accounts → Add Account → Azure.
  2. Enter the four values you collected:
    • Tenant ID (Directory ID from Step 1)
    • Client ID (Application ID from Step 1)
    • Client Secret (the value copied in Step 2)
    • Subscription ID (from Step 3)
  3. Click Test & Connect. CloudAIPilot performs a pre-flight check before saving.

Verifying a Successful Connection

After connecting, your Azure subscription appears in the Cloud Accounts list with a green Connected status. Navigate to Servers → Add Server — your Azure regions should now appear as provisioning targets.

Common Connection Errors

"Application not found in tenant"
The Tenant ID entered does not match the tenant where the app registration lives. Double-check the Directory (tenant) ID on the app's overview page in Microsoft Entra ID.
"Invalid client secret" or "AADSTS7000215"
The client secret value was copied incorrectly (truncated or with trailing spaces), or the secret has already expired. Create a new secret in Certificates & secrets and re-enter it in CloudAIPilot.
"The client does not have authorization to perform action Microsoft.Compute/virtualMachines/write"
The Contributor role assignment on the subscription has not propagated yet (Azure role assignments can take up to 5 minutes), or it was assigned to the wrong scope. Check Access control (IAM) on the subscription and confirm CloudAIPilot Orchestrator is listed with the Contributor role.
"Subscription not found"
The Subscription ID entered doesn't exist under this tenant, or the service principal does not have any role assignment on it. Confirm you entered the correct Subscription ID from the Subscriptions page.
FinOps shows no Azure cost data
The Cost Management Reader role is missing (Step 5), or the Azure Cost Management API is not available on your subscription type (it requires pay-as-you-go or EA billing, not free trial accounts).

Human-in-the-Loop Safety

Once connected, CloudAIPilot reads your Azure subscription and can propose infrastructure changes. It will never create a Virtual Machine, resize a disk, or delete any resource without generating an Approval Card for you to review and confirm first.

Revoking Access

To disconnect CloudAIPilot from your Azure subscription:

  • In CloudAIPilot: Cloud Accounts → [your account] → Remove
  • In Azure (immediate revocation): Go to Microsoft Entra ID → App registrations → CloudAIPilot Orchestrator → click Delete, or go to the Certificates & secrets tab and delete the client secret. Either action immediately revokes all access.

Related Articles