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

# Azure

> Give Traversal read-only visibility into your Azure environment — resource configuration, change history, and Azure Monitor logs and metrics.

Connecting Azure lets Traversal's agent inspect your Azure environment during investigations: what's configured and running right now, what changed recently, whether Azure itself is having a problem, and your Azure Monitor logs and metrics. Access is read-only by design — Traversal cannot create, modify, or delete anything in your Azure environment.

One connection covers both: Azure Resource Manager (resource inventory, change history, access metadata) and Azure Monitor (logs and metrics) are the same integration, connected once.

[Azure DevOps](/integrations/azure-devops) (source control, pipelines) is a separate integration — connect it independently if you use Azure DevOps.

<Note>
  This integration covers Azure Commercial Cloud. We don't support Azure Government or other sovereign/national clouds at this time.
</Note>

## What Traversal reads

* **Resource inventory and configuration** — via Azure Resource Graph
* **Change history** — via the Activity Log, scoped to your subscriptions
* **Resource and Service Health** — whether Azure itself is reporting a problem
* **Access and identity metadata** — role assignments (metadata only, never secret values)
* **Azure Monitor Logs** — Log Analytics workspace queries (KQL)
* **Azure Monitor Metrics** — platform and custom metrics

## How it works

Traversal authenticates to your Azure tenant using a short-lived, secretless credential (Microsoft Entra Workload Identity Federation) — no password, API key, or secret is ever shared or stored, by either side.

You create and own the identity Traversal authenticates as, entirely inside your own tenant: a user-assigned managed identity or an app registration, trusted to a specific Traversal Kubernetes cluster via a federated credential, and granted the roles below on exactly the subscriptions you choose. Traversal never registers or owns anything inside your tenant — you give Traversal the resulting identity's **Client ID**, along with your tenant ID, and that's the entire handoff.

Every API call uses a token that expires within minutes, re-issued fresh for each request.

You connect at the **tenant** level. Every subscription your identity can see is discovered automatically — you don't need to list subscriptions individually.

## Required roles

Two roles cover everything Traversal needs:

| Role | Unlocks |
| - | - |
| **Reader** | Resource inventory, configuration, change history, Resource/Service Health, access/identity metadata, and Azure Monitor Metrics. |
| **Log Analytics Reader** | Querying the *contents* of Log Analytics workspaces. Without this, Traversal can see that a workspace exists but not what's in it. |

No Contributor, data-plane, or Cost Management Reader access is ever requested.

<Note>
  A Log Analytics workspace lives in its own subscription, separate from the subscriptions whose resources send logs into it (common if you centralize logging into a shared subscription). Grant **Log Analytics Reader** on the subscription that hosts the workspace itself — granting it only on the subscriptions holding the resources you care about won't give Traversal access to that workspace's contents. Without it, Traversal will report "no logs found" for resources that do have logs.
</Note>

## Setup

The fastest path is the Bicep template below. Prefer doing it by hand, or need an app registration instead of a managed identity? Skip to the manual steps underneath.

<Steps>
  <Step title="Download and deploy the Bicep template">
    In Traversal, go to **Company Knowledge > Integrations**, select Azure, and download the Bicep template. It's pre-filled with Traversal's cluster OIDC issuer, so you only need to supply your own values when deploying:

    ```bash theme={null}
    az deployment sub create --location <location> \
      --template-file traversal-azure-managed-identity.json \
      --parameters resourceGroupName=<your-resource-group> \
                   roleAssignmentScopes='["<subscription-id>"]'
    ```

    This creates a managed identity, federates it to trust Traversal's cluster, and grants it Reader and Log Analytics Reader on the subscription(s) you listed. Repeat the deploy (or pass more subscription IDs in `roleAssignmentScopes`) for every subscription you want visible — including the one hosting your Log Analytics workspace(s), if that's different from the subscriptions holding the resources you want investigated.
  </Step>

  <Step title="Add the integration in Traversal">
    The deployment's output includes the identity's **Client ID**. In Traversal, go to **Company Knowledge > Integrations**, select Azure, and enter that Client ID along with your tenant ID.
  </Step>
</Steps>

<Note>
  Need to grant roles across a whole management group instead of listing subscriptions one by one? Leave `roleAssignmentScopes` empty above (so the first deployment only creates the identity), then deploy a second Bicep template:

  ```bash theme={null}
  curl -O https://templates.traversal.com/integrations/modules/management-group-role-assignment.json
  az deployment mg create --management-group-id <management-group-id> --location <location> \
    --template-file management-group-role-assignment.json \
    --parameters principalId=<principalId from the first deployment's output>
  ```
