Condividi tramite

Configurare l'autenticazione con Microsoft Entra ID

Questa guida illustra come configurare l'autenticazione di Microsoft Entra ID (in precedenza Azure Active Directory) per il generatore di API dati. Alla fine, l'app client autentica gli utenti tramite Entra, acquisisce i token per il generatore di API dati e DAB può usare l'identità gestita per connettersi ad Azure SQL.

Il generatore di API dati autentica le richieste in ingresso usando la convalida del bearer JWT (EntraID/AzureAD/Custom) o le intestazioni di identità fornite dalla piattaforma ().AppService Per lo sviluppo locale e il test delle autorizzazioni, usare il Simulator provider.

Illustrazione del modo in cui i client eseguono l'autenticazione a Data API Builder usando i token JWT.

Guide dei provider di autenticazione

Scegli una guida in base al provider di identità:

Provider Guida
Microsoft Entra ID Questo articolo
Okta, Auth0 o altro Configurare l'autenticazione JWT personalizzata
Servizio app di Azure Configurare l'autenticazione del servizio app
Test locali Configurare l'autenticazione del simulatore

Flusso di autenticazione

Il diagramma seguente illustra il flusso di autenticazione completo quando si usa Microsoft Entra ID con Il generatore di API dati:

Illustrazione della sequenza di autenticazione di Microsoft Entra ID che mostra l'accesso utente, l'acquisizione di token e l'accesso al database.

Il flusso ha tre fasi distinte:

Phase Description
Autenticazione utente L'utente accede tramite l'app client tramite Microsoft Entra ID
Autenticazione client L'applicazione client acquisisce un token con ambito DAB e chiama Data API builder
Accesso al database Il generatore di API dati convalida il token, quindi si connette al database usando la propria identità (identità gestita o credenziali della stringa di connessione)

Importante

Il generatore di API dati convalida il token utente in ingresso per l'autenticazione API, ma si connette al database usando le proprie credenziali (identità gestita o autenticazione SQL). DAB non esegue lo scambio di token ON-Behalf-Of (OBO) per accedere al database come utente chiamante.

Prerequisiti

  • Una sottoscrizione di Azure con il tenant di Microsoft Entra ID
  • CLI di Data API builder installata (guida all'installazione)
  • Un dab-config.json esistente con almeno un'entità
  • (Facoltativo) Database SQL di Azure per scenari di identità gestita

Riferimento rapido

Impostazione Value
Provider EntraID (o AzureAD per compatibilità)
Obbligatorio per la convalida aud, issexp, firma valida
Obbligatorio per l'autorizzazione roles attestazione (solo se si usano ruoli personalizzati)
Formato emittente https://login.microsoftonline.com/<tenant-id>/v2.0
Formato audience api://<app-id> o URI dell'ID applicazione personalizzato
Ruolo predefinito Authenticated
Intestazione del ruolo personalizzata X-MS-API-ROLE
Tipo di attestazione del ruolo roles (fisso, non configurabile)

Annotazioni

Quando si usa EntraID o AzureAD come provider, DAB abilita la convalida aggiuntiva dell'autorità emittente della chiave di firma specifica per i token Microsoft Entra. Ciò garantisce una maggiore sicurezza rispetto al provider generico Custom .

Passaggio 1: Registrare un'applicazione in Microsoft Entra ID

Creare una registrazione dell'app che rappresenta l'API del Data API Builder. Le app client richiederanno token con un gruppo di destinatari che corrisponde a questa registrazione.

  1. Accedere all'interfaccia di amministrazione di Microsoft Entra.

  2. Passare a Identità>Applicazioni>Registrazioni delle app.

  3. Seleziona Nuova registrazione.

  4. Immettere un nome , ad esempio Data API Builder API.

  5. Selezionare i tipi di account supportati appropriati per lo scenario:

    • Tenant singolo: solo gli utenti della tua organizzazione
    • Multitenant: utenti in ogni directory di Microsoft Entra

  6. Lasciare vuoto l'URI di reindirizzamento (questa registrazione è per l'API e non per il client).

  7. Selezionare Registrazione.

  8. Nella pagina Panoramica dell'app registrare questi valori:

    Value Dove trovarlo Utilizzo
    ID client dell'applicazione Pagina di panoramica Creazione dell'URI del pubblico
    ID della directory (tenant) Pagina di panoramica Creazione dell'URL dell'emittente

