> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Azure Blob Storage (Direct OAuth)
Connect Azure Blob Storage to Athena to browse containers, read blobs in chat,
and upload files — each member acting as their own Microsoft Entra identity, with
Azure RBAC deciding exactly what they can read or write. Athena never holds
account keys or SAS tokens.
Setup is two steps, done by two different people: your **Azure administrator**
registers an Entra app and assigns RBAC roles, then an **Athena workspace
admin** saves that app once for the whole workspace. Members can only connect
after both are done.
This integration covers Azure Public Cloud blob endpoints
(`*.blob.core.windows.net`). Azure Government, Azure China, and Azure Stack use
different login authorities and are not supported.
## Step 1 — Register an Entra ID application (Azure admin)
1. **Microsoft Entra admin center → App registrations → New registration**. Name
it e.g. `Athena — Azure Blob`, supported account types **single tenant**.
2. **Redirect URI**: platform **Web**, value:
```
https://api.athenaintel.com/api/azure-blob-direct/oauth/callback
```
Entra matches redirect URIs as exact strings — trailing slashes or scheme
mismatches fail the handshake.
3. **API permissions → Add a permission → Azure Storage → Delegated permissions →
`user_impersonation`**, then **Grant admin consent for your tenant**.
4. **Certificates & secrets → New client secret**. Microsoft caps the lifetime at
24 months and recommends 12 months or less — set a reminder to rotate. Copy
the **Value** immediately.
5. **Overview**: copy the **Application (client) ID** and **Directory (tenant)
ID**.
## Step 2 — Assign Azure RBAC on the storage account (Azure admin)
Every member who connects needs one of these built-in roles on the storage
account or on the specific container:
| Role | What the member can do |
| ------------------------------- | --------------------------------------------------- |
| `Storage Blob Data Reader` | List containers and blobs, read blobs |
| `Storage Blob Data Contributor` | Read, write, and delete blobs — recommended default |
| `Storage Blob Data Owner` | Read, write, delete, and set ACLs |
The container picker lists containers using an account-level call. Members who
only have **container-scoped** RBAC will see an empty picker — they can type
the container name manually, and reading and writing still works. RBAC
assignments can take a few minutes to propagate.
## Step 3 — Enable Azure Blob in Athena (workspace admin, once)
An **Athena workspace admin or owner** must add the app on the Athena side for
the **entire workspace** — this is not something individual members can do, and
the connect option stays hidden until it's configured.
Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**,
expand **Azure Blob**, click **Add app**, and fill in:
| Field | Value |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| **Display name** | The label members see in the connect picker |
| **Tenant ID** | Directory (tenant) ID from step 1.5 |
| **Client ID** | Application (client) ID from step 1.5 |
| **Client Secret** | The secret **Value** from step 1.4 (write-only — leave blank when editing to keep the current one) |
| **Default Storage Account** | Optional — pre-fills the connect dialog |
Toggle the app on and **Save app**. You can add more than one app — for example
one per tenant or per storage-account scope — and members get a dropdown to pick
which one to authorize against. Secrets are encrypted at rest and never returned
to the browser.
## Step 4 — Members connect (each user)
1. Go to **[Integrations](https://app.athenaintel.com/dashboard/integrations/)**
and click **Azure Blob Storage → Connect**.
2. Enter the storage account name (or accept the workspace default), pick the app
if more than one is enabled.
3. Sign in to Microsoft and consent.
4. Pick a container from the picker, or type its name. Athena creates a private
catalog per account/container that only you can use. You can connect several.
## Troubleshooting
| Symptom | Cause and fix |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Callback error mentioning a token audience that isn't `https://storage.azure.com` | The Entra app is missing **Azure Storage → Delegated → `user_impersonation`** with admin consent. Add it and reconnect. |
| `401` when listing or reading blobs | Same cause as above — wrong token audience or missing Storage scope. |
| `403` mentioning the `Storage Blob Data Reader` role | The member authenticated fine but has no Azure RBAC role at account or container scope. Assign one and wait a few minutes. |
| Empty container picker, but the member can read a container they name manually | Container-scoped RBAC only. Expected — see the note above. |
| "Entra did not return a refresh\_token" | Athena always requests `offline_access`, so the tenant is refusing it — check that the app registration allows the `offline_access` delegated permission and that no policy blocks it, then reconnect. |
| No Azure Blob connect option on the Integrations page | A workspace admin hasn't completed step 3. |
Tokens are per-user, encrypted at rest, and refreshed automatically. Azure RBAC
remains the source of truth for access — revoking a role revokes what Athena
can do for that member.