Libreria client di autenticazione dell'app per .NET - versione 1.6.0

Nota

Microsoft.Azure.Services.AppAuthentication è stato ritirato e non è più supportato o gestito. Viene sostituito dalla libreria client di Identità di Azure disponibile per .NET, Java, TypeScript e Python. Per informazioni su come eseguire la migrazione, Azure Identityvedere AppAuthentication to Azure.Identity Migration Guidance (Guida alla migrazione di AppAuthentication ad Azure.Identity Migration Guidance).

Per eseguire l'autenticazione ai servizi di Azure con un'entità servizio, sono necessarie credenziali di Azure Active Directory (Azure AD), un segreto condiviso o un certificato.

La gestione di tali credenziali può essere difficile. È allettante aggregare le credenziali in un'app includendole nei file di origine o di configurazione. Microsoft.Azure.Services.AppAuthentication per la libreria .NET semplifica questo aspetto. Usa le credenziali per lo sviluppatore per eseguire l'autenticazione durante lo sviluppo locale. Quando in un secondo momento la soluzione viene distribuita in Azure, la libreria passa automaticamente alle credenziali dell'applicazione. L'uso delle credenziali per sviluppatori durante lo sviluppo locale è più sicuro perché non è necessario creare credenziali di Azure AD o condividere le credenziali tra gli sviluppatori.

La Microsoft.Azure.Services.AppAuthentication libreria gestisce automaticamente l'autenticazione, che a sua volta consente di concentrarsi sulla soluzione anziché sulle credenziali. Supporta lo sviluppo locale con Microsoft Visual Studio, l'interfaccia della riga di comando di Azure o l'autenticazione integrata di Azure AD. Quando viene distribuita in una risorsa di Azure che supporta un'identità gestita, la libreria usa automaticamente le identità gestite per le risorse di Azure. Non sono necessarie modifiche di codice o di configurazione. La libreria supporta anche l'uso diretto delle credenziali client di Azure AD quando un'identità gestita non è disponibile o quando il contesto di sicurezza dello sviluppatore non può essere determinato durante lo sviluppo locale.

Codice | sorgente Pacchetto (nuget) | Documentazione di Azure Active Directory

Prerequisiti

  • Visual Studio 2019 o Visual Studio 2017 v15.5.

  • L'estensione Autenticazione app per Visual Studio, disponibile come estensione separata per Visual Studio 2017 Update 5 e in bundle con il prodotto in Update 6 e versioni successive. Con l'aggiornamento 6 o versione successiva, è possibile verificare l'installazione dell'estensione Autenticazione app selezionando Strumenti di sviluppo di Azure dal programma di installazione di Visual Studio.

Utilizzo della libreria

Per le applicazioni .NET, il modo più semplice per usare l'identità del servizio gestito è tramite il pacchetto Microsoft.Azure.Services.AppAuthentication. Ecco come iniziare:

  1. Selezionare Strumenti> Gestionepacchetti NuGet Gestisci pacchetti NuGet per la soluzione per aggiungere riferimenti ai pacchetti NuGet Microsoft.Azure.Services.AppAuthentication e Microsoft.Azure.KeyVault nuGet al progetto.>

  2. Usare AzureServiceTokenProvider per semplificare la richiesta di token di accesso per i client di Azure, come gli esempi seguenti:

    using Microsoft.Azure.Services.AppAuthentication;
    using Microsoft.Azure.KeyVault;
    using System.Data.SqlClient
    
    // Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
    var azureServiceTokenProvider = new AzureServiceTokenProvider();
    var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));
    
    // Request an access token for SqlConnection
    sqlConnection = new SqlConnection(YourConnectionString)) 
    { 
        sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
        sqlConnection.Open(); 
    } 
    

La classe thread-safe AzureServiceTokenProvider memorizza nella cache il token in memoria e lo recupera da Azure AD appena prima della scadenza. Ciò significa che non è mai necessario controllare la scadenza del token prima di chiamare il GetAccessTokenAsync metodo .

