> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Azure

> Connect Aurora to your Azure subscription using service principal credentials

## Overview

Aurora integrates with Microsoft Azure using service principal (application) credentials. This provides secure, programmatic access to your Azure subscription without using personal credentials.

## What Aurora Can Access

Once authenticated, Aurora can discover and manage:

* **AKS Clusters**: Azure Kubernetes Service clusters
* **Virtual Machines**: Compute instances and scale sets
* **Azure SQL**: Managed database services
* **Storage Accounts**: Blob, file, queue, and table storage
* **Azure Functions**: Serverless compute
* **Virtual Networks**: VNets, subnets, and network security groups
* **Container Instances**: Azure Container Instances (ACI)
* **App Services**: Web apps and APIs
* **Resource Groups**: Logical containers for Azure resources
* **Cost Management**: Billing and usage data

## Prerequisites

<Steps>
  <Step title="Azure Subscription">
    You need an active Azure subscription with administrative access
  </Step>

  <Step title="Azure CLI or Portal Access">
    You'll need access to Azure CLI or Azure Portal to create service principals
  </Step>

  <Step title="Required Permissions">
    You need permissions to create service principals and assign roles at the subscription level
  </Step>
</Steps>

## Environment Variables

Configure these environment variables in Aurora's `.env` file:

```bash theme={null}
# Azure OAuth Configuration (optional, for OAuth flow)
AZURE_CLIENT_ID=your-aurora-app-client-id
AZURE_CLIENT_SECRET=your-aurora-app-client-secret

# Frontend URL for redirects
FRONTEND_URL=https://your-aurora-frontend.com
```

<Info>
  These environment variables are for Aurora's OAuth app registration, not your service principal. Service principal credentials are provided during setup and stored securely in Vault.
</Info>

## Authentication Methods

Aurora supports two authentication methods for Azure:

### 1. Service Principal (Recommended)

Use application credentials for programmatic access.

### 2. OAuth Flow (Legacy)

User-based authentication through Microsoft Entra ID (formerly Azure AD).

<Note>
  Service principal authentication is recommended for production use as it provides better security and doesn't require interactive login.
</Note>

## Setup Instructions

### Method 1: Using Azure Portal

