App Service-hitelesítés konfigurálása (EasyAuth)

Az Azure App Service beépített hitelesítést (más néven "EasyAuth") biztosít, amely kezeli a felhasználói bejelentkezést, mielőtt a kérések elérnék az alkalmazást. A Data API Builder képes beolvasni az App Service által beszúrt identitásadatokat, így a hitelesítés megvalósítható a jogkivonatok közvetlen kezelése nélkül.

Fontos

A AppService szolgáltató megbízik az EasyAuth által továbbított identitásfejlécekben. Győződjön meg arról, hogy az ügyfelek nem tudják megkerülni az EasyAuth-t, és nem érik el közvetlenül a Data API Buildert.

Warning

A AppService hitelesítésszolgáltatót csak akkor használja, ha Azure App Service vagy Azure Functions üzemeltet az App Service-ben. A szolgáltató önálló Windows-gazdagépen vagy nem App Service-környezetben való beállítása indítási hibákat okoz, mert a szükséges EasyAuth-infrastruktúra hiányzik. A helyi teszteléshez szimulálja az EasyAuth-t a X-MS-CLIENT-PRINCIPAL fejléc manuális elküldésével. Lásd : Helyi tesztelés X-MS-CLIENT-PRINCIPAL használatával.

Hitelesítési folyamat

Ha a Data API Builder az Azure App Service mögött fut, és engedélyezve van a hitelesítés, az App Service kezeli az OAuth-folyamatot, és HTTP-fejléceken keresztül továbbítja az identitásadatokat:

Az App Service hitelesítési folyamatának illusztrációja, amely bemutatja, hogyan injektálja az EasyAuth az identitásfejléc-információkat.

Phase	Mi történik?
Felhasználói hitelesítés	Az App Service elfogja a nem hitelesített kéréseket, és átirányítja az identitásszolgáltatóhoz
Identitásinjektálás	A hitelesítés után az App Service hozzáadja a fejlécet `X-MS-CLIENT-PRINCIPAL`
DAB-feldolgozás	A Data API Builder Base64-dekódolja a JSON fejlécet, és a `ClaimsPrincipal` tömbből létrehoz egy `claims`-t.
Authorization	A DAB a `ClaimsPrincipal.IsInRole()` a fejléc ellenőrzésére használja, majd kiértékeli az engedélyeket és szabályzatokat `X-MS-API-ROLE`

Előfeltételek

Azure-előfizetés
Azure App Service vagy Azure Functions (App Service-infrastruktúrán)
Telepített Data API Builder CLI (telepítési útmutató)
Legalább egy entitással rendelkező meglévő dab-config.json

Rövid összefoglalás

Setting	Érték
Szolgáltató	`AppService`
Identitásfejléc	`X-MS-CLIENT-PRINCIPAL` (Base64 kódolású JSON)
Szerepkör-kijelölés fejléce	`X-MS-API-ROLE`
Egyéni jogcímek támogatása	Igen
Helyi tesztelés	Igen (kézzel beállított fejlécek)

1. lépés: App Service-hitelesítés engedélyezése

Hitelesítés konfigurálása az Azure App Service-ben:

Az Azure Portalon lépjen az App Service-hez.
Válassza a Beállítások hitelesítése lehetőséget>.
Válassza az Identitásszolgáltató hozzáadása lehetőséget.
Válassza a Microsoftot (vagy egy másik támogatott szolgáltatót).
Konfigurálja a beállításokat:
- Alkalmazásregisztráció típusa: Új létrehozása vagy meglévő kiválasztása
- Támogatott fióktípusok: Válasszon a forgatókönyv alapján
- Hozzáférés korlátozása: Hitelesítés megkövetelése
Válassza a Hozzáadás lehetőséget.

Jótanács

Az App Service-hitelesítés több identitásszolgáltatóval is működik, beleértve a Microsoftot, a Google-t, a Facebookot, a Twittert és az OpenID Connectet.

2. lépés: A Data API Builder konfigurálása

A hitelesítési szolgáltató beállítása a következőre AppService:

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

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

Az eredményként kapott konfiguráció

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

Megjegyzés:

A EntraID/AzureAD vagy Custom szolgáltatóktól eltérően a AppService nem igényel jwt.audience vagy jwt.issuer beállításokat. Az App Service ellenőrzi a jogkivonatot, mielőtt identitásadatokat ad át a DAB-nak.

3. lépés: Entitásengedélyek konfigurálása

Szerepkörök engedélyeinek meghatározása. A Data API Builder a szerepköröket a ClaimsPrincipal.IsInRole() segítségével értékeli, amely a X-MS-CLIENT-PRINCIPAL fejlécből elemzett jogcímeket ellenőrzi. Vegye fel a szerepkörjogcímeket a claims tömbbe a megfelelő szerepkör jogcímtípussal.

Konfigurációs példa

Bash
Parancssor

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

Az eredményként kapott konfiguráció

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

4. lépés: Helyi tesztelés X-MS-CLIENT-PRINCIPAL

A X-MS-CLIENT-PRINCIPAL fejléc manuális megadásával helyileg tesztelheti az App Service-hitelesítést. Ez a megközelítés szimulálja, hogy az EasyAuth mit továbbít az alkalmazásnak, és lehetővé teszi a szerepkör és a jogcímalapú viselkedés tesztelését anélkül, hogy üzembe helyezned az Azure-ban.

Ügyfélazonosító létrehozása

A X-MS-CLIENT-PRINCIPAL fejléc egy Base64 kódolású JSON-objektumot tartalmaz. A Data API Builder a következő tulajdonságokat elemzi:

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

