Condividi tramite

Configurare l'autenticazione del servizio app (EasyAuth)

Servizio app di Azure fornisce l'autenticazione predefinita (spesso denominata "EasyAuth") che gestisce l'accesso utente prima che le richieste raggiungano l'applicazione. Il generatore di API dati può leggere le informazioni sull'identità che il servizio app inserisce, abilitando l'autenticazione senza gestire direttamente i token.

Importante

Il AppService provider considera attendibili le intestazioni di identità inoltrate da EasyAuth. Assicurarsi che i client non possano ignorare EasyAuth e raggiungere direttamente il generatore di API dati.

Flusso di autenticazione

Quando il generatore di API dati viene eseguito dietro il servizio app di Azure con l'autenticazione abilitata, il servizio app gestisce il flusso OAuth e passa le informazioni sull'identità tramite intestazioni HTTP:

Illustrazione del flusso di autenticazione del servizio app che mostra come EasyAuth inserisce le intestazioni di identità.

Phase Che succede
Autenticazione utente App Service intercetta le richieste non autenticate e reindirizza al provider di identità
Inserimento di identità Dopo l'autenticazione, il servizio app aggiunge l'intestazione X-MS-CLIENT-PRINCIPAL
Elaborazione DAB Generatore API dati Base64 decodifica l'intestazione JSON e compila un oggetto ClaimsPrincipal dalla claims matrice
Autorizzazione DAB usa ClaimsPrincipal.IsInRole() per convalidare l'intestazione X-MS-API-ROLE , quindi valuta le autorizzazioni e i criteri

