Configurare l'autenticazione del simulatore per i test locali

Il provider di autenticazione del simulatore consente di testare le autorizzazioni basate sui ruoli localmente senza configurare un provider di identità. Usarlo durante lo sviluppo per verificare che le regole di autorizzazione funzionino correttamente prima della distribuzione nell'ambiente di produzione.

Scegliere un provider di autenticazione locale

Durante lo sviluppo, è possibile testare l'autenticazione e l'autorizzazione senza configurare un provider di identità di produzione.

Provider	Ideale per	Note
Simulatore	Test rapido delle autorizzazioni	Solo sviluppo. Considera ogni richiesta come autenticata. Il valore predefinito è Authenticated role; eseguire l'override con X-MS-API-ROLE.
AppService	Test basati sulle attestazioni	Simulare EasyAuth in locale inviando X-MS-CLIENT-PRINCIPAL con attestazioni personalizzate. Per informazioni dettagliate, vedere Configurare l'autenticazione del servizio app.

Flusso di autenticazione

Il provider del simulatore considera tutte le richieste come autenticate, consentendo di concentrarsi sui test delle regole di autorizzazione:

Phase	Che succede
La richiesta arriva	Lo sviluppatore invia una richiesta HTTP a DAB
Assegnazione di ruolo	DAB assegna Authenticated (impostazione predefinita) o il ruolo dall'intestazione X-MS-API-ROLE
Controllo dei permessi	DAB valuta la richiesta rispetto alle autorizzazioni dell'entità per tale ruolo
Esecuzione di query	Se consentito, DAB esegue una query sul database e restituisce i risultati

Importante

Il provider del simulatore è solo per sviluppo. Non usarlo mai nell'ambiente di produzione, ignorando tutte le autenticazioni reali.

Prerequisiti

• CLI di Data API builder installata (guida all'installazione)
• Un dab-config.json esistente con almeno un'entità

Riferimento rapido

Impostazione	Value
Provider	Simulator
Modalità host	development (obbligatorio)
Ruolo predefinito	Authenticated (inserito automaticamente)
Intestazione di override del ruolo	X-MS-API-ROLE
Token obbligatorio	NO
Supporto per i reclami	Limitato (solo ruoli Anonymous/Authenticated di sistema; nessuna richiesta arbitraria)

Passaggio 1: Configurare il provider del simulatore

Impostare il provider di autenticazione su Simulatore e verificare che la modalità di sviluppo sia abilitata.

CLI

Bash

# Enable development mode
dab configure \
  --runtime.host.mode development

# Set the Simulator provider
dab configure \
  --runtime.host.authentication.provider Simulator

Prompt dei comandi

REM Enable development mode
dab configure ^
  --runtime.host.mode development

REM Set the Simulator provider
dab configure ^
  --runtime.host.authentication.provider Simulator

Configurazione risultante

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Annotazioni

Il provider del simulatore funziona solo quando mode è impostato su development. In modalità di produzione, DAB rifiuta il fornitore del simulatore e non riesce ad avviarsi.

Passaggio 2: Configurare le autorizzazioni per le entità

Definire le autorizzazioni per i ruoli da testare. È possibile testare i ruoli di sistema (Anonymous, Authenticated) e i ruoli personalizzati.

Esempio: più ruoli

Bash

# Allow anonymous read access
dab update Book \
  --permissions "Anonymous:read"

# Allow authenticated users full read access
dab update Book \
  --permissions "Authenticated:read"

# Allow authors to create and update
dab update Book \
  --permissions "author:create,read,update"

# Allow admins full access
dab update Book \
  --permissions "admin:*"

Prompt dei comandi

REM Allow anonymous read access
dab update Book ^
  --permissions "Anonymous:read"

REM Allow authenticated users full read access
dab update Book ^
  --permissions "Authenticated:read"

REM Allow authors to create and update
dab update Book ^
  --permissions "author:create,read,update"

REM Allow admins full access
dab update Book ^
  --permissions "admin:*"

Configurazione risultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Passaggio 3: Testare ruoli diversi

Avviare Generatore API dati e inviare richieste per testare ogni ruolo.

dab start

Prova come autenticato (impostazione predefinita)

Senza intestazioni speciali, le richieste vengono valutate come il ruolo Authenticated.

curl -X GET "http://localhost:5000/api/Book"

Test come anonimo

Usa l'intestazione X-MS-API-ROLE per testare come Anonymous.

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous"

Testare come ruolo personalizzato

Usare l'intestazione X-MS-API-ROLE per testare qualsiasi ruolo personalizzato:

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: author"

Annotazioni

Con il Simulatore, il test dei ruoli personalizzati funziona perché DAB valuta le autorizzazioni in base al valore dell'intestazione X-MS-API-ROLE . I ruoli di sistema (Anonymous, Authenticated) sono sempre disponibili. Se una richiesta di ruolo personalizzata restituisce 403, verificare che il nome del ruolo corrisponda esattamente alle autorizzazioni dell'entità.

Testare un'azione che deve essere negata

Provare un'azione per cui il ruolo non dispone dell'autorizzazione per:

# This should fail—Anonymous can only read
curl -X POST "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Book", "author": "Test"}'

Risposta prevista: 403 Forbidden

Scenari di test

Usare il simulatore per testare questi scenari comuni:

Scenario	Come eseguire il test
Accesso anonimo	Impostare X-MS-API-ROLE: Anonymous
Accesso autenticato	Omettere le intestazioni (impostazione predefinita) o impostare X-MS-API-ROLE: Authenticated
Accesso al ruolo personalizzato	Impostare X-MS-API-ROLE: <role-name>
Azione negata	Richiedere un'azione per cui il ruolo non dispone dell'autorizzazione
Restrizioni dei campi	Configurare le autorizzazioni a livello di campo e verificare i campi di risposta
Ruolo mancante	Impostare X-MS-API-ROLE: nonexistent per testare la gestione degli errori

Limitazioni

Il provider del simulatore presenta queste limitazioni:

Limitation	Soluzione
Nessuna dichiarazione personalizzata	Usare il provider AppService con X-MS-CLIENT-PRINCIPAL l'intestazione
Nessun criteri di database con attestazioni	Testare i criteri usando il provider AppService
Nessuna convalida del token	Passare a Entra o a Provider personalizzato per la produzione
Solo modalità di sviluppo	Usare un provider reale nell'ambiente di produzione

Suggerimento

Se è necessario testare i criteri di database che usano attestazioni (ad esempio @claims.userId), usare invece l'AppService provider. Consente di fornire attestazioni personalizzate tramite l'intestazione X-MS-CLIENT-PRINCIPAL .

Transizione alla produzione

Quando si è pronti per la distribuzione, sostituire il provider del simulatore con un provider di produzione:

1. Passare mode da development a production
2. Passare provider da Simulator al provider scelto (EntraID/AzureAD, AppServiceo )Custom
3. Configurare le impostazioni JWT necessarie (gruppo di destinatari, autorità di certificazione)

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

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": "Server=localhost;Database=Library;Trusted_Connection=true;TrustServerCertificate=true;"
  },
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contenuti correlati

• Autorizzazione e ruoli
• Configurare l'autenticazione del servizio app
• Configurare l'autenticazione di Microsoft Entra ID
• Informazioni di riferimento sulla configurazione del runtime