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 JSON Web Token (JWT) bearer (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 flusso ha tre fasi distinte:

Fase Descrizione
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 per impostazione predefinita. Per abilitare OBO in modo che il database esegua l'autenticazione come chiamante effettivo, vedere Configurare l'autenticazione OBO.

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

Se si usa EntraID o AzureAD come provider, DAB abilita la convalida aggiuntiva dell'emittente della chiave di firma specificamente per i token Microsoft Entra. Questa convalida garantisce una sicurezza più avanzata 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 richiedono token con un gruppo di destinatari che corrisponde a questa registrazione.

  1. Accedi 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:

    Valore Dove trovarlo Usato per
    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 dell'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 un ambito

È necessario un ambito in modo che le applicazioni client (incluso Azure CLI) possano richiedere token di accesso delegati per l'API.

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

  2. In Ambiti definiti da questa API selezionare Aggiungi un ambito.

  3. Inserire:

    • Nome ambit: Endpoint.Access
    • Chi può fornire il consenso?: Amministratori e utenti
    • Nome visualizzato del consenso amministratore: Execute requests against Data API builder
    • Descrizione del consenso amministratore: Allows client app to send requests to Data API builder endpoint.
    • Nome visualizzato del consenso utente: Execute requests against Data API builder
    • Descrizione del consenso utente: Allows client app to send requests to Data API builder endpoint.
    • Stato: Abilitato

  4. Seleziona Aggiungi ambito.

Annotazioni

Il valore dell'ambito completo è api://<app-id>/Endpoint.Access. Le applicazioni client usano questo valore quando si richiedono token.

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. Seleziona Applica.

  5. Ripetere per più ruoli (ad esempio, writer, admin).

Impostare la versione del token manifest

Per impostazione predefinita, il manifesto di registrazione dell'app imposta accessTokenAcceptedVersion su null, il che genera token v1.0. I token V1 usano un formato di autorità di certificazione diverso (https://sts.windows.net/<tenant-id>/) rispetto all'autorità emittente v2.0 configurata in DAB, che causa l'esito negativo della convalida dei token.

  1. Nella registrazione dell'app passare a Manifesto.

  2. Trovare accessTokenAcceptedVersion e modificare il valore in 2.

  3. Seleziona Salva.

Importante

Se accessTokenAcceptedVersion è null o 1, l'attestazione iss nel token non corrisponde all'URL dell'autorità di certificazione v2.0 configurata in DAB e tutte le richieste hanno esito negativo con 401 Unauthorized.

Assegnare utenti ai ruoli dell'app

La creazione di ruoli dell'app non concede automaticamente agli utenti. È necessario assegnare utenti o gruppi tramite l'applicazione aziendale.

  1. Nell'interfaccia di amministrazione Microsoft Entra, passare a Identity>Applications>Applicazioni aziendali.

  2. Cerca e seleziona l'app, ad esempio Data API Builder API. Un'applicazione aziendale è stata creata automaticamente quando è stata registrata l'app.

  3. Passare a Utenti e gruppi.

  4. Selezionare Aggiungi utente/gruppo.

  5. In Utenti selezionare l'account utente da assegnare e selezionare Seleziona.

  6. In Selezionare un ruolo scegliere il ruolo da assegnare , ad esempio Reader. Se il ruolo non viene visualizzato, attendere qualche minuto per il completamento del processo di replica di Microsoft Entra.

  7. Seleziona Assegna.

  8. Ripetere per ogni ruolo da assegnare.

Annotazioni

Senza l'assegnazione di ruolo, l'attestazione roles nel token dell'utente è vuota e le richieste che usano X-MS-API-ROLE con un ruolo personalizzato vengono rifiutate con 403 Forbidden.

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 di Azure CLI:

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

Autorizzare Azure CLI come applicazione client

Prima che Azure CLI possa acquisire i token per la tua API, è necessario aggiungerla come applicazione client autorizzata.

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

  2. In Applicazioni client autorizzate selezionare Aggiungi applicazione client.

  3. Immettere l'ID client Azure CLI: 00001111-aaaa-2222-bbbb-3333cccc4444.

  4. Selezionare l'ambito api://<app-id>/Endpoint.Access.

  5. Seleziona Aggiungi applicazione.

Acquisire un token con Azure CLI

Accedere a Azure CLI e impostare il tenant in cui esiste la registrazione dell'app:

az login
az account set --tenant <your-tenant-id>

Richiedere un token con ambito definito per la tua API:

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

Annotazioni

Se è stato ricevuto un errore di consenso AADSTS65001, verificare di aver aggiunto l'ID client Azure CLI (00001111-aaaa-2222-bbbb-3333cccc4444) come applicazione client autorizzata nel passaggio precedente.

È possibile esaminare il token su jwt.ms per verificare le attestazioni aud, iss e roles.

Avviare DAB e inviare una richiesta

  1. Avviare il generatore di API dati:

    dab start

  2. Chiamare l'API con il token:

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

  3. 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) Sì No Rifiutato (403 Vietato)
Sì (valido) Sì Sì Valore intestazione
Sì (non valido) - - Rifiutato (401 Non autorizzato)

Risoluzione dei problemi

Sintomo Possibile causa Soluzione
401 Unauthorized Token scaduto o malformato 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 Verificare che l'utente sia assegnato al ruolo dell'app 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