<Steps>
  <Step title="Open Azure Portal">
    Navigate to [Azure Portal](https://portal.azure.com/)
  </Step>

  <Step title="Go to App Registrations">
    Search for "App registrations" in the top search bar
  </Step>

  <Step title="Create New Registration">
    Click **New registration**

    * Name: `Aurora Service Principal`
    * Supported account types: **Accounts in this organizational directory only**
    * Redirect URI: Leave empty
    * Click **Register**
  </Step>

  <Step title="Copy Application (Client) ID">
    On the Overview page, copy the **Application (client) ID** - this is your `clientId`
  </Step>

  <Step title="Copy Directory (Tenant) ID">
    Also copy the **Directory (tenant) ID** - this is your `tenantId`
  </Step>

  <Step title="Create Client Secret">
    Go to **Certificates & secrets** > **New client secret**

    * Description: `Aurora Access`
    * Expires: Choose appropriate duration (e.g., 24 months)
    * Click **Add**
    * Copy the **Value** (not the Secret ID) - this is your `clientSecret`
  </Step>

  <Step title="Assign Subscription Role">
    Go to **Subscriptions** > Select your subscription > **Access control (IAM)**

    * Click **Add role assignment**
    * Role: **Contributor** (for full access) or **Reader** (for read-only)
    * Assign access to: **User, group, or service principal**
    * Select members: Search for "Aurora Service Principal" and select it
    * Click **Review + assign**
  </Step>

  <Step title="Copy Subscription ID">
    In Subscriptions, copy your **Subscription ID**
  </Step>
</Steps>

### Method 2: Using Azure CLI

Run the provided setup script to automate service principal creation:

<CodeGroup>
  ```bash Bash Script theme={null}
  # Download and run the setup script
  curl -O https://your-aurora-backend.com/azure/setup-script
  chmod +x setup-aurora-access.sh
  ./setup-aurora-access.sh
  ```

  ```powershell PowerShell Script theme={null}
  # Download and run the PowerShell script
  Invoke-WebRequest -Uri "https://your-aurora-backend.com/azure/setup-script-ps1" -OutFile "setup-aurora-access.ps1"
  .\setup-aurora-access.ps1
  ```
</CodeGroup>

The script will:

1. Create a service principal with a random name
2. Assign Contributor role to your subscription
3. Generate a client secret
4. Display the credentials needed for Aurora

### Method 3: Manual Azure CLI Commands

```bash theme={null}
# Login to Azure
az login

# Create service principal
az ad sp create-for-rbac --name "Aurora-SP" --role Contributor \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID

# Output will contain:
# {
#   "appId": "YOUR_CLIENT_ID",
#   "password": "YOUR_CLIENT_SECRET",
#   "tenant": "YOUR_TENANT_ID"
# }
```

## Connecting Aurora

<Steps>
  <Step title="Open Aurora UI">
    Navigate to the Azure integration page
  </Step>

  <Step title="Enter Service Principal Credentials">
    Provide the following information:

    * **Tenant ID**: Directory (tenant) ID from Azure
    * **Client ID**: Application (client) ID from app registration
    * **Client Secret**: Client secret value you created
    * **Subscription ID**: Your Azure subscription ID
    * **Subscription Name**: (Optional) Friendly name for display
  </Step>

  <Step title="Optional: Read-Only Credentials">
    For Ask mode, optionally provide a separate service principal with Reader role:

    ```json theme={null}
    {
      "readOnlyCredentials": {
        "tenantId": "tenant-id",
        "clientId": "read-only-client-id",
        "clientSecret": "read-only-client-secret",
        "subscriptionId": "subscription-id"
      }
    }
    ```
  </Step>

  <Step title="Validate Connection">
    Click **Connect** - Aurora will validate credentials and fetch subscription details
  </Step>

  <Step title="Verify Access">
    Aurora will list your AKS clusters and enabled subscriptions to confirm access
  </Step>
</Steps>

## API Endpoints

### Login with Service Principal

```http theme={null}
POST /azure/login
Content-Type: application/json

{
  "userId": "user-id",
  "tenantId": "your-tenant-id",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "subscriptionId": "your-subscription-id",
  "subscriptionName": "Production Subscription"
}
```

Alternate field names are also supported:

* `tenant` instead of `tenantId`
* `appId` instead of `clientId`
* `password` instead of `clientSecret`
* `subscription_id` instead of `subscriptionId`

### Fetch Subscription Data

```http theme={null}
GET /azure/fetch_data
Headers: X-User-ID: your-user-id
```

Returns subscription details and validates stored credentials.

### List AKS Clusters

```http theme={null}
GET /azure/clusters
Headers: X-User-ID: your-user-id
```

Returns all AKS clusters in the connected subscription.

### Get Subscriptions

```http theme={null}
GET /api/azure-subscriptions
Headers: X-User-ID: your-user-id
```

Returns connected Azure subscription information.

## AKS Cluster Access

Aurora can connect to AKS clusters using two methods:

### 1. Admin Credentials (Default)

For clusters with local admin account enabled:

* Aurora calls `listClusterAdminCredential` API
* Retrieves kubeconfig with cluster admin access
* Creates Kubernetes client for direct cluster management

### 2. Azure AD Integration (Fallback)

For clusters with static credentials disabled:

* Aurora acquires an Azure AD token for AKS
* Uses resource ID `6dae42f8-4368-4678-94ff-3960e28e3630` (AKS well-known ID)
* Creates Kubernetes client with AAD token authentication

## Metrics Server Deployment

Aurora automatically checks for and deploys Kubernetes Metrics Server on AKS clusters if not already installed. This enables:

* Pod and node metrics collection
* Horizontal Pod Autoscaling (HPA)
* Resource usage monitoring

## Troubleshooting

### Authentication Failed

**Error**: "Invalid Azure credentials"

**Solution**:

1. Verify tenant ID, client ID, and client secret are correct
2. Check that the service principal exists in Azure AD
3. Ensure the client secret hasn't expired
4. Confirm you're using the secret **Value**, not the Secret ID

### No Enabled Subscription Found

**Error**: "No enabled subscription found"

**Solution**:

1. Verify your Azure subscription is in "Enabled" state (not disabled or expired)
2. Check that the service principal has access to at least one subscription
3. Go to Azure Portal > Subscriptions to verify subscription status

### Insufficient Permissions

**Error**: "Failed to fetch AKS clusters" or similar permission errors

**Solution**:

1. Verify the service principal has **Contributor** or **Reader** role
2. Check role assignment at the subscription level (not resource group)
3. Wait a few minutes for role assignments to propagate
4. Verify using Azure CLI:
   ```bash theme={null}
   az role assignment list --assignee YOUR_CLIENT_ID --all
   ```

### AKS Access Denied

**Error**: "Admin credentials failed" when accessing AKS

**Solution**:

1. Check if the cluster has local admin account disabled
2. Enable local accounts: `az aks update --enable-local-accounts`
3. Alternatively, Aurora will fall back to AAD authentication
4. Ensure service principal has `Azure Kubernetes Service Cluster User Role`

### Token Generation Failed

**Error**: "Failed to get Azure token"

**Solution**:

1. Verify client secret is valid and not expired
2. Check network connectivity to `login.microsoftonline.com`
3. Ensure tenant ID is correct
4. Try regenerating the client secret

### SSL Certificate Errors

**Warning**: Kubernetes client SSL verification disabled

**Context**: Aurora disables SSL verification for AKS clusters in containerized environments to avoid certificate issues. This is standard practice for trusted AKS clusters.

**For production**: Consider enabling SSL verification and providing trusted CA certificates.

### Graph API Permission Errors

**Error**: "Service principal not found" when fetching object ID

**Solution**:

1. Ensure service principal has Microsoft Graph API permissions
2. Grant `Application.Read.All` permission (admin consent required)
3. Wait for permissions to propagate (up to 10 minutes)

## Security Considerations

* **Client Secrets**: Stored securely in HashiCorp Vault with encryption at rest
* **Service Principal Scope**: Limit role assignments to specific subscriptions/resource groups when possible
* **Secret Expiration**: Regularly rotate client secrets (set expiration in Azure Portal)
* **Least Privilege**: Use **Reader** role for Ask mode, **Contributor** for Do mode
* **Audit Logs**: Monitor Azure Activity Logs for actions performed by the service principal
* **Token Lifetime**: Management tokens expire after \~1 hour and are automatically refreshed

## Token Management

* **Access Tokens**: Valid for \~1 hour, automatically refreshed using client credentials
* **Management Token**: Generated for `https://management.azure.com/.default` scope
* **Graph Token**: Generated for `https://graph.microsoft.com/.default` scope (if needed)
* **AKS Token**: Generated for `6dae42f8-4368-4678-94ff-3960e28e3630/.default` scope
* **Storage**: Tokens stored in Vault with subscription ID and name metadata

## Supported Azure Regions

Aurora supports all Azure public cloud regions. For Azure Government or Azure China, contact support for configuration assistance.

## Next Steps

After connecting Azure:

1. Aurora will discover your Azure infrastructure
2. View discovered resources in the Aurora dashboard
3. Use Aurora's AI agent to manage Azure resources
4. Deploy applications to AKS clusters
5. Monitor costs and optimize resource usage