Condividi tramite

Scrivere codice di autenticazione dell'app client

  • Articolo

Dopo aver configurato un'istanza e l'autenticazione di Gemelli digitali di Azure, è possibile creare un'applicazione client che verrà usata per interagire con l'istanza. Dopo aver configurato un progetto client iniziale, è necessario scrivere codice nell'app client per autenticarlo nell'istanza di Gemelli digitali di Azure.

Gemelli digitali di Azure esegue l'autenticazione usando i token di sicurezza di Microsoft Entra basati su OAUTH 2.0. Per autenticare l'SDK, è necessario ottenere un token di connessione con le autorizzazioni appropriate per Gemelli digitali di Azure e passarlo insieme alle chiamate API.

Questo articolo descrive come ottenere le credenziali usando la Azure.Identity libreria client. Anche se questo articolo illustra esempi di codice in C#, ad esempio ciò che si scrive per .NET (C#) SDK, è possibile usare una versione di Azure.Identity indipendentemente dall'SDK in uso (per altre informazioni sugli SDK disponibili per Gemelli digitali di Azure, vedere API e SDK di Gemelli digitali di Azure.

Prerequisiti

Prima di tutto, completare i passaggi di installazione in Configurare un'istanza e l'autenticazione. Questa configurazione garantisce che si disponga di un'istanza di Gemelli digitali di Azure e che l'utente disponga delle autorizzazioni di accesso. Dopo questa configurazione, è possibile scrivere codice dell'app client.

Per continuare, è necessario un progetto di app client in cui si scrive il codice. Se non è già stato configurato un progetto di app client, creare un progetto di base nel linguaggio preferito da usare con questa esercitazione.

Eseguire l'autenticazione con la libreria Azure.Identity

Azure.Identity è una libreria client che fornisce diversi metodi di recupero delle credenziali che è possibile usare per ottenere un token di connessione ed eseguire l'autenticazione con l'SDK. Anche se questo articolo fornisce esempi in C#, è possibile visualizzare Azure.Identity diversi linguaggi, tra cui...

In sono disponibili tre metodi comuni di recupero delle credenziali:Azure.Identity

  • DefaultAzureCredential fornisce un flusso di autenticazione predefinito TokenCredential per le applicazioni che verranno distribuite in Azure ed è la scelta consigliata per lo sviluppo locale. Può anche essere abilitato per provare gli altri due metodi consigliati in questo articolo; esegue il ManagedIdentityCredential wrapping e può accedere InteractiveBrowserCredential con una variabile di configurazione.
  • ManagedIdentityCredential funziona bene nei casi in cui sono necessarie identità gestite (MSI) ed è un buon candidato per lavorare con Funzioni di Azure e la distribuzione nei servizi di Azure.
  • InteractiveBrowserCredential è destinato ad applicazioni interattive e può essere usato per creare un client SDK autenticato.

