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

# Azure Cloud Integration

> Connect your Azure subscription to Backline for cloud-aware exploitability analysis

## Overview

Connect your Azure subscriptions so Backline can securely analyze your cloud environment for richer risk analysis and smarter remediation.

By integrating with Azure, Backline gains visibility into your runtime environment — including AKS clusters, App Services, Container Apps, VMs, and network configurations — to determine whether a vulnerability is actually exploitable in your specific infrastructure. This moves security prioritization from theoretical severity (CVSS scores) to **contextual exploitability**.

## What You Can Do

With the Azure Cloud integration, Backline can:

* Assess whether vulnerabilities are **actually exploitable** in your Azure environment
* Analyze AKS clusters, App Services, Container Apps, and VMs for runtime security context
* Evaluate network exposure and access controls to determine reachability
* Provide evidence-backed exploitability verdicts with cloud context (e.g., "Service is in a private VNet with no public endpoint")
* Support multiple Azure subscriptions and tenants from a single Backline workspace

## Prerequisites

Before connecting Azure Cloud, ensure you have:

* Azure CLI installed and logged in (`az login`)
* Permission to create service principals in your Entra ID tenant
* Your Azure Tenant ID (GUID)
* One or more Azure Subscription IDs where you want Backline to analyze resources
* **Owner** or **Role Based Access Control Administrator** at the relevant scope for each integration:
  * Subscription scope — to assign the Reader role via `--cloud-sub`
  * AKS cluster or resource group scope — to assign the AKS RBAC Reader role via `--aks-sub`

<Tip>
  These permissions are required to create the role assignments, not for Backline itself. Backline is granted read-only access only.
</Tip>

## Connecting Azure Cloud

Backline provides an automated installation script to set up the required service principal and permissions.

