Nakonfigurujte ověřování Microsoft Entra ID

Tato příručka vás provede konfigurací ověřování Microsoft Entra ID (dříve Azure Active Directory) pro tvůrce rozhraní Data API. Nakonec vaše klientská aplikace ověřuje uživatele prostřednictvím Entra, získává tokeny pro tvůrce rozhraní Data API a DAB může používat spravovanou identitu pro připojení k Azure SQL.

Tvůrce rozhraní Data API ověřuje příchozí požadavky pomocí ověřování pomocí JSON Web Token (EntraID/AzureAD/CustomJWT) nebo hlaviček identit poskytovaných platformou (AppService). Pro místní vývoj a testování oprávnění použijte Simulator poskytovatele.

Obrázek toho, jak se klienti ověřují v Tvůrci rozhraní Data API pomocí tokenů JWT

Průvodci pro poskytovatele ověřování

Vyberte příručku na základě vašeho poskytovatele identity.

Poskytovatel	Guide
Microsoft Entra ID	Tento článek
Okta, Auth0 nebo jiné	Konfigurace vlastního ověřování JWT
Azure App Service	Konfigurace ověřování ve službě App Service
Místní testování	Konfigurace ověřování simulátoru

Průběh ověřování

Tok má tři různé fáze:

Fáze	Description
Ověřování uživatelů	Uživatel se přihlásí přes vaši klientskou aplikaci prostřednictvím Microsoft Entra ID
Ověřování klientů	Klientská aplikace získá token s oborem DAB a volá Data API builder.
Přístup k databázi	Tvůrce rozhraní Data API token ověří a pak se k databázi připojí pomocí vlastní identity (spravované identity nebo přihlašovacích údajů připojovacího řetězce).

Důležité

Tvůrce rozhraní DATA API ověří příchozí token uživatele pro ověřování rozhraní API, ale připojí se k databázi pomocí vlastních přihlašovacích údajů (spravovaná identita nebo ověřování SQL). DAB neprovádí výměnu tokenů on-Behalf-Of (OBO) pro přístup k databázi jako volající uživatel ve výchozím nastavení. Chcete-li povolit OBO, aby se databáze ověřovala jménem skutečného volajícího, přečtěte si téma Konfigurace ověřování OBO.

Předpoklady

Předplatné Azure s tenantem Microsoft Entra ID
Nainstalovaný Data API builder CLI (průvodce instalací)
Existující dab-config.json s alespoň jednou entitou
(Volitelné) Azure SQL Database pro scénáře spravovaných identit

Stručná referenční dokumentace

Setting	Hodnota
Poskytovatel	`EntraID` (nebo `AzureAD` kvůli kompatibilitě)
Požadováno pro ověření	`aud`, `iss`, `exp`platný podpis
Požadováno pro autorizaci	`roles` deklarace identity (pouze pokud používáte vlastní role)
Formát vystavitele	`https://login.microsoftonline.com/<tenant-id>/v2.0`
Formát cílové skupiny	`api://<app-id>` nebo vlastní URI identifikátor aplikace
Výchozí role	`Authenticated`
Hlavička vlastní role	`X-MS-API-ROLE`
Typ deklarace role	`roles` (opraveno, ne konfigurovatelné)

Poznámka:

Pokud jako zprostředkovatele použijete EntraID nebo AzureAD, DAB umožní dodatečné ověření vystavitele podpisových klíčů specifické pro Microsoft Entra tokeny. Toto ověření poskytuje silnější zabezpečení v porovnání s obecným Custom poskytovatelem.

Krok 1: Registrace aplikace v Microsoft Entra ID

Vytvořte registraci aplikace, která představuje vaše rozhraní API Data API builder. Klientské aplikace požadují tokeny s cílovou skupinou, která odpovídá této registraci.

Přihlaste se do Centra pro správu Microsoft Entra.
Přejděte na Identita>Aplikace>Registrace aplikací.
Vyberte Nová registrace.
Zadejte název (například Data API Builder API).
Vyberte vhodné typy podporovaných účtů pro váš scénář:
- Jeden tenant: Pouze uživatelé ve vaší organizaci
- Multitenant: Uživatelé v libovolném adresáři Microsoft Entra
Nechejte identifikátor URI přesměrování prázdný (tato registrace je určená pro rozhraní API, ne pro klienta).
Vyberte Zaregistrovat.

Na stránce Přehled aplikace si poznamenejte tyto hodnoty:

Hodnota	Kde to najít	Používá se pro
ID aplikace (klienta)	Přehledová stránka	Vytvoření identifikátoru URI cílové skupiny
ID adresáře (tenanta)	Přehledová stránka	Sestavení adresy URL vystavitele

Konfigurace URI identifikátoru aplikace

