Esercitazione: Connettere un'app del Servizio app al database SQL per conto dell'utente connesso

Questa esercitazione illustra come abilitare l'autenticazione predefinita in un'app del Servizio app usando il provider di autenticazione Microsoft Entra, quindi estenderla mediante la connessione a un database SQL di Azure back-end tramite rappresentazione dell'utente connesso. Questo approccio è noto anche come flusso On-Behalf-Of (OBO). Si tratta di un approccio di connettività più avanzato rispetto a Esercitazione: Accedere ai dati con l'identità gestita e presenta i vantaggi seguenti negli scenari aziendali:

• Elimina i segreti di connessione ai servizi back-end, proprio come l'approccio basato su identità gestite.
• Fornisce al database back-end, o a qualsiasi altro servizio di Azure, un maggiore controllo sulle persone o sul livello di accesso da concedere per i dati e le funzionalità.
• Consente all'app di adattare la presentazione dei dati all'utente connesso.

In questa esercitazione si aggiunge l'autenticazione di Microsoft Entra all'app Web di esempio distribuita in una delle esercitazioni seguenti:

• Esercitazione: Creare un'app ASP.NET in Azure con un database SQL di Azure
• Esercitazione: Creare un'app ASP.NET Core con database SQL di Azure nel servizio app di Azure

Al termine, l'app di esempio eseguirà in modo sicuro l'autenticazione degli utenti che si connettono al database SQL per conto dell'utente connesso.

Nota

Le procedure descritte in questa esercitazione supportano le versioni seguenti:

• .NET Framework 4.8 e versioni successive
• .NET 6.0 e versioni successive

Contenuto dell'esercitazione:

• Abilitare l'autenticazione predefinita per il database SQL di Azure
• Disabilitare altre opzioni di autenticazione nel database SQL di Azure
• Abilitare l'autenticazione del servizio app
• Usare Microsoft Entra ID come provider di identità
• Accedere al database SQL di Azure per conto dell'utente di Microsoft Entra connesso

Nota

L'autenticazione di Microsoft Entra è diversa dall'Autenticazione integrata di Windows nell'ambiente Active Directory locale (Active Directory Domain Services). Active Directory Domain Services e Microsoft Entra ID usano protocolli di autenticazione completamente diversi. Per altre informazioni, vedere la documentazione di Microsoft Entra Domain Services.

Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.

Prerequisiti

Questo articolo riprende la procedura nel punto in cui è stata interrotta in una delle esercitazioni seguenti:

• Esercitazione: Creare un'app ASP.NET in Azure con un database SQL
• Esercitazione: Compilare un'app ASP.NET Core e database SQL in Servizio app di Azure.

Se non è già stato fatto, seguire prima una delle due esercitazioni. In alternativa, è possibile adattare le procedure alla propria app .NET con un database SQL.

Preparare l'ambiente per l'interfaccia della riga di comando di Azure.

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser. È possibile usare Bash o PowerShell con Cloud Shell per usare i servizi di Azure. È possibile usare i comandi preinstallati di Cloud Shell per eseguire il codice contenuto in questo articolo senza dover installare strumenti nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione	Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un blocco di codice o di comando. Quando si seleziona Prova, il codice o il comando non viene copiato automaticamente in Cloud Shell.
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser.
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo in alto a destra del portale di Azure.

Per usare Azure Cloud Shell:

1. Avviare Cloud Shell.

2. Selezionare il pulsante Copia in un blocco di codice (o in un blocco di comando) per copiare il codice o il comando.

3. Incollare il codice o il comando nella sessione di Cloud Shell selezionando CTRL+MAIUSC+V in Windows e Linux o selezionando CMD+MAIUSC+V in macOS.

4. Premere Invio per eseguire il codice o il comando.

1. Configurare il server di database con l'autenticazione di Microsoft Entra