Configurare l'URI dell'ID applicazione

  1. Nella registrazione dell'app passare a Esporre un'API.

  2. Selezionare Aggiungi accanto a URI ID applicazione.

  3. Accettare il valore predefinito (api://<app-id>) o immettere un URI personalizzato.

  4. Seleziona Salva.

Suggerimento

L'URI ID dell'applicazione diventa il valore audience nella configurazione DAB. Usare un formato coerente in ambienti diversi.

Aggiungere ruoli dell'app (facoltativo)

Se si vogliono usare ruoli personalizzati oltre Anonymous a e Authenticated:

  1. Passare a Ruoli app.

  2. Selezionare Crea ruolo app.

  3. Inserire:

    • Nome visualizzato: Reader
    • Tipi di membri consentiti: utenti/gruppi o entrambi
    • Valore: reader (questo valore viene visualizzato nell'attestazione del roles token)
    • Descrizione: Read-only access to data

  4. Selezionare Applica.

  5. Ripetere per i ruoli aggiuntivi (ad esempio, writer, admin).

Passaggio 2: Configurare il generatore di API dati

Configurare DAB per convalidare i token rilasciati dal tenant Entra per il gruppo di destinatari dell'API.

CLI

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

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Configurazione risultante

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

Passaggio 3: Configurare le autorizzazioni per le entità

Definire quali ruoli possono accedere a ogni entità. Le richieste vengono valutate rispetto al ruolo determinato dal token.

Concedere l'accesso agli utenti autenticati

dab update Book \
  --permissions "Authenticated:read"

Concedere l'accesso a un ruolo personalizzato

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

Configurazione risultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Passaggio 4: Configurare la connessione al database

Il generatore di API dati si connette al database usando la propria identità, separata dall'utente autenticato. Per gli scenari di produzione con Azure SQL, usare l'identità gestita.

Annotazioni

La connessione al database usa l'identità del servizio DAB (identità gestita o credenziali SQL), non l'identità dell'utente chiamante. DAB non passa i token utente al database.

Identità gestita assegnata dal sistema

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

Identità gestita assegnata dall'utente

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Opzione B: Autenticazione SQL (sviluppo)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Importante

Non eseguire mai il commit delle stringhe di connessione con password nel controllo del codice sorgente. Utilizzare variabili di ambiente o Azure Key Vault.

Opzione C: Sviluppo locale con az login

Per lo sviluppo locale con Azure SQL, usare le credenziali dell'interfaccia della riga di comando di Azure:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Prima di avviare DAB, accedere:

az login

Passaggio 5: Testare la configurazione

  1. Avviare il generatore di API dati:

    dab start

  2. Acquisire un token per l'API. Usare Microsoft Authentication Library (MSAL) o uno strumento come jwt.ms per i test.

  3. Chiamare l'API con il token:

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

  4. Per usare un ruolo personalizzato, includere l'intestazione X-MS-API-ROLE :

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: reader"

Annotazioni

Il ruolo specificato in X-MS-API-ROLE deve esistere nella rivendicazione del token roles. Se il ruolo non è presente nel token, la richiesta viene rifiutata.

Comportamento di selezione dei ruoli

Il generatore di API dati determina il ruolo della richiesta usando questa logica:

Il token è presente? Intestazione X-MS-API-ROLE? Ruolo nel token? Result
NO NO — Anonymous
Sì (valido) NO — Authenticated
Sì (valido) Yes NO Rifiutato (403 Vietato)
Sì (valido) Yes Yes Valore intestazione
Sì (non valido) — — Rifiutato (401 Non autorizzato)

Risoluzione dei problemi

Sintomo Possibile causa Soluzione
401 Unauthorized Token scaduto o non valido Acquisire un nuovo token; controllare il token su jwt.ms
401 Unauthorized Discordanza del pubblico Verificare che jwt.audience corrisponda all'affermazione del aud token
401 Unauthorized Mancata corrispondenza del mittente Verificare che jwt.issuer corrisponda esattamente alla dichiarazione di iss token
403 Forbidden Ruolo non nel token Assicurarsi che all'utente sia assegnato il ruolo applicativo in Entra
403 Forbidden Nessuna autorizzazione per il ruolo Aggiungere il ruolo alla matrice dell'entità permissions

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=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Contenuti correlati

  • Last updated on