Configure Microsoft Entra ID authentication

This guide walks you through configuring Microsoft Entra ID (formerly Azure Active Directory) authentication for Data API builder. By the end, your client app authenticates users through Entra, acquires tokens for Data API builder, and DAB can use managed identity to connect to Azure SQL.

Data API builder authenticates incoming requests using either JSON Web Token (JWT) bearer validation (EntraID/AzureAD/Custom) or platform-provided identity headers (AppService). For local development and permission testing, use the Simulator provider.

Authentication provider guides

Choose a guide based on your identity provider:

Authentication flow

The flow has three distinct phases:

Prerequisites

• An Azure subscription with Microsoft Entra ID tenant
• Data API builder CLI installed (installation guide)
• An existing dab-config.json with at least one entity
• (Optional) Azure SQL Database for managed identity scenarios

Quick reference

Step 1: Register an application in Microsoft Entra ID

Create an app registration that represents your Data API builder API. Client apps request tokens with an audience that matches this registration.

1. Sign in to the Microsoft Entra admin center.

2. Navigate to Identity > Applications > App registrations.

3. Select New registration.

4. Enter a Name (for example, Data API Builder API).

5. Select the appropriate Supported account types for your scenario:

   • Single tenant: Only users in your organization
   • Multitenant: Users in any Microsoft Entra directory

6. Leave Redirect URI blank (this registration is for the API, not the client).

7. Select Register.

8. On the app's Overview page, record these values:

   Value	Where to find it	Used for
   Application (client) ID	Overview page	Building the audience URI
   Directory (tenant) ID	Overview page	Building the issuer URL

Configure the Application ID URI

1. In the app registration, go to Expose an API.

2. Select Add next to Application ID URI.

3. Accept the default (api://<app-id>) or enter a custom URI.

4. Select Save.

Add a scope

A scope is required so that client applications (including Azure CLI) can request delegated access tokens for your API.

1. In the app registration, go to Expose an API.

2. Under Scopes defined by this API, select Add a scope.

3. Enter:

   • Scope name: Endpoint.Access
   • Who can consent?: Admins and users
   • Admin consent display name: Execute requests against Data API builder
   • Admin consent description: Allows client app to send requests to Data API builder endpoint.
   • User consent display name: Execute requests against Data API builder
   • User consent description: Allows client app to send requests to Data API builder endpoint.
   • State: Enabled

4. Select Add scope.

Add app roles (optional)

If you want to use custom roles beyond Anonymous and Authenticated:

1. Go to App roles.

2. Select Create app role.

3. Enter:

   • Display name: Reader
   • Allowed member types: Users/Groups or Both
   • Value: reader (this value appears in the token's roles claim)
   • Description: Read-only access to data

4. Select Apply.

5. Repeat for more roles (for example, writer, admin).

Set the manifest token version

By default, the app registration manifest sets accessTokenAcceptedVersion to null, which produces v1.0 tokens. V1 tokens use a different issuer format (https://sts.windows.net/<tenant-id>/) than the v2.0 issuer configured in DAB, which causes token validation to fail.

1. In the app registration, go to Manifest.

2. Find accessTokenAcceptedVersion and change the value to 2.

3. Select Save.

Assign users to app roles

Creating app roles doesn't automatically grant them to users. You must assign users or groups through the Enterprise Application.

1. In the Microsoft Entra admin center, navigate to Identity > Applications > Enterprise applications.

2. Search for and select your app (for example, Data API Builder API). An enterprise application was created automatically when you registered the app.

3. Go to Users and groups.

4. Select Add user/group.

5. Under Users, select the user account to assign and select Select.

6. Under Select a role, choose the role to assign (for example, Reader). If your role doesn't appear, wait a few minutes for Microsoft Entra replication to complete.

7. Select Assign.

8. Repeat for each role you want to assign.

Step 2: Configure Data API builder

Configure DAB to validate tokens issued by your Entra tenant for your API audience.

CLI

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider EntraID

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider EntraID

REM Set the expected audience (Application ID URI)
dab configure ^
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

REM Set the expected issuer (your tenant)
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Resulting configuration

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

Step 3: Configure entity permissions

Define which roles can access each entity. Requests are evaluated against the role determined from the token.

Grant access to authenticated users

dab update Book \
  --permissions "Authenticated:read"

dab update Book ^
  --permissions "Authenticated:read"

Grant access to a custom role

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

dab update Book ^
  --permissions "reader:read" ^
  --permissions "writer:create,read,update"

Resulting configuration

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Step 4: Configure database connection

Data API builder connects to the database using its own identity, separate from the authenticated user. For production scenarios with Azure SQL, use managed identity.

Option A: Managed identity (recommended for Azure)

System-assigned managed identity

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

User-assigned managed identity

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Option B: SQL authentication (development)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Option C: Local development with az login

For local development against Azure SQL, use your Azure CLI credentials:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Before starting DAB, sign in:

az login

Step 5: Test the configuration

Authorize Azure CLI as a client application

Before Azure CLI can acquire tokens for your API, you must add it as an authorized client application.

1. In the app registration, go to Expose an API.

2. Under Authorized client applications, select Add a client application.

3. Enter the Azure CLI client ID: 00001111-aaaa-2222-bbbb-3333cccc4444.

4. Select the api://<app-id>/Endpoint.Access scope.

5. Select Add application.

Acquire a token with Azure CLI

Sign in to Azure CLI and set the tenant where your app registration exists:

az login
az account set --tenant <your-tenant-id>

Request a token scoped to your API:

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

You can inspect the token at jwt.ms to verify the aud, iss, and roles claims.

Start DAB and send a request

1. Start Data API builder:

   dab start
   

2. Call the API with the token:

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>"
   

3. To use a custom role, include the X-MS-API-ROLE header:

   curl -X GET "http://localhost:5000/api/Book" \
     -H "Authorization: Bearer <your-token>" \
     -H "X-MS-API-ROLE: reader"
   

Role selection behavior

Data API builder determines the request's role using this logic:

Troubleshooting

Complete configuration example

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Related content

• Authorization and roles
• Configure Simulator authentication for testing
• Configure App Service authentication
• Runtime configuration reference