> ## 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 SQL (Direct OAuth)
Connect Azure SQL to Athena so each member can query your databases as
themselves — no shared SQL login, no password to paste. Athena signs each user
in through **Microsoft Entra ID** and runs every query with that user's own
Entra identity, so row-level security and database grants apply unchanged.
Setup is two steps, and they are done by two different people: your **Azure
administrator** registers an app in Entra ID and grants database access, then
an **Athena workspace admin** saves that app once for the whole workspace.
Individual members can only connect after both steps are done.
## What this works against
| Target | Supported | Notes |
| ---------------------------------- | --------------------- | ----------------------------------------------------------------------------------- |
| Azure SQL Database (PaaS) | Yes | Entra access token |
| Azure SQL Managed Instance | Yes | Same as Azure SQL Database |
| SQL Server 2022 + Azure Arc | Yes, with extra setup | Requires the Arc agent and certificate from Microsoft's Entra-auth-for-Arc tutorial |
| On-prem SQL Server 2019 or earlier | No | No OAuth support in the product |
## Step 1 — Register an Entra ID application (Azure admin)
1. **Azure Portal → Microsoft Entra ID → App registrations → New
registration**. Name it something recognizable, e.g. `Athena — Azure SQL`.
2. **Supported account types**: single tenant is the usual choice. Pick
multitenant only if guest users from partner tenants must connect.
3. **Redirect URI**: platform **Web**, value:
```
https://api.athenaintel.com/api/azure-sql-direct/oauth/callback
```
Entra compares redirect URIs as exact strings — a stray trailing slash or
`http` instead of `https` will fail the handshake.
4. **API permissions → Add a permission → Azure SQL Database → Delegated
permissions → `user_impersonation`**, then **Grant admin consent** so members
aren't prompted individually.
5. **Certificates & secrets → New client secret**. Copy the secret **Value**
immediately — Entra shows it only once.
6. **Overview**: copy the **Application (client) ID** and **Directory (tenant)
ID**.
### Allow Athena through the SQL server firewall
Azure SQL denies all inbound connections by default. Your DBA must add a
firewall rule for Athena's egress IP, otherwise the first connection fails with
error `40615` ("Client with IP address … is not allowed to access the server").
Contact [team@athenaintel.com](mailto:team@athenaintel.com) for the current
egress IP for your environment.
Firewall rules take up to five minutes to propagate. Azure SQL **Serverless**
databases also auto-pause after inactivity — the first query after a pause can
take 30–60 seconds while the database resumes.
### Create a database user for each Athena user
Azure SQL maps Entra tokens to **contained database users**. Every member who
will query a database needs a user in that database, otherwise the connection
authenticates but the query fails with "Login failed for user". For each target
database, connect as an Entra admin and run:
```sql theme={null}
-- For a security group (recommended — grant once, manage membership in Entra)
CREATE USER [Athena Analysts] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [Athena Analysts];
-- Or for an individual user
CREATE USER [alice@contoso.com] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [alice@contoso.com];
```
## Step 2 — Enable Azure SQL in Athena (workspace admin, once)
An **Athena workspace admin or owner** has to add the app on the Athena side for
the **entire workspace** before anyone can connect. Individual members cannot do
this themselves, and the Azure SQL connect option stays hidden until it's done.
Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**,
expand **Azure SQL**, toggle it on, and fill in:
| Field | Value |
| -------------------- | ----------------------------------------------------------- |
| **Server FQDN** | `myserver.database.windows.net` (the short name also works) |
| **Entra Tenant ID** | Directory (tenant) ID from step 1.6 |
| **Client ID** | Application (client) ID from step 1.6 |
| **Client Secret** | The secret **Value** from step 1.5 |
| **Default Database** | Optional — pre-selected in the connect dialog |
The client secret is encrypted before it is stored and is never returned to the
browser.
## Step 3 — Members connect (each user)
1. Go to **[Integrations](https://app.athenaintel.com/dashboard/integrations/)**
and click **Azure SQL → Connect**.
2. Sign in to Microsoft in the popup and consent to **Azure SQL Database
user\_impersonation**.
3. Pick the default database. Athena creates a private catalog for you that only
you can query.
## Troubleshooting
| Symptom | Cause and fix |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri_mismatch` in the popup | The callback URL isn't registered on the Entra app, or doesn't match exactly. Re-check step 1.3. |
| Connect works, queries fail with "Login failed for user" | No contained database user for that Entra identity. Run `CREATE USER … FROM EXTERNAL PROVIDER` in the target database. |
| Error `40615` on the first query | The SQL server firewall is blocking Athena's egress IP. Add the rule and wait five minutes. |
| First query times out, second succeeds | Serverless database resuming from auto-pause. Expected. |
| No Azure SQL connect option on the Integrations page | A workspace admin hasn't completed step 2. |
Credentials and tokens are encrypted at rest, tokens are per-user and refresh
automatically, and disconnecting a catalog removes your access immediately.