V registraci aplikace přejděte na Zveřejnit rozhraní API.
Vyberte Přidat vedle identifikátoru URI ID aplikace.
Přijměte výchozí (api://<app-id>) nebo zadejte vlastní identifikátor URI.
Vyberte Uložit.

Návod

Identifikátor URI ID aplikace se stane audience hodnotou v konfiguraci DAB. Používejte konzistentní formát napříč prostředími.

Přidat obor

Je vyžadován obor, aby klientské aplikace (včetně Azure CLI) mohly požadovat delegované přístupové tokeny pro váš API.

V registraci aplikace přejděte na Zveřejnit rozhraní API.
V části Obory definované tímto rozhraním API vyberte Přidat obor.
Vstoupit:
- Názvu oboru: Endpoint.Access
- Kdo může souhlasit?: Správci a uživatelé
- Zobrazovaný název souhlasu správce: Execute requests against Data API builder
- Popis souhlasu správce: Allows client app to send requests to Data API builder endpoint.
- Zobrazované jméno souhlasu uživatele: Execute requests against Data API builder
- Popis souhlasu uživatele: Allows client app to send requests to Data API builder endpoint.
- Stav: Povoleno
Vyberte Přidat rozsah.

Poznámka:

Úplná hodnota rozsahu je api://<app-id>/Endpoint.Access. Klientské aplikace používají tuto hodnotu při vyžádání tokenů.

Přidání rolí aplikace (volitelné)

Pokud chcete používat vlastní role nad rámec Anonymous a Authenticated:

Přejděte do rolí aplikace.
Vyberte Vytvořit roli aplikace.
Vstoupit:
- Zobrazovaný název: Reader
- Povolené typy členů: Uživatelé/skupiny nebo obojí
- Hodnota: reader (tato hodnota se zobrazí v deklaraci identity tokenu roles )
- Popis: Read-only access to data
Vyberte a použijte.
Opakujte pro více rolí (například writer, admin).

Nastavení verze tokenu manifestu

Ve výchozím nastavení manifest registrace aplikace nastaví accessTokenAcceptedVersion na null, což vytváří tokeny v1.0. Tokeny V1 používají jiný formát vystavitele (https://sts.windows.net/<tenant-id>/) než vystavitel ve formátu v2.0 nakonfigurovaný v DAB, což způsobuje selhání ověření tokenu.

V registraci aplikace přejděte do manifestu.
Najděte accessTokenAcceptedVersion a změňte hodnotu na 2.
Vyberte Uložit.

Důležité

Pokud accessTokenAcceptedVersion je null nebo 1, deklarace identity iss v tokenu neodpovídá adrese URL vystavitele v2.0 nakonfigurované v DAB a všechny požadavky selžou s 401 Unauthorized.

Přiřazení uživatelů k rolím aplikací

Vytváření rolí aplikací nejsou automaticky uděleny uživatelům. Uživatele nebo skupiny musíte přiřadit prostřednictvím podnikové aplikace.

V centru pro správu Microsoft Entra přejděte na Identity>Applications>Enterprise applications.
Vyhledejte a vyberte aplikaci (například Data API Builder API). Podniková aplikace se vytvořila automaticky při registraci aplikace.
Přejděte na Uživatelé a skupiny.
Vyberte Přidat uživatele nebo skupinu.
V části Uživatelé vyberte uživatelský účet, který chcete přiřadit, a vyberte Vybrat.
V části Vybrat roli zvolte roli, která se má přiřadit (například Reader). Pokud se vaše role nezobrazí, počkejte několik minut, než se Microsoft Entra replikace dokončí.
Vyberte Přiřadit.
Opakujte pro každou roli, kterou chcete přiřadit.

Poznámka:

Bez přiřazení role roles je deklarace identity v tokenu uživatele prázdná a žádosti, které používají X-MS-API-ROLE s vlastní rolí, se zamítnou.403 Forbidden

Krok 2: Konfigurace tvůrce rozhraní Data API

Nakonfigurujte DAB tak, aby ověřil tokeny vydané vaším tenantem Entra pro vaše API.

# 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"

Výsledná konfigurace

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

Krok 3: Konfigurace oprávnění entity

Definujte, které role mají přístup ke každé entitě. Požadavky se vyhodnocují na základě role určené z tokenu.

Udělení přístupu ověřeným uživatelům

Bash
Příkazový řádek

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

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

Udělení přístupu k uživatelsky definované roli

Bash
Příkazový řádek

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

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

Výsledná konfigurace

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

Krok 4: Konfigurace připojení k databázi

Tvůrce rozhraní DATA API se připojí k databázi pomocí vlastní identity, která je oddělená od ověřeného uživatele. V produkčních scénářích s Azure SQL použijte spravovanou identitu.

Poznámka:

Připojení k databázi používá identitu služby DAB (spravovanou identitu nebo přihlašovací údaje SQL), nikoli identitu volajícího uživatele. DAB nepředává tokeny uživatele do databáze.

Možnost A: Spravovaná identita (doporučeno pro Azure)

Spravovaná identita přiřazená systémem

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

Spravovaná identita přiřazená uživatelem

{
  "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;"
  }
}

Možnost B: Ověřování SQL (vývoj)

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

Důležité

Nikdy nepokládejte připojovací řetězce s hesly do správy zdrojového kódu. Použijte proměnné prostředí nebo Azure Key Vault.

Možnost C: Místní vývoj s využitím `az login`

Pro místní vývoj pro Azure SQL použijte přihlašovací údaje Azure CLI:

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

Před zahájením DAB se přihlaste:

az login

Krok 5: Otestování konfigurace

Autorizace Azure CLI jako klientské aplikace

Než může Azure CLI získat tokeny pro vaše rozhraní API, musíte ho přidat jako autorizovanou klientskou aplikaci.

V registraci aplikace přejděte na Zveřejnit rozhraní API.
V části Autorizované klientské aplikace vyberte Přidat klientskou aplikaci.
Zadejte ID klienta Azure CLI: 00001111-aaaa-2222-bbbb-3333cccc4444.
Vyberte api://<app-id>/Endpoint.Access rozsah.
Vyberte Přidat aplikaci.

Získání tokenu pomocí Azure CLI

Přihlaste se do Azure CLI a nastavte tenanta, kde je registrace vaší aplikace.

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

Vyžádejte si token s vymezeným oborem vašeho rozhraní API:

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

Poznámka:

Pokud se vám zobrazila chyba souhlasu AADSTS65001, ověřte, zda jste v předchozím kroku přidali ID klienta Azure CLI (00001111-aaaa-2222-bbbb-3333cccc4444) jako autorizovanou klientsku aplikaci.

Token můžete zkontrolovat na jwt.ms a ověřit aud, iss, a roles tvrzení.

Spuštění DAB a odeslání požadavku

Spusťte Tvůrce rozhraní API pro data:
```
dab start
```

Volání rozhraní API pomocí tokenu:

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

Pokud chcete použít vlastní roli, zahrňte hlavičku X-MS-API-ROLE :

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

Poznámka:

Role zadaná v X-MS-API-ROLE deklaraci identity tokenu roles musí existovat. Pokud se role nenachází v tokenu, žádost bude odmítnuta.

Chování výběru role

Tvůrce rozhraní Data API určuje roli požadavku pomocí této logiky:

Token je k dispozici?	Hlavička X-MS-API-ROLE?	Jaká je role v tokenu?	Výsledek
Ne	Ne	—	`Anonymous`
Ano (platné)	Ne	—	`Authenticated`
Ano (platné)	Ano	Ne	Odmítnuto (403 Zakázáno)
Ano (platné)	Ano	Ano	Hodnota záhlaví
Ano (neplatné)	—	—	Odmítnuto (401 Neautorizováno)

Troubleshooting

Symptom	Možná příčina	Řešení
`401 Unauthorized`	Platnost tokenu vypršela nebo je token chybný	Získejte nový token; zkontrolujte token na jwt.ms
`401 Unauthorized`	Neshoda cílové skupiny	Ověřte, zda `jwt.audience` odpovídá nároku tokenu `aud`
`401 Unauthorized`	Neshoda vydavatelů	Ověřte `jwt.issuer` , že přesně odpovídá deklaraci identity tokenu `iss` .
`403 Forbidden`	Role není v tokenu	Ujistěte se, že je uživatel přiřazený k roli aplikace v Entra.
`403 Forbidden`	Žádná oprávnění pro roli	Přidejte roli do pole entity `permissions`

Příklad dokončení konfigurace

{
  "$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"]
        }
      ]
    }
  }
}

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-01