Il metodo GetAccessTokenAsync richiede un identificatore di risorsa. Per altre informazioni sui servizi di Microsoft Azure, vedere Informazioni sulle identità gestite per le risorse di Azure.

Autenticazione per lo sviluppo locale

Per lo sviluppo locale, esistono due scenari di autenticazione principali: l'autenticazione ai servizi di Azure e l'autenticazione ai servizi personalizzati.

Autenticazione ai servizi di Azure

I computer locali non supportano le identità gestite per le risorse di Azure. Di conseguenza, la libreria Microsoft.Azure.Services.AppAuthentication usa le credenziali per lo sviluppatore per l'esecuzione nell'ambiente di sviluppo locale. Quando la soluzione viene distribuita in Azure, la libreria usa l'autenticazione del servizio gestito per passare a un flusso di concessione delle credenziali client di OAuth 2.0. Questo approccio significa che è possibile testare lo stesso codice in locale e in remoto senza doversi preoccupare.

Per lo sviluppo locale, AzureServiceTokenProvider recupera i token usando Visual Studio, l'interfaccia della riga di comando di Azure o l'autenticazione integrata di Azure AD. Ogni opzione viene provata in sequenza e la libreria usa la prima opzione con esito positivo. Se nessuna opzione funziona, viene generata un'eccezione AzureServiceTokenProviderException con informazioni dettagliate.

Autenticazione con Visual Studio

Per eseguire l'autenticazione tramite Visual Studio:

  1. Accedere a Visual Studio e usareLe opzionidegli strumenti> per aprire Opzioni.

  2. Selezionare Autenticazione del servizio di Azure, scegliere un account per lo sviluppo locale e selezionare OK.

Se si verificano problemi con Visual Studio, ad esempio errori che coinvolgono il file del provider di token, esaminare attentamente i passaggi precedenti.

Potrebbe essere necessario autenticare nuovamente il token per sviluppatore. A tale scopo, selezionare Opzioni strumenti> e quindi selezionare Autenticazione del servizio di Azure. Cercare un collegamento Per ripetere l'autenticazione nell'account selezionato. Selezionare il collegamento per eseguire l'autenticazione.

Autenticazione con l'interfaccia della riga di comando di Azure

Per usare l'interfaccia della riga di comando di Azure per lo sviluppo locale, assicurarsi di avere la versione dell'interfaccia della riga di comando di Azure versione 2.0.12 o successiva.

Per usare l'interfaccia della riga di comando di Azure:

  1. Cercare l'interfaccia della riga di comando di Azure nella barra delle applicazioni di Windows per aprire il prompt dei comandi di Microsoft Azure.

  2. Accedere al portale di Azure: az login per accedere ad Azure.

  3. Verificare l'accesso immettendo az account get-access-token --resource https://vault.azure.net. Se viene visualizzato un errore, verificare che la versione corretta dell'interfaccia della riga di comando di Azure sia installata correttamente.

    Se l'interfaccia della riga di comando di Azure non è installata nella directory predefinita, potrebbe essere visualizzato un messaggio di errore che AzureServiceTokenProvider non riesce a trovare il percorso per l'interfaccia della riga di comando di Azure. Usare la variabile di ambiente AzureCLIPath per definire la cartella di installazione dell'interfaccia della riga di comando di Azure. AzureServiceTokenProvider aggiunge la directory specificata nella variabile di ambiente AzureCLIPath alla variabile di ambiente Path, quando è necessario.

  4. Se si è connessi all'interfaccia della riga di comando di Azure usando più account o l'account ha accesso a più sottoscrizioni, è necessario specificare la sottoscrizione da usare. Immettere il comando az account set --subscription .

Questo comando genera l'output solo in caso di errore. Per verificare le impostazioni dell'account corrente, immettere il comando az account list.

Autenticazione con l'autenticazione di Azure AD

Per usare l'autenticazione di Azure AD, verificare che:

Autenticazione ai servizi personalizzati

Quando un servizio chiama i servizi Azure, i passaggi precedenti funzionano perché i servizi Azure consentono l'accesso a utenti e ad applicazioni.