Abilitare prima di tutto l'autenticazione di Microsoft Entra nel database SQL assegnando un utente di Microsoft Entra come amministratore del server. Questo utente è diverso dall'account Microsoft usato per effettuare l'iscrizione alla sottoscrizione di Azure. Deve essere un utente creato, importato, sincronizzato o invitato in Microsoft Entra ID. Per altre informazioni sugli utenti di Microsoft Entra consentiti, vedere Funzionalità e limitazioni di Microsoft Entra nel database SQL.

1. Se il tenant di Microsoft Entra non ha ancora un utente, crearne uno seguendo la procedura descritta in Aggiungere o eliminare utenti usando Microsoft Entra ID.

2. Trovare l'ID oggetto dell'utente di Microsoft Entra tramite az ad user list e sostituire <user-principal-name>. Il risultato viene salvato in una variabile.

   azureaduser=$(az ad user list --filter "userPrincipalName eq '<user-principal-name>'" --query [].id --output tsv)
   

   Suggerimento

   Per visualizzare l'elenco di tutti i nomi delle entità utente in Microsoft Entra ID, eseguire az ad user list --query [].userPrincipalName.

3. Aggiungere questo utente di Microsoft Entra come amministratore di Active Directory usando il comando az sql server ad-admin create in Cloud Shell. Nel comando seguente sostituire <server-name> con il nome del server, senza il suffisso .database.windows.net.

   az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id $azureaduser
   

4. Limitare l'autenticazione del server di database all'autenticazione di Active Directory. Questo passaggio disabilita di fatto l'autenticazione SQL.

   az sql server ad-only-auth enable --resource-group <group-name> --name <server-name>
   

Per altre informazioni sull'aggiunta di un amministratore di Active Directory, vedere Effettuare il provisioning dell'amministratore di Microsoft Entra (database SQL).

2. Abilitare l'autenticazione utente per l'app

Abilitare l'autenticazione con Microsoft Entra ID come provider di identità. Per altre informazioni, vedere Configurare l'autenticazione di Microsoft Entra per un'applicazione dei servizi app.

1. Nel menu del portale di Azure selezionare Gruppi di risorse oppure cercare e selezionare Gruppi di risorse da qualsiasi pagina.

2. In Gruppi di risorse trovare e selezionare il gruppo di risorse e quindi selezionare l'app.

3. Nel menu a sinistra dell'app selezionare Autenticazione e quindi selezionare Aggiungi provider di identità.

4. Nella pagina Aggiungi un provider di identità selezionare Microsoft come Provider di identità per l'acceso di identità Microsoft e Microsoft Entra.

5. Accettare le impostazioni predefinite e fare clic su OK.

   

Suggerimento

Se si verificano errori e le impostazioni di autenticazione dell'app vengono riconfigurate, i token nell'archivio token potrebbero non essere rigenerati dalle nuove impostazioni. Per assicurarsi che i token vengano rigenerati, è necessario disconnettersi e accedere di nuovo all'app. Un modo semplice per eseguire tale operazione consiste nell'usare il browser in modalità privata, chiudendo e riaprendo il browser in modalità privata dopo aver modificato le impostazioni nelle app.

3. Configurare la rappresentazione utente nel database SQL

L'app di Azure si connette attualmente al database SQL usando l'autenticazione SQL (nome utente e password) gestita come impostazioni dell'app. In questo passaggio si assegnano all'app le autorizzazioni per accedere al database SQL per conto dell'utente connesso a Microsoft Entra.

1. Nella pagina Autenticazione per l'app selezionare il nome dell'app in Provider di identità. La registrazione dell'app è stata generata automaticamente. Selezionare Autorizzazioni API nel menu a sinistra.

2. Selezionare Aggiungi un'autorizzazione e quindi API usate dall'organizzazione.

3. Digitare Database SQL di Azure nella casella di ricerca e selezionare il risultato.

4. Nella pagina Richiedi autorizzazioni API per il database SQL di Azure selezionare Autorizzazioni delegate e user_impersonation, quindi selezionare Aggiungi autorizzazioni.

   

4. Configurare il servizio app per la restituzione di un token di accesso utilizzabile