Nakonfigurujte ověřování Microsoft Entra ID

Průvodci pro poskytovatele ověřování

Průběh ověřování

Předpoklady

Stručná referenční dokumentace

Krok 1: Registrace aplikace v Microsoft Entra ID

Konfigurace URI identifikátoru aplikace

Přidat obor

Přidání rolí aplikace (volitelné)

Nastavení verze tokenu manifestu

Přiřazení uživatelů k rolím aplikací

Krok 2: Konfigurace tvůrce rozhraní Data API

CLI

Výsledná konfigurace

Krok 3: Konfigurace oprávnění entity

Udělení přístupu ověřeným uživatelům

Udělení přístupu k uživatelsky definované roli

Výsledná konfigurace

Krok 4: Konfigurace připojení k databázi

Možnost A: Spravovaná identita (doporučeno pro Azure)

Spravovaná identita přiřazená systémem

Spravovaná identita přiřazená uživatelem

Možnost B: Ověřování SQL (vývoj)

Možnost C: Místní vývoj s využitím az login

Krok 5: Otestování konfigurace

Autorizace Azure CLI jako klientské aplikace

Získání tokenu pomocí Azure CLI

Spuštění DAB a odeslání požadavku

Chování výběru role

Troubleshooting

Příklad dokončení konfigurace

Související obsah

Váš názor

Další materiály

Možnost C: Místní vývoj s využitím `az login`