Quando si crea un servizio che chiama un servizio personalizzato, usare le credenziali client di Azure AD per l'autenticazione per lo sviluppo locale. Sono disponibili due opzioni:

  • Usare un'entità servizio per accedere ad Azure:

    1. Creare un'entità servizio. Per altre informazioni, vedere Creare un'entità servizio di Azure con l'interfaccia della riga di comando di Azure.

    2. Usare l'interfaccia della riga di comando di Azure per accedere con il comando seguente:

      az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
      

      Poiché l'entità servizio potrebbe non avere accesso a una sottoscrizione, usare l'argomento --allow-no-subscriptions.

  • Usare le variabili di ambiente per specificare i dettagli dell'entità servizio. Per altre informazioni, vedere Esecuzione dell'applicazione tramite un'entità servizio.

Dopo aver eseguito l'accesso ad Azure, AzureServiceTokenProvider usa l'entità servizio per recuperare un token per lo sviluppo locale.

Questo approccio si applica solo allo sviluppo locale. Quando la soluzione viene distribuita in Azure, la libreria passa all'identità gestita per l'autenticazione.

Esecuzione dell'applicazione tramite identità gestita o identità assegnata dall'utente

Quando si esegue il codice in un Servizio app di Azure o in una macchina virtuale di Azure con l'identità gestita abilitata, la libreria usa automaticamente l'identità gestita. Non sono necessarie modifiche al codice, ma l'identità gestita deve disporre delle autorizzazioni per le risorse a cui tenterà di accedere. Ad esempio, i criteri di accesso sono necessari per un'identità gestita per accedere a tutti i segreti in un insieme di credenziali delle chiavi.

In alternativa, è possibile eseguire l'autenticazione con un'identità assegnata dall'utente. Per altre informazioni sulle identità assegnate dall'utente, vedere Informazioni sulle identità gestite per le risorse di Azure. Per eseguire l'autenticazione con un'identità assegnata dall'utente, è necessario specificare l'ID client dell'identità assegnata dall'utente nella stringa di connessione. La stringa di connessione viene specificata in Supporto stringhe di connessione.

Esecuzione dell'applicazione con un'entità servizio

Potrebbe essere necessario creare una credenziale client di Azure Active Directory per eseguire l'autenticazione. Questa situazione può verificarsi negli esempi seguenti:

  • Il codice viene eseguito in un ambiente di sviluppo locale, ma non con l'identità dello sviluppatore. Service Fabric, ad esempio, usa l'account NetworkService per lo sviluppo locale.

  • Il codice viene eseguito in un ambiente di sviluppo locale e si esegue l'autenticazione a un servizio personalizzato; non è possibile usare l'identità dello sviluppatore.

  • Il codice è in esecuzione in una risorsa di calcolo di Azure che non supporta ancora le identità gestite per le risorse di Azure, ad esempio Azure Batch.

Esistono tre metodi primari di uso di un'entità servizio per eseguire l'applicazione. Per usarli, è prima necessario creare un'entità servizio. Per altre informazioni, vedere Creare un'entità servizio di Azure con l'interfaccia della riga di comando di Azure.

Usare un certificato nell'archivio chiavi locale per accedere ad Azure AD

  1. Creare un certificato dell'entità servizio usando il comando az ad sp create-for-rbac dell'interfaccia della riga di comando di Azure.

    az ad sp create-for-rbac --create-cert
    

    Questo comando crea un file pem (chiave privata) archiviato nella home directory. Convertire il file con estensione pem in un certificato PFX usando il comando:

    openssl pkcs12 -export -in test.pem -out test.pfx
    
  2. Impostare una variabile di ambiente denominata AzureServicesAuthConnectionString sul valore seguente:

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
          CertificateStoreLocation={CertificateStore}
    

    Sostituire {AppId}, {TenantId} e {Thumbprint} con i valori generati nel passaggio 1. Sostituire {CertificateStore} con LocalMachine' o CurrentUser, in base al piano di distribuzione.

  3. Eseguire l'applicazione.

