> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yasu.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure

> Complete guide to connect your Microsoft Azure account to Yasu for cost analysis and optimization

Connect your **Azure account** to Yasu by creating a Service Principal with read-only permissions. This enables Yasu to analyze your cloud costs and provide optimization recommendations.

<Info>
  **Security First:** Yasu uses a Service Principal with read-only permissions. We cannot modify, create, or delete any Azure resources.
</Info>

## Subscription-Level Setup (All Billing Account Types)

This guide covers connecting Azure subscriptions to Yasu using subscription-level RBAC roles. This setup method works for **all Azure billing account types**, including:

* **Pay as You Go** (Individual subscriptions)
* **Microsoft Customer Agreement (MCA)**
* **Enterprise Agreement (EA)**
* **Azure Cloud Solution Provider (CSP)**

<Info>
  **Universal Setup:** Subscription-level RBAC roles provide access to cost data and resources for all billing account types. Simply create a Service Principal and assign roles at the subscription scope - no billing account ID or enrollment number is required.
</Info>

## Prerequisites

Before connecting your Azure account, ensure you have:

* **Administrative access** to your Azure subscription (or permissions to create Service Principals and assign RBAC roles)
* **Subscription Owner or User Access Administrator** role to assign permissions
* Access to Azure Portal or Azure CLI
* PowerShell or Azure CLI installed (for automated setup)

## Quick Setup via Azure CLI

The fastest way to connect your Azure account is through Azure CLI commands.