Prerequisiti

  • Una sottoscrizione di Azure
  • Servizio app di Azure o Funzioni di Azure (nell'infrastruttura del servizio app)
  • CLI di Data API builder installata (guida all'installazione)
  • Un dab-config.json esistente con almeno un'entità

Riferimento rapido

Impostazione Value
Provider AppService
Intestazione di identità X-MS-CLIENT-PRINCIPAL (JSON con codifica Base64)
Selezione ruolo intestazione X-MS-API-ROLE
Supporta attestazioni personalizzate Yes
Test locali Sì (impostare manualmente le intestazioni)

Passaggio 1: Abilitare l'autenticazione del servizio app

Configurare l'autenticazione nel servizio app di Azure:

  1. Nel portale di Azure passare al servizio app.

  2. Selezionare Impostazioni>Autenticazione.

  3. Seleziona Aggiungi provider di identità.

  4. Scegliere Microsoft (o un altro provider supportato).

  5. Configurare le impostazioni:

    • Tipo di registrazione dell'app: crearne uno nuovo o selezionare quello esistente
    • Tipi di account supportati: scegliere in base al proprio scenario
    • Limitare l'accesso: richiedere l'autenticazione

  6. Seleziona Aggiungi.

Suggerimento

L'autenticazione del servizio app funziona con più provider di identità, tra cui Microsoft, Google, Facebook, Twitter e OpenID Connect.

Passaggio 2: Configurare il generatore di API dati

Impostare il provider di autenticazione su AppService:

CLI

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

Configurazione risultante

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

Annotazioni

A differenza dei EntraID/AzureAD provider o Custom , AppService non richiede jwt.audience o jwt.issuer impostazioni. Il servizio app convalida il token prima di passare le informazioni sull'identità a DAB.

Passaggio 3: Configurare le autorizzazioni per le entità

Definire le autorizzazioni per i ruoli. Il generatore di API di dati valuta i ruoli tramite ClaimsPrincipal.IsInRole(), che verifica le attestazioni analizzate dall'intestazione X-MS-CLIENT-PRINCIPAL. Includere le attestazioni di ruolo nella claims matrice con il tipo di attestazione del ruolo appropriato.

Configurazione di esempio

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

Configurazione risultante

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

Passaggio 4: Testare localmente con X-MS-CLIENT-PRINCIPAL

È possibile testare l'autenticazione del servizio app in locale specificando manualmente l'intestazione X-MS-CLIENT-PRINCIPAL . Questo approccio simula ciò che EasyAuth inoltra alla tua app e consente di testare il comportamento basato su ruoli e dichiarazioni senza distribuire su Azure.

Creare un principale client

L'intestazione X-MS-CLIENT-PRINCIPAL contiene un oggetto JSON con codifica Base64. Generatore API dati analizza le proprietà seguenti:

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

Codificare il principale

Codificare il codice JSON come Base64. È possibile usare qualsiasi strumento:

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

Invia una richiesta con l'intestazione

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

Struttura X-MS-CLIENT-PRINCIPAL

Il Data API Builder analizza le proprietà seguenti dal principale client:

Proprietà TIPO Description
auth_typ corda Tipo di autenticazione , ad esempio aad. Necessario affinché l'identità sia considerata autenticata.
name_typ corda (Facoltativo) Tipo di attestazione usato per il nome dell'utente
role_typ corda (Facoltativo) Tipo di attestazione usato per i ruoli (per impostazione predefinita )roles
claims object[] Matrice di attestazioni con le proprietà typ e val. I ruoli devono essere inclusi qui come attestazioni.

Importante

I ruoli vengono valutati tramite ClaimsPrincipal.IsInRole(), che controlla l'array claims alla ricerca di dichiarazioni corrispondenti a role_typ. Includere ogni ruolo come una voce distinta di attestazione, ad esempio { "typ": "roles", "val": "editor" }.

Uso delle dichiarazioni nei criteri di database

Con il provider AppService è possibile usare le attestazioni nei criteri di database. Ciò consente la sicurezza a livello di riga in base all'identità utente.

Esempio: Filtrare in base all'ID oggetto utente

In questo esempio si usa la dichiarazione oid (identificatore di oggetto), che Microsoft Entra ID include nei token:

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

Suggerimento

I tipi di attestazione comuni di Microsoft Entra ID includono oid (ID oggetto), email, namee preferred_username. Utilizzare la stringa esatta del tipo di attestazione del proprio provider di identità.

Riferimenti alle rivendicazioni disponibili

I riferimenti alle attestazioni usano la stringa esatta del tipo di attestazione dalla matrice claims.

Riferimento alla dichiarazione Description
@claims.<claim-type> Qualsiasi dichiarazione dalla matrice claims, corrispondente alla proprietà typ

Ad esempio, se il principale include { "typ": "email", "val": "alice@contoso.com" }, usare @claims.email nella politica. Il tipo di attestazione deve corrispondere esattamente.

Richieste anonime

Quando il servizio app consente richieste non autenticate o quando si esegue il test in locale senza l'intestazione X-MS-CLIENT-PRINCIPAL, il middleware di autenticazione del generatore di API dati imposta automaticamente l'intestazione X-MS-API-ROLE su anonymous. Le richieste vengono quindi valutate usando il anonymous ruolo :

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

Per il corretto funzionamento, l'entità deve disporre delle autorizzazioni per il anonymous ruolo:

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

Risoluzione dei problemi

Sintomo Possibile causa Soluzione
401 Unauthorized (o reindirizzare al login) EasyAuth ha bloccato la richiesta prima che abbia raggiunto DAB Accedere tramite EasyAuth o inviare credenziali valide; verificare le impostazioni di autenticazione del servizio app
403 Forbidden Ruolo non incluso nelle autorizzazioni Aggiungere il ruolo alle autorizzazioni dell'entità
403 Forbidden X-MS-API-ROLE non nei ruoli dell'utente Verificare che il valore dell'header corrisponda a un'attestazione di ruolo nell'array del principal claims
Attestazioni non disponibili Matrice mancante claims nel principale Aggiungere attestazioni al X-MS-CLIENT-PRINCIPAL codice JSON
Ruolo non riconosciuto Ruoli non inclusi nella claims matrice Aggiungere le attestazioni di ruolo con le corrette role_typ (ad esempio, { "typ": "roles", "val": "editor" })
Il test locale ha esito negativo Intestazione non con codifica Base64 Codificare correttamente il codice JSON prima dell'invio

Esempio di configurazione completo

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

Contenuti correlati

  • Last updated on