</Note>

## Manual setup

You can use either a **managed identity** or an **app registration** as the identity Traversal authenticates as. A managed identity is simpler and has no client secret that could later be created by mistake — use it unless your organization's permissions make an app registration easier to set up.

<Tabs>
  <Tab title="Managed identity (recommended)">
    <Steps>
      <Step title="Create a managed identity">
        In the Azure Portal: **Managed Identities > Create**. Name it, pick a resource group and region, and create it.

        Or with the Azure CLI:

        ```bash theme={null}
        az identity create --name traversal-access --resource-group <your-resource-group> --location <location>
        ```
      </Step>

      <Step title="Add federated credentials">
        Add the same federated credentials the Bicep template above creates — the Client ID field on the Azure integration tile (**Company Knowledge > Integrations > Azure**) lists the exact issuer and every subject to use. On the identity: **Federated credentials > Add credential**, scenario **"Kubernetes accessing Azure resources"**, with audience `api://AzureADTokenExchange`.

        Or with the Azure CLI, once per subject:

        ```bash theme={null}
        az identity federated-credential create --name <a name for this credential> \
          --identity-name traversal-access --resource-group <your-resource-group> \
          --issuer "<issuer from the Azure integration tile>" \
          --subject "<a subject from the Azure integration tile>" \
          --audiences api://AzureADTokenExchange
        ```
      </Step>

      <Step title="Grant roles">
        Assign both roles below to the identity on each subscription you want visible:

        ```bash theme={null}
        PRINCIPAL_ID=$(az identity show -n traversal-access -g <your-resource-group> --query principalId -o tsv)

        for role in "Reader" "Log Analytics Reader"; do
          az role assignment create --assignee-object-id "$PRINCIPAL_ID" \
            --assignee-principal-type ServicePrincipal \
            --role "$role" --scope /subscriptions/<subscription-id>
        done
        ```

        Repeat for each additional subscription — including the subscription that hosts your Log Analytics workspace(s), if that's different from the subscriptions holding the resources you want investigated.
      </Step>

      <Step title="Add the integration in Traversal">
        Get the identity's Client ID and your tenant ID:

        ```bash theme={null}
        az identity show -n traversal-access -g <your-resource-group> --query clientId -o tsv
        az account show --query tenantId -o tsv
        ```

        In Traversal, go to **Company Knowledge > Integrations**, select Azure, and enter both values.
      </Step>
    </Steps>
  </Tab>

  <Tab title="App registration">
    <Steps>
      <Step title="Create an app registration">
        In the Azure Portal: **App registrations > New registration**. Name it and choose **"Accounts in this organizational directory only"** — this app never needs to be visible outside your tenant.
      </Step>

      <Step title="Add federated credentials">
        Add the same federated credentials the Bicep template above creates — the Client ID field on the Azure integration tile (**Company Knowledge > Integrations > Azure**) lists the exact issuer and every subject to use. On the app: **Certificates & secrets > Federated credentials > Add credential > "Other issuer"**, with audience `api://AzureADTokenExchange`. No client secret is needed or created.
      </Step>

      <Step title="Grant roles">
        Assign both roles below to the app's service principal on each subscription you want visible:

        ```bash theme={null}
        for role in "Reader" "Log Analytics Reader"; do
          az role assignment create --assignee <app's Client ID> --role "$role" --scope /subscriptions/<subscription-id>
        done
        ```

        Repeat for each additional subscription — including the subscription that hosts your Log Analytics workspace(s), if that's different from the subscriptions holding the resources you want investigated.
      </Step>

      <Step title="Add the integration in Traversal">
        In Traversal, go to **Company Knowledge > Integrations**, select Azure, and enter the app's Client ID and your tenant ID (both visible on the app's Overview page).
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  To connect another identity — in the same tenant or a different one — repeat these steps: Azure supports multiple integration instances, one per identity.
</Tip>

## Private network access

If the service endpoint is not directly reachable by Traversal (as is common with self-hosted services), deploy a [Traversal Connector](/architecture/connector) in a network that can reach it. When configuring the integration, select that connector under **Network Access Needed**. The service endpoint does not need public internet exposure.

See [Set up the Traversal Connector](/setup/connector) for deployment and network requirements.

<Note>
  Authentication is identical either way — a Connector only changes which network the Azure calls come from, not how Traversal authenticates.
</Note>

## More information

* [Finding your Microsoft Entra tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant)
* [Azure built-in roles reference](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles)
* [Azure DevOps integration](/integrations/azure-devops)


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