Il resto di questo articolo illustra come usare questi metodi con .NET (C#) SDK.

Aggiungere Azure.Identity al progetto .NET

Per configurare il progetto .NET per l'autenticazione con Azure.Identity, completare la procedura seguente:

  1. Includere il pacchetto Azure.DigitalTwins.Core SDK e il Azure.Identity pacchetto nel progetto. A seconda degli strumenti scelti, è possibile includere i pacchetti usando Gestione pacchetti di Visual Studio o lo dotnet strumento da riga di comando.

  2. Aggiungere le istruzioni using seguenti al codice del progetto:

    using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;

Aggiungere quindi il codice per ottenere le credenziali usando uno dei metodi in Azure.Identity. Nelle sezioni seguenti vengono fornite informazioni più dettagliate sull'uso di ognuno di essi.

DefaultAzureCredential, metodo

DefaultAzureCredential fornisce un flusso di autenticazione predefinito TokenCredential per le applicazioni che verranno distribuite in Azure ed è la scelta consigliata per lo sviluppo locale.

Per usare le credenziali di Azure predefinite, è necessario l'URL dell'istanza di Gemelli digitali di Azure (istruzioni per trovare).

Ecco un esempio di codice per aggiungere un oggetto DefaultAzureCredential al progetto:

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Nota

Attualmente è presente un problema noto che interessa la DefaultAzureCredential classe wrapper che può causare un errore durante l'autenticazione. Se si verifica questo problema, è possibile provare a creare DefaultAzureCredential un'istanza con il parametro facoltativo seguente per risolverlo: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Per altre informazioni su questo problema, vedere Problemi noti di Gemelli digitali di Azure.

Configurare le credenziali di Azure locali

Con DefaultAzureCredential, l'esempio cercherà le credenziali nell'ambiente locale, ad esempio un account di accesso di Azure nell'interfaccia della riga di comando di Azure locale o in Visual Studio o Visual Studio Code. Per questo motivo è necessario accedere ad Azure in locale tramite uno di questi meccanismi per configurare le credenziali per l'esempio.

Se si usa Visual Studio o Visual Studio Code per eseguire esempi di codice, assicurarsi di aver eseguito l'accesso a tale editor con le stesse credenziali di Azure da usare per accedere all'istanza di Gemelli digitali di Azure. Se si usa una finestra dell'interfaccia della riga di comando locale, eseguire il az login comando per accedere all'account Azure. In seguito, quando si esegue l'esempio di codice, si dovrebbe essere autenticati automaticamente.

ManagedIdentityCredential, metodo

Il metodo ManagedIdentityCredential funziona correttamente nei casi in cui sono necessarie identità gestite, ad esempio durante l'autenticazione con Funzioni di Azure.

Ciò significa che è possibile usare ManagedIdentityCredential nello stesso progetto di DefaultAzureCredential o InteractiveBrowserCredentialper autenticare una parte diversa del progetto.

Per usare le credenziali di Azure predefinite, è necessario l'URL dell'istanza di Gemelli digitali di Azure (istruzioni per trovare). Potrebbe essere necessaria anche una registrazione dell'app e l'ID applicazione (client) della registrazione.

In una funzione di Azure è possibile usare le credenziali di identità gestite come segue:

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Durante la creazione delle credenziali, lasciando vuoto il parametro come illustrato in precedenza restituirà le credenziali per l'identità assegnata dal sistema dell'app per le funzioni, se presente. Per specificare invece un'identità assegnata dall'utente, passare l'ID client dell'identità assegnata dall'utente al parametro .

InteractiveBrowserCredential, metodo

Il metodo InteractiveBrowserCredential è destinato ad applicazioni interattive e visualizzerà un Web browser per l'autenticazione. È possibile usare questo metodo anziché DefaultAzureCredential nei casi in cui è necessaria l'autenticazione interattiva.

Per usare le credenziali interattive del browser, è necessaria una registrazione dell'app con autorizzazioni per le API di Gemelli digitali di Azure. Per informazioni su come configurare la registrazione di questa app, vedere Creare una registrazione dell'app con l'accesso a Gemelli digitali di Azure. Dopo aver configurato la registrazione dell'app, è necessario...

Di seguito è riportato un esempio di codice per creare un client SDK autenticato usando InteractiveBrowserCredential.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Nota

Anche se è possibile inserire l'ID client, l'ID tenant e l'URL dell'istanza direttamente nel codice, come illustrato in precedenza, è consigliabile che il codice ottenga questi valori da un file di configurazione o da una variabile di ambiente.

Autenticare Funzioni di Azure

Questa sezione contiene alcune delle opzioni di configurazione importanti nel contesto dell'autenticazione con Funzioni di Azure. Prima di tutto, si leggeranno le variabili a livello di classe consigliate e il codice di autenticazione che consentirà alla funzione di accedere a Gemelli digitali di Azure. Verranno quindi letti alcuni passaggi di configurazione finali da completare per la funzione dopo la pubblicazione del codice in Azure.

Scrivere il codice dell'applicazione

Quando si scrive la funzione di Azure, è consigliabile aggiungere queste variabili e codice alla funzione:

  • Codice per leggere l'URL del servizio Gemelli digitali di Azure come variabile di ambiente o impostazione di configurazione. È consigliabile leggere l'URL del servizio da una variabile di ambiente o impostazione dell'applicazione, anziché impostarlo come hardcoded nella funzione. In una funzione di Azure il codice per leggere la variabile di ambiente potrebbe essere simile al seguente:

    private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");

    Successivamente, dopo la pubblicazione della funzione, si creerà e si imposta il valore della variabile di ambiente per questo codice da leggere. Per istruzioni su come eseguire questa operazione, passare a Configurare le impostazioni dell'applicazione.

  • Variabile statica per contenere un'istanza HttpClient. HttpClient è relativamente costoso da creare, quindi probabilmente si vuole crearlo una volta con il codice di autenticazione per evitare di crearlo per ogni chiamata di funzione.

    private static readonly HttpClient singletonHttpClientInstance = new HttpClient();

  • Credenziali dell'identità gestita. Creare una credenziale di identità gestita che verrà usata dalla funzione per accedere a Gemelli digitali di Azure.

    // To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");

    Se il parametro è vuoto, come illustrato in precedenza, restituirà le credenziali per l'identità assegnata dal sistema dell'app per le funzioni, se presente. Per specificare invece un'identità assegnata dall'utente, passare l'ID client dell'identità assegnata dall'utente al parametro .

    Successivamente, dopo la pubblicazione della funzione, si verificherà che l'identità della funzione abbia l'autorizzazione per accedere alle API di Gemelli digitali di Azure. Per istruzioni su come eseguire questa operazione, passare a Assegnare un ruolo di accesso.

  • Variabile locale DigitalTwinsClient. Aggiungere la variabile all'interno della funzione per contenere l'istanza client di Gemelli digitali di Azure. Non rendere questa variabile statica all'interno della classe.

    var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });

  • Controllo Null per adtInstanceUrl. Aggiungere il controllo Null e quindi eseguire il wrapping della logica della funzione in un blocco try/catch per rilevare eventuali eccezioni.

Dopo l'aggiunta di queste variabili a una funzione, il codice della funzione potrebbe essere simile all'esempio seguente.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

Al termine del codice della funzione, inclusa l'aggiunta dell'autenticazione e della logica della funzione, pubblicare l'app in Azure