La registrazione dell'app in Microsoft Entra ID ha ora le autorizzazioni necessarie per connettersi al database SQL rappresentando l'utente connesso. Configurare quindi l'app del Servizio app in modo che fornisca un token di accesso utilizzabile.

In Cloud Shell eseguire i comandi seguenti nell'app per aggiungere il parametro scope all'impostazione di autenticazione identityProviders.azureActiveDirectory.login.loginParameters. Usa [jq] per l'elaborazione JSON, che è già installata in Cloud Shell.

authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)
authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.windows.net/user_impersonation"]}')
az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

I comandi aggiungono in pratica una proprietà loginParameters con ambiti personalizzati aggiuntivi. Ecco una spiegazione degli ambiti richiesti:

• openid, profile e email sono già richiesti dal Servizio app per impostazione predefinita. Per informazioni, vedere Ambiti di OpenID Connect.
• https://database.windows.net/user_impersonation fa riferimento al database SQL di Azure. È l'ambito che fornisce un token JWT che include il database SQL come destinatari del token.
• offline_access è incluso qui per praticità, nel caso in cui si vogliano aggiornare i token.

Suggerimento

Per configurare gli ambiti necessari usando invece un'interfaccia Web, vedere la procedura Microsoft in Aggiornare i token di autenticazione.

Le app sono ora configurate. L'app può ora generare un token accettato dal database SQL.

5. Usare il token di accesso nel codice dell'applicazione

I passaggi da seguire per il progetto dipendono dal fatto che si usi Entity Framework (impostazione predefinita per ASP.NET) o Entity Framework Core (impostazione predefinita per ASP.NET Core).

Entity Framework

1. In Visual Studio aprire la console di Gestione pacchetti e aggiornare Entity Framework:

   Update-Package EntityFramework
   

2. Nell'oggetto DbContext (in Models/MyDbContext.cs) aggiungere il codice seguente al costruttore predefinito.

   var conn = (System.Data.SqlClient.SqlConnection)Database.Connection;
   conn.AccessToken = System.Web.HttpContext.Current.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
   

Entity Framework Core

Nell'oggetto DbContext (in Models/MyDbContext.cs) modificare il costruttore predefinito come segue.

public MyDatabaseContext (DbContextOptions<MyDatabaseContext> options, IHttpContextAccessor accessor)
    : base(options)
{
    var conn = Database.GetDbConnection() as SqlConnection;
    conn.AccessToken = accessor.HttpContext.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];
}

Nota

Il codice aggiunge il token di accesso fornito dall'autenticazione del Servizio app all'oggetto connessione.

Questa modifica del codice non funziona in locale. Per altre informazioni, vedere Come si esegue il debug in locale quando si usa l'autenticazione del Servizio app?.

6. Pubblicare le modifiche

ASP.NET

1. Se si proviene da Esercitazione: Creare un'app ASP.NET in Azure con il database SQL, si imposta una stringa di connessione nel Servizio app usando l'autenticazione SQL, con nome utente e password. Usare il comando seguente per rimuovere i segreti di connessione, ma sostituire <group-name>, <app-name>, <db-server-name> e <db-name> con i valori personalizzati.

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings MyDbConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"
   

2. Pubblicare le modifiche in Visual Studio. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto DotNetAppSqlDb e selezionare Pubblica.

   

3. Nella pagina di pubblicazione selezionare Pubblica.

ASP.NET Core

1. Se proviene da Esercitazione: Creare un'app ASP.NET Core e database SQL nel Servizio app di Azure, si ha una stringa di connessione denominata defaultConnection nel Servizio app con l'autenticazione SQL, con nome utente e password. Usare il comando seguente per rimuovere i segreti di connessione, ma sostituire <group-name>, <app-name>, <db-server-name> e <db-name> con i valori personalizzati.

   az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type SQLAzure --settings defaultConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"
   

2. È stata apportata la modifica del codice nel fork di GitHub, con Visual Studio Code nel browser. Nel menu a sinistra selezionare Controllo del codice sorgente.