A főelem kódolása

Kódold a JSON-t Base64 formátumban. Bármilyen eszközt használhat:

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))

Ütés

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

Küldjön kérelmet egy fejléc megadásával

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

X-MS-CLIENT-PRINCIPAL struktúra

A Data API Builder a kliensvezérlő következő tulajdonságait elemzi:

Ingatlan	Típus	Leírás
`auth_typ`	karakterlánc	A hitelesítési típus (például `aad`). Az identitás hitelesítéséhez szükséges.
`name_typ`	karakterlánc	(Nem kötelező) A felhasználó nevének jogcímtípusa
`role_typ`	karakterlánc	(Nem kötelező) A szerepkörökhöz használt jogcímtípus (alapértelmezés szerint `roles`)
`claims`	objektum[]	Állítások halmaza `typ` és `val` tulajdonságokkal. A szerepköröket itt jogcímként kell szerepeltetni.

Fontos

A szerepkörök kiértékelése a ClaimsPrincipal.IsInRole() segítségével történik, amely ellenőrzi, hogy a claims tömb tartalmaz-e a role_typ-nek megfelelő jogcímeket. Vegyen fel minden szerepkört külön jogcímbejegyzésként (például { "typ": "roles", "val": "editor" }).

Jogcímek használata adatbázis-szabályzatokban

Az AppService-szolgáltatóval jogcímeket használhat adatbázis-szabályzatokban. Ez a képesség a felhasználói identitáson alapuló sorszintű biztonságot teszi lehetővé.

Példa: Szűrés felhasználói objektumazonosító alapján

Ez a példa a oid (objektumazonosító) igényeket használja, amelyeket a Microsoft Entra ID tartalmaz a tokenekben.

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

Jótanács

A Microsoft Entra-azonosító gyakori jogcímtípusai közé tartozik az oid (objektumazonosító), email, name, és preferred_username. Használja az identitásszolgáltató pontos jogcímtípus-sztringét.

Rendelkezésre álló jogcímhivatkozások

A jogcímhivatkozások a tömbből származó pontos jogcímtípus-sztringet claims használják:

Jogcímhivatkozás	Leírás
`@claims.<claim-type>`	Az `claims` tömb minden olyan jogcíme, amely megfelel a `typ` tulajdonságnak

Ha például az alapértelmezett elem tartalmazza { "typ": "email", "val": "alice@contoso.com" }, használja @claims.email a szabályzatban. A jogcímtípusnak pontosan meg kell egyeznie.

Névtelen kérések

Ha az App Service engedélyezi a hitelesítés nélküli kéréseket, vagy amikor fejléc nélküli helyi tesztelés zajlik, a Data API Builder hitelesítési köztesrétege automatikusan beállítja a X-MS-CLIENT-PRINCIPAL fejlécet X-MS-API-ROLE. Ezután a rendszer a következő szerepkörrel értékeli ki a anonymous kérelmeket:

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

A névtelen hozzáférés működéséhez az entitásnak engedélyekkel kell rendelkeznie a anonymous szerepkörhöz:

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

Hibaelhárítás

tüneti	Lehetséges ok	Megoldás
`401 Unauthorized` (vagy átirányítás bejelentkezésre)	Az EasyAuth letiltotta a kérést, mielőtt elérte volna a DAB-t	Jelentkezzen be az EasyAuth-on keresztül, vagy küldjön érvényes hitelesítő adatokat; Az App Service hitelesítési beállításainak ellenőrzése
`403 Forbidden`	A szerepkör nem szerepel az engedélyek között	Engedélyek hozzáadása az entitás szerepköreihez
`403 Forbidden`	`X-MS-API-ROLE` nincs a felhasználó szerepei között	Győződjön meg arról, hogy a fejléc értéke megegyezik egy szerepköveteléssel a fő objektum `claims` tömbjében.
Az igények nem érhetők el	Hiányzó `claims` tömb az ügyfél alapelvben	Jogcímek hozzáadása a `X-MS-CLIENT-PRINCIPAL` JSON-hoz
A szerepkör nem ismerhető fel	A `claims` tömbben nem szereplő szerepkörök	A szerepekhez tartozó jogcímek helyes hozzáadása `role_typ` (például `{ "typ": "roles", "val": "editor" }`)
A helyi tesztelés sikertelen	Nem Base64 kódolású fejléc	A JSON megfelelő kódolása küldés előtt

Teljes konfigurációs példa

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

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-20

App Service-hitelesítés konfigurálása (EasyAuth)

Hitelesítési folyamat

Előfeltételek

Rövid összefoglalás

1. lépés: App Service-hitelesítés engedélyezése

2. lépés: A Data API Builder konfigurálása

parancssori felület

Az eredményként kapott konfiguráció

3. lépés: Entitásengedélyek konfigurálása

Konfigurációs példa

Az eredményként kapott konfiguráció

4. lépés: Helyi tesztelés X-MS-CLIENT-PRINCIPAL

Ügyfélazonosító létrehozása

A főelem kódolása

Küldjön kérelmet egy fejléc megadásával

X-MS-CLIENT-PRINCIPAL struktúra

Jogcímek használata adatbázis-szabályzatokban

Példa: Szűrés felhasználói objektumazonosító alapján

Rendelkezésre álló jogcímhivatkozások

Névtelen kérések

Hibaelhárítás

Teljes konfigurációs példa

Kapcsolódó tartalom

Visszajelzés

További források