Usare una credenziale privata condivisa per accedere ad Azure AD

  1. Creare un certificato dell'entità servizio con una password usando l'interfaccia della riga di comando di Azure az ad sp create-for-rbac con il parametro --sdk-auth.

    az ad sp create-for-rbac --sdk-auth
    
  2. Impostare una variabile di ambiente denominata AzureServicesAuthConnectionString sul valore seguente:

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
    

    Sostituire {AppId}, {TenantId} e {ClientSecret} con i valori generati nel passaggio 1.

  3. Eseguire l'applicazione.

Dopo avere eseguito tutte le impostazioni non è necessario eseguire modificare il codice. AzureServiceTokenProvider usa la variabile di ambiente e il certificato per eseguire l'autenticazione ad Azure AD.

Usare un certificato in Key Vault per accedere ad Azure AD

Questa opzione consente di archiviare il certificato client dell'entità servizio in Key Vault e usarlo per l'autenticazione dell'entità servizio. È possibile usare questa opzione per gli scenari seguenti:

  • Autenticazione locale, in cui si vuole eseguire l'autenticazione usando un'entità servizio esplicita e si vuole mantenere le credenziali dell'entità servizio in modo sicuro in un insieme di credenziali delle chiavi. L'account sviluppatore deve avere accesso all'insieme di credenziali delle chiavi.

  • Autenticazione da Azure in cui si desidera usare credenziali esplicite e si vuole mantenere le credenziali dell'entità servizio in modo sicuro in un insieme di credenziali delle chiavi. È possibile usare questa opzione per uno scenario multi-tenant. L'identità gestita deve avere accesso all'insieme di credenziali delle chiavi.

L'identità gestita o l'identità dello sviluppatore devono avere l'autorizzazione per recuperare il certificato client dalla Key Vault. La libreria AppAuthentication usa il certificato recuperato come credenziale client dell'entità servizio.

Per usare un certificato client per l'autenticazione dell'entità servizio:

  1. Creare un certificato dell'entità servizio e archiviarlo automaticamente nel Key Vault. Usare l'interfaccia della riga di comando di Azure az ad sp create-for-rbac --keyvault <keyvaultname --cert certificatename>> --create-cert <--skip-assignment:

    az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
    

    L'identificatore del certificato sarà un URL nel formato https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

  2. Sostituire {KeyVaultCertificateSecretIdentifier} in questa stringa di connessione con l'identificatore del certificato:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
    

    Ad esempio, se l'insieme di credenziali delle chiavi è stato chiamato myKeyVault e è stato creato un certificato denominato myCert, l'identificatore del certificato sarà:

    RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
    

Opzioni supportate per la stringa di connessione

Per impostazione predefinita, AzureServiceTokenProvider prova i metodi di autenticazione seguenti per recuperare un token:

Per controllare il processo, usare una stringa di connessione passata al costruttore AzureServiceTokenProvider o specificata nella variabile di ambiente AzureServicesAuthConnectionString. Sono supportate le opzioni seguenti:

Opzione Stringa di connessione Scenario Commenti
RunAs=Developer;DeveloperTool=AzureCli Sviluppo locale AzureServiceTokenProvider usa AzureCli per ottenere il token.
RunAs=Developer;DeveloperTool=VisualStudio Sviluppo locale AzureServiceTokenProvider usa Visual Studio per ottenere il token.
RunAs=CurrentUser Sviluppo locale Non supportato in .NET Core. AzureServiceTokenProvider usa l'autenticazione integrata di Azure AD per ottenere il token.
RunAs=App Identità gestite per le risorse di Azure AzureServiceTokenProvider usa un'identità gestita per ottenere il token.
RunAs=App;AppId={ClientId of user-assigned identity} Identità assegnata dall'utente per le risorse di Azure AzureServiceTokenProvider usa un'identità assegnata dall'utente per ottenere il token.
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier} Autenticazione dei servizi personalizzati KeyVaultCertificateSecretIdentifier è l'identificatore segreto del certificato.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} Entità servizio AzureServiceTokenProvider usa il certificato per ottenere il token da Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} Entità servizio AzureServiceTokenProvider usa il certificato per ottenere il token da Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} Entità servizio AzureServiceTokenProvider usa il segreto per ottenere il token da Azure AD.