Configurare l'app pubblicata

Completare infine i passaggi di configurazione seguenti per una funzione di Azure pubblicata per assicurarsi che possa accedere all'istanza di Gemelli digitali di Azure.

Eseguire i comandi seguenti in Azure Cloud Shell o in un'interfaccia della riga di comando di Azure locale.

Nota

Questa sezione deve essere completata da un utente di Azure che dispone delle autorizzazioni per gestire l'accesso utente alle risorse di Azure, inclusa la concessione e la delega delle autorizzazioni. I ruoli comuni che soddisfano questo requisito sono Proprietario, Amministratore account o combinazione di Accesso utenti Amministrazione istrator e Collaboratore. Per altre informazioni sui requisiti di autorizzazione per i ruoli di Gemelli digitali di Azure, vedere Configurare un'istanza e l'autenticazione.

Assegnare un ruolo di accesso

La funzione di Azure richiede il passaggio di un token di connessione. Per assicurarsi che il token di connessione venga passato, concedere all'app per le funzioni il ruolo Proprietario dati di Gemelli digitali di Azure per l'istanza di Gemelli digitali di Azure, che consentirà all'app per le funzioni di eseguire attività del piano dati nell'istanza.

  1. Usare il comando seguente per creare un'identità gestita dal sistema per la funzione ( se la funzione ne ha già una, questo comando ne stamperà i dettagli). Prendere nota del principalId campo nell'output. Questo ID verrà usato per fare riferimento alla funzione in modo che sia possibile concedere le autorizzazioni nel passaggio successivo.

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. Usare il principalId valore nel comando seguente per assegnare alla funzione il ruolo Proprietario dati di Gemelli digitali di Azure per l'istanza di Gemelli digitali di Azure.

    az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Configurare le impostazioni dell'applicazione

Rendere quindi accessibile l'URL dell'istanza di Gemelli digitali di Azure alla funzione impostando una variabile di ambiente.

Suggerimento

L'URL dell'istanza di Gemelli digitali di Azure viene creato aggiungendo https:// all'inizio del nome host dell'istanza. Per visualizzare il nome host, insieme a tutte le proprietà dell'istanza, eseguire az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Il comando seguente imposta una variabile di ambiente per l'URL dell'istanza che verrà usata dalla funzione ogni volta che deve accedere all'istanza.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Eseguire l'autenticazione su più tenant

Gemelli digitali di Azure è un servizio che supporta un solo tenant di Microsoft Entra: il tenant principale della sottoscrizione in cui si trova l'istanza di Gemelli digitali di Azure.

Di conseguenza, le richieste alle API di Gemelli digitali di Azure richiedono un utente o un'entità servizio che fa parte dello stesso tenant in cui risiede l'istanza di Gemelli digitali di Azure. Per impedire l'analisi dannosa degli endpoint di Gemelli digitali di Azure, le richieste con token di accesso dall'esterno del tenant di origine verranno restituiti un messaggio di errore "404 Sub-Domain not found". Questo errore verrà restituito anche se all'utente o all'entità servizio è stato assegnato un ruolo di proprietario dei dati di Gemelli digitali di Azure o lettore dati di Gemelli digitali di Azure tramite Microsoft Entra B2B Collaboration.

Se è necessario accedere all'istanza di Gemelli digitali di Azure usando un'entità servizio o un account utente appartenente a un tenant diverso dall'istanza, è possibile avere ogni identità federata da un altro tenant richiedere un token dal tenant "home" dell'istanza di Gemelli digitali di Azure.

Un modo per eseguire questa operazione consiste nel comando dell'interfaccia della riga di comando seguente, dove <home-tenant-ID> è l'ID del tenant di Microsoft Entra che contiene l'istanza di Gemelli digitali di Azure:

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

Dopo la richiesta, l'identità riceverà un token rilasciato per la https://digitaltwins.azure.net risorsa Microsoft Entra, che ha un'attestazione ID tenant corrispondente all'istanza di Gemelli digitali di Azure. L'uso di questo token nelle richieste API o con il Azure.Identity codice deve consentire all'identità federata di accedere alla risorsa di Gemelli digitali di Azure.

È anche possibile specificare il tenant principale nelle opzioni delle credenziali nel codice.

L'esempio seguente illustra come impostare un valore di ID tenant di esempio per InteractiveBrowserTenantId nelle DefaultAzureCredential opzioni:

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Sono disponibili opzioni simili per impostare un tenant per l'autenticazione con Visual Studio e Visual Studio Code. Per altre informazioni sulle opzioni disponibili, vedere la documentazione di DefaultAzureCredentialOptions.

Altri metodi di credenziale

Se gli scenari di autenticazione evidenziati sopra non coprono le esigenze dell'app, è possibile esplorare altri tipi di autenticazione offerti in Microsoft Identity Platform. La documentazione per questa piattaforma illustra più scenari di autenticazione, organizzati per tipo di applicazione.

Passaggi successivi

Altre informazioni sul funzionamento della sicurezza in Gemelli digitali di Azure:

In alternativa, ora che l'autenticazione è configurata, passare alla creazione e alla gestione dei modelli nell'istanza: