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

# Azure Entra ID Authentication

> How Entegrata authenticates to Azure-hosted SQL data sources using Entra ID, and how to grant it access

## Overview

Azure Entra ID authentication lets Entegrata connect to Azure-hosted SQL data sources without a SQL Server login. Instead of storing a username and password, access is granted to an **Azure AD identity** — either a managed identity that Entegrata already owns, or a service principal (app registration) that you control.

Entegrata supports two Entra-based methods:

* **Service Principal** — an Azure AD app registration authenticates using a client secret or certificate that you enter on the connection. Available to all customers.
* **Managed Identity** — a managed identity that Entegrata already owns in Azure authenticates on your behalf. Nothing is stored on the connection. Only available for self-hosted instances.

<Note>
  Entra authentication only works against SQL Servers integrated with Azure AD: **Azure SQL Database**, **Azure SQL Managed Instance**, **Microsoft Fabric** SQL / Warehouse / Lakehouse endpoints, and **SQL Server running on Azure VM or Arc** with Entra authentication enabled.

  Traditional on-premise SQL Server without Entra integration can't use these methods — use SQL Authentication instead.
</Note>

## Before You Start

An **Azure AD admin** on the target SQL Server is required to run the `CREATE USER ... FROM EXTERNAL PROVIDER` step below. If you're not that admin, hand this page to whoever is.

<Tip>
  For Azure SQL Database and Managed Instance, an Azure AD admin is assigned at the server level in the Azure portal (**Settings → Microsoft Entra ID**). That admin can then create users for other identities in each database.
</Tip>

## Service Principal

Service Principal is the default Entra auth method and is available to all customers. Use it when you need each connection to carry its own identity for auditing, when the target tenant differs from the one hosting Entegrata, or whenever Managed Identity isn't an option.

### How It Works

A service principal is an Azure AD app registration with its own credentials (a client secret or certificate). Entegrata uses those credentials to request a token scoped to SQL and presents it to the target server.

### Setup

<Steps>
  <Step title="Create an Azure AD app registration">
    In the Azure portal: **Microsoft Entra ID → App registrations → New registration**. Give it a descriptive name (e.g. `Entegrata Collector`).

    After creation, capture the **Application (client) ID** and **Directory (tenant) ID** from the app's Overview page.
  </Step>

  <Step title="Generate a client secret or certificate">
    Under **Certificates & secrets**, either:

    * Click **New client secret**, pick an expiration, and copy the **secret value** immediately (it's only shown once), **or**
    * Upload a PEM-encoded client certificate.
  </Step>

  <Step title="Create a SQL user for the app registration">
    Connect to the target database as an Azure AD admin and run:

    ```sql theme={null}
    CREATE USER [<app-registration-display-name>] FROM EXTERNAL PROVIDER;
    ```

    Use the exact display name of the app registration.
  </Step>

  <Step title="Grant the roles Entegrata needs">
    For a **collector** connection:

    ```sql theme={null}
    ALTER ROLE db_datareader ADD MEMBER [<app-registration-display-name>];
    GRANT VIEW DATABASE STATE TO [<app-registration-display-name>];
    ```

    For an **emitter** connection (Entegrata writes tables into the target schema):

    ```sql theme={null}
    ALTER ROLE db_datawriter ADD MEMBER [<app-registration-display-name>];
    ALTER ROLE db_ddladmin ADD MEMBER [<app-registration-display-name>];
    GRANT VIEW DATABASE STATE TO [<app-registration-display-name>];
    ```
  </Step>

  <Step title="Enter credentials on the connection form">
    When creating the connection in Entegrata, pick **Entra Service Principal** and supply:

    * **Tenant ID** (directory ID)
    * **Client ID** (application ID)
    * **Client Secret** *or* **Client Certificate** (PEM) — one or the other, not both

    Set the **Secret Expiration** field so Entegrata alerts you before the secret or certificate runs out.
  </Step>
</Steps>

<Warning>
  Service principal client secrets and certificates expire and must be rotated. Always set the **Secret Expiration** field on the connection.
</Warning>

## Managed Identity

<Note>
  Managed Identity authentication is only available for self-hosted instances. Entegrata-hosted instances must use the [Service Principal](#service-principal) option.
</Note>

For self-hosted instances, prefer Managed Identity when possible. There are no credentials to rotate, store, or leak — authentication is handled by Azure itself.

### How It Works

Entegrata runs in Azure with a pre-provisioned managed identity. When a connection uses Managed Identity auth, Entegrata requests a token for that identity from Azure at query time and presents it to SQL Server.

### Setup

<Steps>
  <Step title="Get the managed identity's display name">
    Ask your Entegrata Customer Experience Manager for the display name of the managed identity Entegrata uses in Azure for your instance.
  </Step>

  <Step title="Create a SQL user for the identity">
    Connect to the target database as an Azure AD admin and run:

    ```sql theme={null}
    CREATE USER [<managed-identity-display-name>] FROM EXTERNAL PROVIDER;
    ```
  </Step>

  <Step title="Grant the roles Entegrata needs">
    Same grants as the Service Principal flow above — `db_datareader` for collectors; `db_datawriter` + `db_ddladmin` for emitters; `VIEW DATABASE STATE` for throttling. Use the managed identity's display name in place of the app registration's.
  </Step>

  <Step title="Select Entra ID on the connection form">
    When creating the connection in Entegrata, pick **Entra ID** as the authentication type. No credentials are required.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Login failed for user '<token-identified principal>'">
    The Entegrata identity authenticated with Azure AD, but the target database has no SQL user mapped to it. Run the `CREATE USER ... FROM EXTERNAL PROVIDER` step for that identity on the target database.
  </Accordion>

  <Accordion title="The server does not support Azure Active Directory authentication">
    The target SQL Server isn't configured for Entra authentication. For Azure SQL and Managed Instance, make sure an Azure AD admin has been assigned at the server level. For on-premise SQL Server, confirm it's on Azure VM / Arc with Entra authentication explicitly enabled.
  </Accordion>

  <Accordion title="AADSTS7000215 or AADSTS700016 (service principal cannot sign in)">
    The client secret has expired, the certificate has been revoked, or the app registration was deleted. Create a fresh secret or certificate and update the connection.
  </Accordion>

  <Accordion title="Permission denied on dynamic management views">
    The identity doesn't have `VIEW DATABASE STATE`. Entegrata can still collect without it, but automatic throttling is disabled — grant `VIEW DATABASE STATE` to the identity to fix.
  </Accordion>
</AccordionGroup>