Esempi

Per visualizzare la Microsoft.Azure.Services.AppAuthentication libreria in azione, vedere gli esempi di codice seguenti.

Risoluzione dei problemi di AppAuthentication

Problemi comuni durante lo sviluppo locale

L'interfaccia della riga di comando di Azure non è installata, non si è connessi o non si ha la versione più recente

Eseguire az account get-access-token per verificare se l'interfaccia della riga di comando di Azure mostra un token per l'utente. Se non viene trovato alcun programma di questo tipo, installare la versione più recente dell'interfaccia della riga di comando di Azure. Potrebbe essere necessario effettuare l'accesso.

AzureServiceTokenProvider non riesce a trovare il percorso per l'interfaccia della riga di comando di Azure

AzureServiceTokenProvider cerca l'interfaccia della riga di comando di Azure nei percorsi di installazione predefiniti. Se non è possibile trovare l'interfaccia della riga di comando di Azure, impostare la variabile di ambiente AzureCLIPath sulla cartella di installazione dell'interfaccia della riga di comando di Azure. AzureServiceTokenProvider aggiungerà la variabile di ambiente alla variabile di ambiente Path.

Si è connessi all'interfaccia della riga di comando di Azure usando più account, lo stesso account ha accesso alle sottoscrizioni in più tenant o si riceve un errore di accesso negato quando si tenta di effettuare chiamate durante lo sviluppo locale

Usando l'interfaccia della riga di comando di Azure, impostare la sottoscrizione predefinita su un account che si vuole usare. La sottoscrizione deve trovarsi nello stesso tenant della risorsa a cui si vuole accedere: az account set --subscription [subscription-id]. Se non viene visualizzato alcun output, ha avuto esito positivo. Verificare che l'account corretto sia ora l'impostazione predefinita usando az account list.

Problemi comuni tra ambienti

Accesso non autorizzato, negato, non consentito o errore simile

L'entità di sicurezza usata non ha accesso alla risorsa a cui sta tentando di accedere. Concedere all'account utente o all'accesso "Collaboratore" del servizio gestito del servizio app a una risorsa. Ciò dipende dal fatto che l'esempio sia in esecuzione nel computer locale o distribuito in Azure nel servizio app. Alcune risorse, ad esempio gli insiemi di credenziali delle chiavi, dispongono anche dei propri criteri di accesso usati per concedere l'accesso alle entità, ad esempio utenti, app e gruppi.

Problemi comuni durante la distribuzione in Servizio app di Azure

L'identità gestita non è configurata nella servizio app

Controllare le variabili di ambiente MSI_ENDPOINT e MSI_SECRET esistere usando la console di debug Kudu. Se queste variabili di ambiente non esistono, l'identità gestita non è abilitata nella servizio app.

Problemi comuni quando sono stati distribuiti localmente con IIS

Impossibile recuperare i token durante il debug dell'app in IIS

Per impostazione predefinita, AppAuth viene eseguito in un contesto utente diverso in IIS. Questo è il motivo per cui non ha accesso all'uso dell'identità dello sviluppatore per recuperare i token di accesso. È possibile configurare IIS per l'esecuzione con il contesto utente con i due passaggi seguenti:

  • Configurare il pool di applicazioni per l'app Web da eseguire come account utente corrente. Ulteriori informazioni sono disponibili qui.

  • Configurare "setProfileEnvironment" su "True". Vedere altre informazioni qui.

    • Passare a %windir%\System32\inetsrv\config\applicationHost.config
    • Cercare "setProfileEnvironment". Se è impostato su "False", modificarlo su "True". Se non è presente, aggiungerlo come attributo all'elemento processModel (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) e impostarlo su "True".
  • Altre informazioni sulle identità gestite per le risorse di Azure.

  • Altre informazioni sugli scenari di autenticazione di Azure AD.