> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Azure Connector
> Connect Ana to Microsoft Azure to analyze files in Blob Storage and query Azure APIs with fully managed authentication.
### **1. Overview**
The Microsoft Azure integration authenticates Ana to your Azure tenant using an Entra ID app registration (service principal). TextQL manages authentication end to end: Ana's requests to Azure endpoints are automatically authenticated server-side, so no tokens, secrets, or OAuth flows ever appear in analysis code. This works across Azure Storage (Blob, Data Lake, Queue, Table), Azure Resource Manager, Microsoft Graph, and Key Vault endpoints.
The most common use case is Azure Blob Storage: point Ana at a container of reports, exports, or data files and it can list and read them directly — no authentication code required.
### **2. Prerequisites**
You'll need:
* An Azure account with permission to create an app registration in Microsoft Entra ID (or an existing app registration).
* Permission to assign roles on the resources you want Ana to reach (e.g. a storage account).
* A TextQL account with permission to add or configure connectors.
### **3. Capabilities**
Once configured, Ana can:
* List and read files in Azure Blob Storage containers (CSV, Excel, Parquet, PDF, JSON) and analyze their contents.
* Query Azure Resource Manager APIs for resource, cost, and infrastructure data.
* Call Microsoft Graph endpoints permitted by the app registration's API permissions.
* Combine data retrieved from Azure with your other connected sources in a single analysis.
### **4. Setup Instructions**
***
### Step 1: Create an app registration and client secret
1. Go to the [Azure Portal](https://portal.azure.com) and open **Microsoft Entra ID**.
2. In the left sidebar, click **App registrations**, then **New registration**.
3. Give it a name (e.g. `textql-connector`), leave the defaults, and click **Register**.
4. On the app's **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID**.
5. Go to **Certificates & secrets** > **Client secrets** > **New client secret**, set an expiry, and click **Add**.
6. Copy the secret **Value** immediately — it is shown only once.
### Step 2: Grant data-plane roles on the resources Ana should reach
A successful login is not enough for Azure Storage. The app registration must hold a **data-plane RBAC role** on the storage account or container — control-plane roles like Owner or Contributor do **not** grant blob read access. This is the most common setup mistake.
For Blob Storage access:
1. Open the storage account (or a specific container) in the Azure Portal.
2. Go to **Access Control (IAM)** > **Add role assignment**.
3. Select **Storage Blob Data Reader** (read-only, recommended) or **Storage Blob Data Contributor** if Ana should also write.
4. Under **Members**, select your app registration and save.
Role assignments can take a few minutes to propagate.
If your storage account restricts network access (**Networking** > "Enabled from selected virtual networks and IP addresses"), also allow your TextQL deployment's egress IP there — RBAC and network rules are checked independently, and either one alone can produce a 403.
### Step 3: Add Azure as an API connector in TextQL
1. Go to app.textql.com and sign in.
2. In the bottom left sidebar, click **Connectors > APIs** and select **Microsoft Azure**.
3. In the configuration panel, fill in:
* Name: a label for this connection (e.g. `Azure - Data Lake`)
* Directory (tenant) ID: from Step 1.
* Application (client) ID: from Step 1.
* Client Secret Value: the secret value from Step 1.
4. *(Recommended for Blob Storage)* Expand **Advanced** and set the **Test URL** to a container list request, so the connection test verifies your role assignment end to end:
```
https://.blob.core.windows.net/?restype=container&comp=list
```
5. Click **Save**.
### Step 4: Verify the connection
1. Click on the Azure connector and select **Test Connection** at the bottom of the panel.
* A successful setup returns Connection successful (200).
* With a Blob Test URL configured, a 403 at this step means the role assignment from Step 2 is missing or hasn't propagated yet — see [Troubleshooting](#6-troubleshooting).
***
### **5. Usage Examples**
Once configured, you can ask Ana:
* "List the files in the `monthly-reports` container and summarize what's there."
* "Read `exports/leasing_activity_report.xlsx` from blob storage and chart occupancy by property."
* "Pull all CSVs under the `finance/2026/` prefix and consolidate them into one normalized table."
* "What did our Azure spend look like by service over the last three months?"
Ana's requests to Azure are authenticated automatically — analysis code makes plain HTTPS requests and TextQL attaches the right credentials server-side, scoped per Azure service.
### **6. Troubleshooting**
| **Symptom** | **Likely Cause** | **Fix** |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Token exchange failed / invalid client | Tenant ID, client ID, or secret is wrong, or the secret expired | Verify all three values; create a new client secret if expired and update the connector. |
| 403 AuthorizationPermissionMismatch on blob access | App registration authenticated but lacks a data-plane role | Assign **Storage Blob Data Reader** (or higher) on the storage account or container, wait a few minutes, and re-test. |
| 403 AuthorizationFailure on blob access | Storage account network rules (firewall / IP restrictions) blocked the request — this is not a role problem | Allow your TextQL deployment's egress IP under the storage account's **Networking** settings, or disable the IP restriction. |
| 401 on legacy `/oauth2/token` requests | Analysis code using the retired Azure AD v1 endpoint, which TextQL's managed authentication does not support | None needed — remove any custom auth code. Plain requests to Azure endpoints are authenticated automatically via the v2 flow. |
| Blob requests rejected with a version error | Custom code overriding the `x-ms-version` header with an outdated value | Remove the override; TextQL sets a compatible version automatically. |
### **7. Security Notes**
* Client secrets expire on the schedule you set in Entra ID. Rotate them before expiry and update the connector to avoid interruptions.
* Access is bounded by the RBAC roles assigned to the app registration, not by the integration. Grant read-only, narrowly scoped roles (e.g. Storage Blob Data Reader on one container) to keep the integration analysis-only. **The app registration's RBAC scope is the security boundary**: any storage account those roles can reach, Ana can reach.
* To additionally restrict which endpoints Ana may call, edit the **Hosts** list under **Advanced** in the connector form — e.g. replace the default wildcards with the exact account hostname (`https://myaccount.blob.core.windows.net:443`) so requests to any other storage account are blocked at the proxy regardless of RBAC.
* Credentials are encrypted at rest and are never exposed to analysis code — authentication happens server-side, and requests are restricted to an allowlist of Azure hosts.
* How to revoke access: delete the client secret (or the app registration) in Microsoft Entra ID, or remove its role assignments.
***
### **Need Help?**
For further assistance, please contact [support@textql.com](mailto:support@textql.com).
### **Privacy Policy**
For information about how we handle your data and protect your privacy, please review our [Privacy Policy](https://textql.com/privacy).