Konfigurace ověřování služby App Service (EasyAuth)

Azure App Service poskytuje integrované ověřování (často označované jako "EasyAuth"), které zpracovává přihlašování uživatelů před žádostí do vaší aplikace. Tvůrce rozhraní DATA API může číst informace o identitě, které služba App Service vloží, a povolit ověřování bez přímé správy tokenů.

Důležité

AppService Zprostředkovatel důvěřuje hlavičkám identit předávaným službou EasyAuth. Ujistěte se, že klienti nemůžou obejít EasyAuth a přímo se dostanou ke tvůrci rozhraní Data API.

Warning

Poskytovatele ověřování AppService používejte pouze při hostování v Azure App Service nebo Azure Functions v App Service. Nastavení tohoto poskytovatele na samostatném hostiteli se systémem Windows nebo v prostředí mimo App Service způsobí selhání spuštění, protože chybí požadovaná infrastruktura EasyAuth. Při místním testování simulujte EasyAuth ručním odesláním hlavičky X-MS-CLIENT-PRINCIPAL. Viz Místní testování pomocí X-MS-CLIENT-PRINCIPAL.

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

Když tvůrce rozhraní Data API běží za službou Azure App Service s povoleným ověřováním, služba App Service zpracovává tok OAuth a předává informace o identitě prostřednictvím hlaviček HTTP:

Obrázek toku ověřování služby App Service znázorňující, jak EasyAuth vloží hlavičky identity

Fáze	Co se stane
Ověřování uživatelů	App Service zachytí neověřené požadavky a přesměruje je na zprostředkovatele identity.
Injektáž identity	Po ověření služba App Service přidá hlavičku `X-MS-CLIENT-PRINCIPAL` .
Zpracování DAB	Tvůrce rozhraní Data API dekóduje JSON hlavičky pomocí Base64 a sestaví `ClaimsPrincipal` z pole `claims`.
Authorization	DAB používá `ClaimsPrincipal.IsInRole()` k ověření hlavičky `X-MS-API-ROLE`, poté vyhodnocuje oprávnění a zásady.

Předpoklady

Předplatné Azure
Azure App Service nebo Azure Functions (v infrastruktuře služby App Service)
Nainstalovaný Data API builder CLI (průvodce instalací)
Existující dab-config.json s alespoň jednou entitou

Stručná referenční dokumentace

Setting	Hodnota
Poskytovatel	`AppService`
Hlavička identity	`X-MS-CLIENT-PRINCIPAL` (JSON s kódováním Base64)
Nadpis výběru role	`X-MS-API-ROLE`
Podporuje vlastní deklarace identity.	Ano
Místní testování	Ano (manuálně nastavená záhlaví)

Krok 1: Povolení ověřování služby App Service

Konfigurace ověřování ve službě Azure App Service:

Na webu Azure Portal přejděte do služby App Service.
Vyberte Ověřování nastavení>.
Vyberte Přidat poskytovatele identity.
Zvolte Microsoft (nebo jiný podporovaný poskytovatel).
Nakonfigurujte nastavení:
- Typ registrace aplikace: Vytvořit nový nebo vybrat existující
- Podporované typy účtů: Volba na základě vašeho scénáře
- Omezení přístupu: Vyžadování ověřování
Vyberte Přidat.

Návod

Ověřování pomocí služby App Service funguje s několika zprostředkovateli identity, mezi které patří Microsoft, Google, Facebook, Twitter a OpenID Connect.

Krok 2: Konfigurace tvůrce rozhraní Data API

Nastavte zprostředkovatele ověřování na AppService:

dab configure \
  --runtime.host.authentication.provider AppService

dab configure ^
  --runtime.host.authentication.provider AppService

Výsledná konfigurace

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

Poznámka:

Na rozdíl od poskytovatelů EntraID/AzureAD nebo CustomAppService nevyžaduje jwt.audience ani jwt.issuer nastavení. App Service před předáním informací o identitě do DAB token ověří.

Krok 3: Konfigurace oprávnění entity

Definujte oprávnění pro role. Tvůrce API vyhodnocuje role prostřednictvím ClaimsPrincipal.IsInRole(), která kontroluje nároky analyzované z hlavičky X-MS-CLIENT-PRINCIPAL. Zahrňte do pole claims deklarace role s odpovídajícím typem deklarace role.

Příklad konfigurace

Bash
Příkazový řádek

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow editors to create and update
dab update Book ^
  --permissions "editor:create,read,update"

Výsledná konfigurace

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Krok 4: Místní testování pomocí X-MS-CLIENT-PRINCIPAL

Ověřování služby App Service můžete otestovat místně tím, že ručně poskytnete hlavičku X-MS-CLIENT-PRINCIPAL . Tento přístup simuluje, co EasyAuth předává vaší aplikaci, a umožňuje otestovat chování řízené rolemi a deklaracemi identity bez nasazení do Azure.

Vytvoření hlavní identity klienta