<Steps>
  <Step title="Run the Installation Script">
    Clone the [azure-integration](https://github.com/Backline-labs/azure-integration) repository and run the installation script with the flags for the integrations you want to enable:

    ```bash theme={null}
    ./scripts/azure/install_azure_integration.sh --cloud-sub <subscription-id>
    ```

    | Flag               | Description                                                                                |
    | ------------------ | ------------------------------------------------------------------------------------------ |
    | `--cloud-sub <id>` | Grants **Reader** on a subscription. Repeatable for multiple subscriptions.                |
    | `--aks-sub <id>`   | Grants **AKS RBAC Reader** on clusters in a subscription. Prompts per cluster. Repeatable. |
    | `--aks-all`        | Use with `--aks-sub` to grant access to all clusters without prompting.                    |
    | `--dry-run`        | Preview changes without applying them.                                                     |

    Flags can be combined. For example, to set up both subscription-level access and AKS cluster access in one run:

    ```bash theme={null}
    ./scripts/azure/install_azure_integration.sh \
      --cloud-sub <subscription-id> \
      --aks-sub <subscription-id> \
      --aks-all
    ```

    The script creates a service principal for Backline (if not already present) and assigns the required roles.

    <Tip>
      The script is idempotent and safe to run multiple times. Use `--dry-run` to preview changes before applying them.
    </Tip>
  </Step>

  <Step title="Copy Your Tenant ID">
    After running the script, it will output your **Tenant ID**. Save this value — you'll need it for the Backline UI.
  </Step>

  <Step title="Go to Integration Hub">
    Navigate to Integrations from the main menu in Backline.
  </Step>

  <Step title="Select Azure Cloud">
    Find and click on the Azure Cloud integration card under the **Cloud** category.
  </Step>

  <Step title="Enter Connection Details">
    In Backline, enter:

    * **Tenant ID**: Your Azure Active Directory Tenant ID (GUID format)
    * **Subscription IDs**: Comma-separated list of Azure Subscription IDs you want Backline to analyze
  </Step>

  <Step title="Connect">
    Click **Connect** to validate and save the connection. Backline will verify it can authenticate to your Azure tenant and access the specified subscriptions.
  </Step>
</Steps>

## Alternative: Admin Consent Flow

If you prefer not to use the installation script, you can grant Backline access through Azure's admin consent flow.

<Steps>
  <Step title="Grant Admin Consent">
    An Azure AD administrator navigates to the admin consent URL for the Backline application and approves the requested permissions. This creates the service principal in your tenant automatically.
  </Step>

  <Step title="Assign Reader Role">
    After the service principal is created, assign the **Reader** role on each subscription you want Backline to analyze:

    ```bash theme={null}
    az role assignment create \
      --assignee 3fc75f55-e53f-4950-9127-665106cded58 \
      --role Reader \
      --scope /subscriptions/<subscription-id>
    ```

    Replace `<subscription-id>` with each subscription's GUID.
  </Step>

  <Step title="Complete Integration in Backline">
    Return to the [Enter Connection Details](#enter-connection-details) step above and enter your Tenant ID and Subscription IDs.
  </Step>
</Steps>

## Required Permissions

The Azure Cloud integration requires:

| Permission | Scope        | Purpose                                                                 |
| ---------- | ------------ | ----------------------------------------------------------------------- |
| **Reader** | Subscription | Read-only access to Azure resources for runtime exploitability analysis |

<Tip>
  Backline follows the principle of least privilege. The Reader role grants read-only access and cannot modify any resources in your Azure environment.
</Tip>

## After Connection

Once connected, Backline begins collecting cloud context from your Azure environment, including:

* **AKS clusters**: Pod deployments, services, and network policies
* **App Services and Container Apps**: Configuration, networking, and runtime state
* **Virtual Machines**: Running state, network interfaces, and security groups
* **Network topology**: VNets, subnets, NSGs, and public IP exposure

This context is used to evaluate exploitability for every vulnerability detected in your environment, producing evidence-backed verdicts such as:

> *"This vulnerability is not exploitable because the affected service runs in an AKS cluster with no public load balancer or ingress. The pod is only accessible within the cluster's private VNet."*

## Connecting Multiple Azure Tenants

Azure Cloud supports multiple connections, allowing you to monitor several Azure tenants or subscription sets from a single Backline workspace.

<Steps>
  <Step title="Open Integration Details">
    Go to the Azure Cloud integration card in the Integration Hub and click **Configure** to open the integration details.
  </Step>

  <Step title="Add Connection">
    At the bottom of the integration details, click the **Add Connection** button.
  </Step>

  <Step title="Enter New Tenant Details">
    Provide the Tenant ID and Subscription IDs for the additional Azure tenant.
  </Step>

  <Step title="Save">
    Click **Save** to add the new connection. It will appear in the connections list alongside your existing tenants.
  </Step>
</Steps>

All connected Azure tenants are displayed in the integration details page, identified by their Tenant ID.

## AKS Access Configuration

<Note>
  This step is required only if you have AKS clusters and want Backline to read Kubernetes resources (pods, deployments, services, etc.).
</Note>

The subscription-level **Reader** role grants Backline control-plane visibility into your AKS clusters — their configuration, networking, and node pools. However, reading Kubernetes resources *inside* a cluster requires a separate authorization grant through the Kubernetes API layer.

### Why This Is Needed

AKS uses two layers of authorization:

1. **Azure RBAC** — Controls access to Azure resource management APIs (handled by the Reader role assigned during setup)
2. **Kubernetes API authorization** — Controls access to Kubernetes resources within the cluster (pods, deployments, services, etc.)

The second layer is handled by Microsoft Entra ID authorization for the Kubernetes API. Assigning the **Azure Kubernetes Service RBAC Reader** role at the cluster scope bridges these two layers, granting the Backline service principal read-only access to Kubernetes resources.

### Prerequisite: Enable Azure RBAC for Kubernetes Authorization

Each AKS cluster must have managed Entra ID integration and Azure RBAC for Kubernetes Authorization enabled. For existing clusters, run:

```bash theme={null}
az aks update \
  --resource-group <resource-group> \
  --name <cluster-name> \
  --enable-azure-rbac
```

<Tip>
  New clusters can be created with `--enable-aad --enable-azure-rbac` flags to have this enabled from the start. See [Microsoft's documentation](https://learn.microsoft.com/en-us/azure/aks/manage-azure-rbac) for details.
</Tip>

### Configure AKS Access

Use the installation script with the `--aks-sub` flag, passing the subscription IDs that contain your AKS clusters:

```bash theme={null}
./scripts/azure/install_azure_integration.sh --aks-sub <subscription-id>
```

The script lists all AKS clusters found in the subscription and prompts you to confirm access for each one individually. To grant access to all clusters without prompting:

```bash theme={null}
./scripts/azure/install_azure_integration.sh --aks-sub <subscription-id> --aks-all
```

For multiple subscriptions:

```bash theme={null}
./scripts/azure/install_azure_integration.sh \
  --aks-sub <subscription-id-1> \
  --aks-sub <subscription-id-2> \
  --aks-all
```

<Tip>
  Use `--dry-run` to preview which clusters would be configured without making any changes.
</Tip>

<Note>
  **Owner** or **Role Based Access Control Administrator** on the AKS cluster or its resource group is required to create the role assignment. Subscription-level Reader is sufficient to enumerate the clusters.
</Note>

### Adding New AKS Clusters

When you create new AKS clusters, re-run the script with `--aks-sub` to grant Backline access to the new clusters:

```bash theme={null}
./scripts/azure/install_azure_integration.sh --aks-sub <subscription-id>
```

### Troubleshooting AKS Access

If Backline cannot read Kubernetes resources from your AKS clusters:

1. **Verify the role assignment exists**:
   ```bash theme={null}
   az role assignment list \
     --scope $AKS_ID \
     --assignee $SP_OBJECT_ID \
     --query "[].roleDefinitionName" \
     -o tsv
   ```

2. **Verify Azure RBAC for Kubernetes is enabled on the cluster**:
   ```bash theme={null}
   az aks show \
     --resource-group <resource-group> \
     --name <cluster-name> \
     --query "aadProfile.enableAzureRbac"
   ```
   The output should be `true`. If it is `null` or `false`, run the `az aks update --enable-azure-rbac` command from the prerequisite step.

3. **Wait for propagation**: New role assignments can take up to five minutes to propagate before they take effect.

## Managing the Integration

### Removing Subscription Access

To remove Backline's access from specific subscriptions, use the cleanup script:

```bash theme={null}
./scripts/azure/cleanup_azure_integration.sh --cloud-sub <subscription-id>
```

### Disconnecting

To remove the Azure Cloud integration:

1. Go to the Integration Hub
2. Click on the Azure Cloud integration
3. Select **Disconnect**
4. Confirm your choice

<Warning>
  Disconnecting will stop cloud-aware exploitability analysis for your Azure environment. Existing vulnerability data will remain but won't include Azure runtime context.
</Warning>

## Troubleshooting

### Consent Error (401)

**Symptom**: Test connection fails with "unauthorized" or "consent required" error.

**Cause**: The Backline service principal has not been created in your Azure AD tenant. This happens when neither the installation script nor the admin consent flow has been completed.

**Resolution**:

* Run the [installation script](#connecting-azure-cloud), or
* Complete the [admin consent flow](#alternative-admin-consent-flow) to create the service principal

### Role Assignment Error (403)

**Symptom**: Test connection fails with "forbidden" or "authorization failed" error.

**Cause**: The service principal exists in your tenant but does not have **Reader** role on the specified subscriptions.

**Resolution**:
Assign the Reader role on each subscription:

```bash theme={null}
az role assignment create \
  --assignee 3fc75f55-e53f-4950-9127-665106cded58 \
  --role Reader \
  --scope /subscriptions/<subscription-id>
```

### Invalid Tenant ID or Subscription ID

**Symptom**: Validation error when entering connection details.

**Cause**: Tenant ID and Subscription IDs must be valid GUIDs in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.

**Resolution**:

* Find your Tenant ID: `az account show --query tenantId -o tsv`
* List your Subscription IDs: `az account list --query "[].id" -o tsv`