3. Digitare un messaggio di commit come OBO connect e selezionare Commit.

   Il commit attiva una distribuzione di GitHub Actions nel Servizio app. Attendere qualche minuto per il completamento della distribuzione.

Quando la nuova pagina Web mostra l'elenco attività, l'app si connette al database per conto dell'utente connesso a Microsoft Entra.

Dovrebbe ora essere possibile modificare l'elenco attività come prima.

7. Pulire le risorse

Nei passaggi precedenti sono state create risorse di Azure in un gruppo di risorse. Se si ritiene che queste risorse non saranno necessarie in futuro, eliminare il gruppo di risorse eseguendo questo comando in Cloud Shell:

az group delete --name <group-name>

L'esecuzione del comando può richiedere un minuto.

Domande frequenti

• Perché viene visualizzato un errore Login failed for user '<token-identified principal>'.?
• Come si aggiungono altri utenti o gruppi di Microsoft Entra nel database SQL di Azure?
• Come si esegue il debug in locale quando si usa l'autenticazione del Servizio app?
• Cosa accade quando scadono i token di accesso?

Perché viene visualizzato un errore Login failed for user '<token-identified principal>'.?

Le cause più comuni di questo errore sono le seguenti:

• Il codice viene eseguito in locale e non è presente alcun token valido nell'intestazione della richiesta X-MS-TOKEN-AAD-ACCESS-TOKEN. Vedere Come si esegue il debug in locale quando si usa l'autenticazione del Servizio app?.
• L'autenticazione di Microsoft Entra non è configurata nel database SQL.
• L'utente connesso non è autorizzato a connettersi al database. Vedere Come si aggiungono altri utenti o gruppi di Microsoft Entra nel database SQL di Azure?.

Come si aggiungono altri utenti o gruppi di Microsoft Entra nel database SQL di Azure?

1. Connettersi al server di database, ad esempio con sqlcmd o SSMS.

2. Creare utenti indipendenti mappati alle identità di Microsoft Entra nella documentazione del database SQL.

   Nell'esempio Transact-SQL seguente viene aggiunta un'identità di Microsoft Entra a SQL Server e vengono assegnati alcuni ruoli del database:

   CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];
   ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];
   ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];
   GO
   

Come si esegue il debug in locale quando si usa l'autenticazione del Servizio app?

Poiché l'autenticazione del servizio app è una funzionalità di Azure, non è possibile che lo stesso codice funzioni nell'ambiente locale. A differenza dell'app in esecuzione in Azure, il codice locale non trae vantaggio dal middleware di autenticazione del Servizio app. Sono disponibili alcune alternative:

• Connettersi al database SQL dall'ambiente locale con Active Directory Interactive. Il flusso di autenticazione non esegue l'accesso dell'utente all'app stessa, ma si connette al database back-end con l'utente connesso e consente di testare l'autorizzazione del database in locale.
• Copiare manualmente il token di accesso da https://<app-name>.azurewebsites.net/.auth/me nel codice, al posto dell'intestazione della richiesta X-MS-TOKEN-AAD-ACCESS-TOKEN.
• Se si esegue la distribuzione da Visual Studio, usare il debug remoto dell'app del Servizio app.

Cosa accade quando scadono i token di accesso?

Il token di accesso scade dopo un certo periodo di tempo. Per informazioni su come aggiornare i token di accesso senza chiedere agli utenti di autenticarsi di nuovo nell'app, vedere Refresh identity provider tokens (Aggiornare i token del provider di identità).

Passaggi successivi

Contenuto dell'esercitazione:

• Abilitare l'autenticazione predefinita per il database SQL di Azure
• Disabilitare altre opzioni di autenticazione nel database SQL di Azure
• Abilitare l'autenticazione del servizio app
• Usare Microsoft Entra ID come provider di identità
• Accedere al database SQL di Azure per conto dell'utente di Microsoft Entra connesso

Eseguire il mapping di un nome DNS personalizzato esistente al Servizio app di Azure

Esercitazione: Accedere a Microsoft Graph da un'app protetta come app

Esercitazione: Isolare le comunicazioni back-end con l'integrazione della rete virtuale