Hlavička X-MS-CLIENT-PRINCIPAL obsahuje objekt JSON kódovaný kódem Base64. Tvůrce rozhraní Data API parsuje následující vlastnosti:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Kódování hlavního objektu

Kód JSON zakódujte jako Base64. Můžete použít libovolný nástroj:

PowerShell:

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Bash

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Odeslání požadavku s hlavičkou

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

Struktura X-MS-CLIENT-PRINCIPAL

Tvůrce rozhraní Data API analyzuje následující vlastnosti z klientského principálu.

Vlastnictví	Typ	Description
`auth_typ`	řetězec	Typ ověřování (například `aad`). Vyžaduje se, aby byla identita považována za ověřenou.
`name_typ`	řetězec	(Volitelné) Typ deklarace identity použitý pro jméno uživatele
`role_typ`	řetězec	(Volitelné) Typ deklarace identity používaný pro role (výchozí nastavení `roles`)
`claims`	object[]	Pole deklarací s vlastnostmi `typ` a `val` Role musí být zde zahrnuty jako nároky.

Důležité

Role se vyhodnocují prostřednictvím ClaimsPrincipal.IsInRole(), které kontroluje pole claims při hledání požadavků, které odpovídají role_typ. Zahrňte každou roli jako samostatnou položku nároku (například { "typ": "roles", "val": "editor" }).

Použití nároků v zásadách databáze

S poskytovatelem služby AppService můžete v zásadách databáze používat deklarace identity. Tato funkce umožňuje zabezpečení na úrovni řádků na základě identity uživatele.

Příklad: Filtrování podle ID objektu uživatele

Tento příklad používá deklaraci identity (identifikátor objektu oid ), kterou ID Microsoft Entra zahrnuje do tokenů:

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Návod

Mezi běžné typy deklarací identity z id Microsoft Entra patří oid (ID objektu), email, namea preferred_username. Použijte přesný řetězec typu deklarace identity od zprostředkovatele identity.

Dostupné reference požadavků

Odkazy na nároky používají přesný řetězec typu nároku z claims pole.

Referenční číslo nároku	Description
`@claims.<claim-type>`	Jakýkoli nárok z pole `claims`, který odpovídá vlastnosti `typ`

Pokud například váš hlavní objekt zahrnuje { "typ": "email", "val": "alice@contoso.com" }, použijte @claims.email ve své zásadě. Typ nároku se musí přesně shodovat.

Anonymní žádosti

Když App Service povolí neověřené požadavky nebo když testujete místně bez hlavičky X-MS-CLIENT-PRINCIPAL, middleware pro ověřování prostřednictvím tvůrce rozhraní Data API automaticky nastaví hlavičku X-MS-API-ROLE na anonymous. Požadavky se pak vyhodnocují pomocí anonymous role:

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Aby anonymní přístup fungoval, musí mít vaše entita oprávnění pro roli anonymous :

{
  "permissions": [
    {
      "role": "anonymous",
      "actions": ["read"]
    }
  ]
}

Troubleshooting

Symptom	Možná příčina	Řešení
`401 Unauthorized` (nebo přesměrovat na přihlášení)	EasyAuth zablokoval požadavek před dosažením DAB.	Přihlaste se přes EasyAuth nebo odešlete platné přihlašovací údaje; ověření nastavení ověřování služby App Service
`403 Forbidden`	Role není zahrnuta v oprávněních	Přidat roli do oprávnění entity
`403 Forbidden`	`X-MS-API-ROLE` není v rolích uživatele.	Ujistěte se, že hodnota hlavičky odpovídá nároku na roli v poli objektu `claims`.
Nároky nejsou k dispozici.	Chybějící `claims` pole v klientské identitě	Přidání nároků do `X-MS-CLIENT-PRINCIPAL` JSON
Nerozpoznaná role	Role, které nejsou v `claims` poli	Přidejte deklarace rolí se správnými `role_typ` (například `{ "typ": "roles", "val": "editor" }`)
Místní testování selže	Hlavička není zakódovaná ve formátu Base64	Správné kódování JSON před odesláním

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": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Váš názor

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

Last updated on 2026-05-14

Konfigurace ověřování služby App Service (EasyAuth)

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

Předpoklady

Stručná referenční dokumentace

Krok 1: Povolení ověřování služby App Service

Krok 2: Konfigurace tvůrce rozhraní Data API

CLI

Výsledná konfigurace

Krok 3: Konfigurace oprávnění entity

Příklad konfigurace

Výsledná konfigurace

Krok 4: Místní testování pomocí X-MS-CLIENT-PRINCIPAL

Vytvoření hlavní identity klienta

Kódování hlavního objektu

Odeslání požadavku s hlavičkou

Struktura X-MS-CLIENT-PRINCIPAL

Použití nároků v zásadách databáze

Příklad: Filtrování podle ID objektu uživatele

Dostupné reference požadavků

Anonymní žádosti

Troubleshooting

Příklad dokončení konfigurace

Související obsah

Váš názor

Další materiály