App Service-verificatie configureren (EasyAuth)

Azure App Service biedt ingebouwde verificatie (ook wel EasyAuth genoemd) die aanmelding van gebruikers afhandelt voordat aanvragen uw toepassing bereiken. Data API Builder kan de identiteitsgegevens lezen die App Service injecteert, waardoor verificatie wordt ingeschakeld zonder tokens rechtstreeks te beheren.

Authenticatiestroom

Wanneer Data API Builder wordt uitgevoerd achter Azure App Service waarvoor verificatie is ingeschakeld, verwerkt App Service de OAuth-stroom en geeft deze identiteitsgegevens door via HTTP-headers:

Vereiste voorwaarden

• Een Azure-abonnement
• Azure App Service of Azure Functions (op de infrastructuur van App Service)
• Data API Builder CLI geïnstalleerd (installatiehandleiding)
• Een bestaande dab-config.json met ten minste één entiteit

Snelzoekgids

Stap 1: App Service-verificatie inschakelen

Verificatie configureren in Azure App Service:

1. Navigeer in Azure Portal naar uw App Service.

2. Selecteer Instellingen>Authenticatie.

3. Selecteer Id-provider toevoegen.

4. Kies Microsoft (of een andere ondersteunde provider).

5. Configureer de instellingen:

   • Type app-registratie: nieuwe maken of bestaande selecteren
   • Ondersteunde accounttypen: Kiezen op basis van uw scenario
   • Toegang beperken: Verificatie vereisen

6. Selecteer Toevoegen.

Stap 2: Data API Builder configureren

Stel de verificatieprovider in op AppService:

CLI (Command Line Interface)

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

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

Resulterende configuratie

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

Stap 3: Entiteitsmachtigingen configureren

Machtigingen voor rollen definiëren. Data API Builder evalueert rollen via ClaimsPrincipal.IsInRole(), waarmee claims worden gecontroleerd die zijn geparseerd uit de X-MS-CLIENT-PRINCIPAL header. Voeg rolclaims toe aan de claims matrix met het juiste rolclaimtype.

Voorbeeldconfiguratie

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

Resulterende configuratie

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

Stap 4: Lokaal testen met X-MS-CLIENT-PRINCIPAL

U kunt App Service-verificatie lokaal testen door de X-MS-CLIENT-PRINCIPAL header handmatig op te geven. Met deze aanpak wordt gesimuleerd wat EasyAuth doorstuurt naar uw app en kunt u rollen en claimgestuurd gedrag testen zonder te implementeren in Azure.

Een client-principal maken

De X-MS-CLIENT-PRINCIPAL header bevat een met Base64 gecodeerd JSON-object. Data API Builder parseert de volgende eigenschappen:

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

Codeer de hoofdsom

Codeer de JSON als Base64. U kunt elk hulpprogramma gebruiken:

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

Een aanvraag verzenden met de header

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

X-MS-CLIENT-PRINCIPAL structuur

Data API Builder parseert de volgende eigenschappen van de client-principal:

Claims gebruiken in het databasebeleid

Met de AppService-provider kunt u claims gebruiken in databasebeleid. Dit maakt beveiliging op rijniveau mogelijk op basis van gebruikersidentiteit.

Voorbeeld: Filteren op gebruikersobject-id

In dit voorbeeld wordt de oid-claim (object-ID) gebruikt, die Microsoft Entra-ID opneemt in tokens.

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

Beschikbare claimverwijzingen

Claimverwijzingen gebruiken de exacte claimtypetekenreeks uit de claims matrix:

Als uw principal bijvoorbeeld { "typ": "email", "val": "alice@contoso.com" } bevat, gebruikt u @claims.email in uw beleid. Het claimtype moet exact overeenkomen.

Anonieme aanvragen

Wanneer App Service niet-geverifieerde aanvragen toestaat of wanneer deze lokaal worden getest zonder de X-MS-CLIENT-PRINCIPAL header, stelt de verificatie-middleware van Data API Builder de X-MS-API-ROLE header anonymous automatisch in. Aanvragen worden vervolgens geëvalueerd met behulp van de anonymous rol:

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

Dit werkt alleen als uw entiteit machtigingen heeft voor de anonymous rol:

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

Probleemoplossingsproces

Volledig configuratievoorbeeld

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

Verwante inhoud

• Autorisatie en rollen
• Beveiliging op rijniveau met sessiecontext
• Microsoft Entra ID-verificatie configureren
• Simulatorverificatie configureren voor testen