<Steps>
  <Step title="Open Azure Connection Dialog">
    1. Log in to your Yasu dashboard at [app.yasu.cloud](https://app.yasu.cloud)
    2. **Create a workspace** (if you haven't already):
       * After logging in, you'll be prompted to create a new workspace
       * Enter your workspace name and click **Create**
       * You'll be redirected to the **Onboarding** page
    3. On the **Onboarding** page, Click the **Connect** button next to Azure

    This opens the Azure connection dialog with step-by-step instructions.
  </Step>

  <Step title="Step 1: Create Service Principal">
    In the dialog, you'll see an Azure CLI command to create a Service Principal:

    1. **Copy the command** from the dialog (it is pre-filled with your account ID)
    2. **Open Azure Cloud Shell** or your local terminal with Azure CLI installed
    3. **Paste and run the command**

    The command creates a Service Principal named `yasu-cost-optimizer-{your-account-id}` and returns a JSON output like:

    ```json theme={null}
    {
      "appId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "displayName": "yasu-cost-optimizer-...",
      "password": "XXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "tenant": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    }
    ```

    4. **Copy the entire JSON output** and paste it into the text box in the dialog — the credentials will be auto-filled from it
    5. Click **Next**

    <Warning>
      **Important:** Save this output securely. The `password` (client secret) is only shown once and cannot be retrieved again.
    </Warning>
  </Step>

  <Step title="Step 2: Assign Roles">
    The dialog will prompt you to enter the subscription ID where your Azure resources are hosted:

    1. **Enter your Azure Subscription ID** in the provided field
    2. The dialog will **automatically regenerate** the three role assignment commands with your subscription ID and App ID filled in
    3. **Copy the commands** for your platform (Bash/Linux/macOS or PowerShell)
    4. **Run the commands** in your Azure terminal and wait for a successful response — they assign the following roles to your Service Principal:
       * **Reader** — read access to subscription resources
       * **Cost Management Reader** — access to cost and billing data
       * **Advisor Reviews Reader** — access to Azure Advisor recommendations

    <Note>
      **Multiple subscriptions:** If your resources span more than one subscription, change the subscription ID in the dialog to your second subscription and run all three commands again. Repeat for each additional subscription.
    </Note>

    <Note>
      Role assignments may take up to 5 minutes to propagate. Wait a few minutes before proceeding.
    </Note>
  </Step>

  <Step title="Step 3: Connect">
    Your credentials have been **auto-filled** from the JSON output you pasted in Step 1. Review the pre-filled values:

    * **Tenant ID**
    * **Service Principal App ID** (Client ID)
    * **Client Secret**

    Click **Connect**. Yasu will validate the connection and, once confirmed, automatically advance to the **Invite Members** step.
  </Step>

  <Step title="Wait for Verification">
    Yasu will automatically verify your connection:

    * ✅ **Authentication test** - Verifies Service Principal credentials
    * ✅ **Permission check** - Confirms required roles are assigned

    This typically takes **10-30 seconds**. If validation fails, check your credentials and ensure role assignments have propagated (wait 5 minutes after assigning roles).
  </Step>

  <Step title="Connection Complete">
    Once verified, the dialog will close and you'll see:

    * ✅ **Azure connection**: Active
    * ✅ **Onboarding progress**: Automatically advances to the next step

    <Check>
      Your first cost-saving insights will appear within **5-10 minutes** after connection.
    </Check>
  </Step>
</Steps>

## Manual Setup via Azure Portal

If you prefer to set up the Service Principal manually through the Azure Portal:

<Steps>
  <Step title="Create Application Registration">
    1. Navigate to **Azure Portal** → **Microsoft Entra ID** (Azure Active Directory)
    2. Go to **App registrations** → **+ New registration**
    3. Set **Name**: `yasu-cost-optimizer-{your-account-id}`
    4. Select **Accounts in this organizational directory only**
    5. Click **Register**
    6. **Copy the following values** (you'll need them later):
       * **Application (client) ID**
       * **Directory (tenant) ID**
  </Step>

  <Step title="Generate Client Secret">
    1. In the app registration, go to **Certificates & secrets**
    2. Click **+ New client secret**
    3. Enter a **Description**: `Yasu Access Key`
    4. Select **Expires**: Choose **24 months** (recommended)
    5. Click **Add**
    6. **Copy the secret Value immediately** - it won't be shown again

    <Warning>
      **Important:** If this secret expires, you'll need to create a new one and update it in Yasu before expiration. Set a reminder for 30 days before expiration.
    </Warning>
  </Step>

  <Step title="Assign RBAC Roles">
    The Service Principal needs the following roles at the **Subscription** scope:

    1. Navigate to **Subscriptions** → Select your subscription
    2. Go to **Access control (IAM)** → **+ Add** → **Add role assignment**
    3. Assign each role one by one:

       **Role 1: Reader**

       * **Role**: Select **Reader**
       * **Assign access to**: User, group, or service principal
       * **Select members**: Search for and select your `yasu-cost-optimizer-*` app
       * Click **Review + assign**

       **Role 2: Cost Management Reader**

       * Repeat the process with **Cost Management Reader** role

       **Role 3: Monitoring Reader**

       * Repeat the process with **Monitoring Reader** role

    <Note>
      Role assignments may take up to 5 minutes to propagate. Wait a few minutes before testing the connection.
    </Note>
  </Step>

  <Step title="Complete Connection in Yasu">
    1. Return to the **Onboarding** page in Yasu
    2. Click **Connect** next to Azure to open the connection dialog
    3. Follow Steps 1-3 in the dialog:
       * Create Service Principal using the provided Azure CLI command
       * Assign roles using the provided commands (replace placeholders)
       * Enter credentials: Tenant ID, Service Principal App ID, and Client Secret
    4. Click **Connect Azure** to complete the connection
  </Step>
</Steps>

## What the Service Principal Needs

The Service Principal is granted the following **read-only** RBAC roles at the subscription scope:

| Role | Purpose | Permissions |
| - | - | - |
| **Reader** | Read all Azure resources | `*/read` |
| **Cost Management Reader** | Access cost and billing data | `Microsoft.Consumption/*/read`, `Microsoft.CostManagement/*/read` |
| **Advisor Reviews Reader** | Access Azure Advisor recommendations | `Microsoft.Advisor/*/read` |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    **Common causes:**

    1. **Wrong tenant ID** - Verify you're using the correct Directory (tenant) ID
    2. **Wrong client ID** - Check the Application (client) ID matches your app registration
    3. **Wrong client secret** - The secret may have expired or been regenerated
    4. **Secret expired** - Create a new client secret and update it in Yasu

    **Solution:**

    ```powershell theme={null}
    # Verify credentials work
    az login --service-principal \
      --username {client-id} \
      --password {client-secret} \
      --tenant {tenant-id}

    # If failed, reset credentials
    az ad app credential reset --id {client-id}
    ```
  </Accordion>

  <Accordion title="Access denied or insufficient permissions">
    **What to check:**

    1. **Missing role assignments** - Verify all three roles are assigned (Reader, Cost Management Reader, Advisor Reviews Reader)
    2. **Role propagation delay** - Azure role assignments can take up to 5 minutes to propagate
    3. **Wrong scope** - Ensure roles are assigned at the Subscription level, not Resource Group level

    **Solution:**

    ```powershell theme={null}
    # Check current role assignments
    az role assignment list --assignee {client-id} --all

    # Add missing role
    az role assignment create \
      --assignee {client-id} \
      --role "Cost Management Reader" \
      --scope "/subscriptions/{subscription-id}"

    # Wait 5 minutes for propagation
    ```
  </Accordion>

  <Accordion title="Subscription not found">
    **What to check:**

    1. **Wrong subscription ID** - Verify the subscription ID is correct
    2. **Service Principal not granted access** - The SP needs Reader role at subscription scope
    3. **Subscription disabled** - Check subscription state in Azure Portal

    **Solution:**

    ```powershell theme={null}
    # List available subscriptions
    az account list --output table

    # Verify subscription exists and is enabled
    az account show --subscription {subscription-id}

    # Grant access to subscription
    az role assignment create \
      --assignee {client-id} \
      --role "Reader" \
      --scope "/subscriptions/{subscription-id}"
    ```
  </Accordion>

  <Accordion title="Missing cost data">
    **What to check:**

    1. **Cost Management API access** - Verify Cost Management Reader role is assigned at subscription scope
    2. **Data delay** - Cost data may take 24-48 hours to appear after first connection
    3. **Subscription billing** - Ensure the subscription has active billing and resources
    4. **Role propagation** - Wait 5 minutes after assigning roles before testing the connection

    **Solution:**

    * Verify Cost Management Reader role is assigned at the subscription level
    * Wait 24-48 hours for initial cost data sync
    * Check that the subscription has incurred charges (not in free/trial period)
    * For organization-wide cost visibility, consider using the MCA/EA/CSP setup guides
  </Accordion>

  <Accordion title="Rate limiting (429 errors)">
    **What it means:** Too many API calls in a short time period.

    **Solution:**

    * Yasu automatically implements exponential backoff
    * Large subscriptions may take longer to fully scan
    * Wait for the full sync cycle (up to 6 hours for large subscriptions)
  </Accordion>

  <Accordion title="Client secret expiration">
    **What to do:**

    1. Create a new client secret in Azure Portal (App Registration → Certificates & secrets)
    2. Update the secret in Yasu before the old one expires:
       * Go to **Settings** → **Integrations** → Your Azure connection
       * Click **Update Client Secret** or **Retry connection**
       * Enter the new secret value along with Tenant ID and Client ID
       * Save changes

    <Warning>
      **Important:** Update the secret at least 30 days before expiration to avoid service interruption.
    </Warning>
  </Accordion>

  <Accordion title="Cost data delay">
    **What it means:** Cost data may take time to appear after connecting.

    **Common causes:**

    * Cost data typically takes 24-48 hours to appear after subscription creation
    * Cost Management API may require additional time for first-time access
    * Subscription may not have incurred any charges yet

    **Solution:**

    * Wait 24-48 hours after connecting for initial cost data sync
    * Verify the subscription has active resources and billing activity
    * Check that Cost Management Reader role is correctly assigned at subscription scope
    * Ensure the subscription is not in a trial or free tier period
  </Accordion>
</AccordionGroup>

## Done!

That's it! You have successfully connected your Azure account to Yasu. Once verified, Yasu will start analyzing your Azure billing, resource usage, and performance metrics to provide optimization insights.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.