Usare l'insieme di credenziali chiave di Azure da un'applicazione WebUse Azure Key Vault from a Web Application

IntroduzioneIntroduction

In questa esercitazione si apprenderà a usare l'insieme di credenziali chiave di Azure da un'applicazione Web in Azure.Use this tutorial to help you learn how to use Azure Key Vault from a web application in Azure. Viene illustrato il processo di accesso a un segreto da un insieme di credenziali chiave di Azure, in modo da poterlo usare nell'applicazione Web.It walks you through the process of accessing a secret from an Azure Key Vault so that it can be used in your web application.

Tempo previsto per il completamento: 15 minutiEstimated time to complete: 15 minutes

Per informazioni generali sull'insieme di credenziali di Azure, vedere Cos'è l'insieme di credenziali chiave di Azure?For overview information about Azure Key Vault, see What is Azure Key Vault?

PrerequisitiPrerequisites

Per completare l'esercitazione, sono necessari gli elementi seguenti:To complete this tutorial, you must have the following:

  • Un URI di un segreto in un insieme di credenziali chiave di Azure.A URI to a secret in an Azure Key Vault
  • Un ID client e un segreto client per un'applicazione Web registrata con Azure Active Directory che abbia accesso all'insieme di credenziali chiave.A Client ID and a Client Secret for a web application registered with Azure Active Directory that has access to your Key Vault
  • Un'applicazione Web.A web application. Verranno mostrati i passaggi per un'applicazione ASP.NET MVC distribuita in Azure come app Web.We will be showing the steps for an ASP.NET MVC application deployed in Azure as a Web App.

Importante

  • Questo esempio dipende da una modalità meno recente di eseguire il provisioning manuale delle identità AAD.This sample depends on an older way of manually provisioning AAD Identities. Attualmente esiste una nuova funzionalità in anteprima, denominata Managed Service Identity (MSI), che consente di eseguire automaticamente il provisioning di identità AAD.Currently, there is a new feature in preview called Managed Service Identity (MSI), which can automatically provision AAD Identities. Per altri dettagli, fare riferimento al seguente esempio suGitHub.Please refer to the following sample on github for further details.

Nota

  • Per questa esercitazione è essenziale aver completato i passaggi elencati in Introduzione all'insieme di credenziali chiave di Azure in modo da disporre dell'URI di un segreto e dell'ID client e del segreto client per un'applicazione Web.It is essential that you have completed the steps listed in Get Started with Azure Key Vault for this tutorial so that you have the URI to a secret and the Client ID and Client Secret for a web application.

L'applicazione Web che accederà all'insieme di credenziali chiave è quella registrata in Azure Active Directory e a cui è stato concesso l'accesso all'insieme di credenziali chiave.The web application that will be accessing the Key Vault is the one that is registered in Azure Active Directory and has been given access to your Key Vault. Se non è così, tornare a Registrare un'applicazione nell'esercitazione introduttiva e ripetere i passaggi elencati.If this is not the case, go back to Register an Application in the Get Started tutorial and repeat the steps listed.

Questa esercitazione è destinata agli sviluppatori Web che conoscono le nozioni di base della creazione di applicazioni Web in Azure.This tutorial is designed for web developers that understand the basics of creating web applications on Azure. Per altre informazioni sulle app Web di Azure, vedere Panoramica delle app Web.For more information about Azure Web Apps, see Web Apps overview.

Aggiungere i pacchetti NuGetAdd Nuget Packages

Sono due i pacchetti che devono essere installati nell'applicazione Web.There are two packages that your web application needs to have installed.

  • Active Directory Authentication Library: contiene i metodi per interagire con Azure Active Directory e gestire l'identità utenteActive Directory Authentication Library - contains methods for interacting with Azure Active Directory and managing user identity
  • Azure Key Vault Library: contiene i metodi per interagire con l'insieme di credenziali chiave di AzureAzure Key Vault Library - contains methods for interacting with Azure Key Vault

È possibile installare entrambi i pacchetti con la Console di Gestione pacchetti usando il comando Install-Package.Both of these packages can be installed using the Package Manager Console using the Install-Package command.

// this is currently the latest stable version of ADAL
Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory -Version 2.16.204221202
Install-Package Microsoft.Azure.KeyVault

Modificare Web.ConfigModify Web.Config

Sono tre le impostazioni che devono essere aggiunte al file web.config, come indicato di seguito.There are three application settings that need to be added to the web.config file as follows.

    <!-- ClientId and ClientSecret refer to the web application registration with Azure Active Directory -->
    <add key="ClientId" value="clientid" />
    <add key="ClientSecret" value="clientsecret" />

    <!-- SecretUri is the URI for the secret in Azure Key Vault -->
    <add key="SecretUri" value="secreturi" />

Se non si ospiterà l'applicazione come app Web di Azure, è consigliabile aggiungere i valori effettivi di ID client, segreto client e URI segreto a web.config. In caso contrario, lasciare questi valori fittizi perché i valori effettivi verranno aggiunti nel portale di Azure per un ulteriore livello di sicurezza.If you are not going to host your application as an Azure Web App, then you should add the actual ClientId, Client Secret, and Secret URI values to the web.config. Otherwise leave these dummy values because we will be adding the actual values in the Azure portal for an additional level of security.

Aggiungere il metodo per ottenere un token di accessoAdd Method to Get an Access Token

Per usare l'API dell'insieme di credenziali chiave, è necessario un token di accesso.In order to use the Key Vault API you need an access token. Il client dell'insieme di credenziali chiave gestisce le chiamate all'API dell'insieme di credenziali chiave, ma è necessario fornirgli una funzione che ottenga il token di accesso.The Key Vault Client handles calls to the Key Vault API but you need to supply it with a function that gets the access token.

Di seguito è riportato il codice per ottenere un accesso token da Azure Active Directory.Following is the code to get an access token from Azure Active Directory. Questo codice può far accedere ovunque nell'applicazione.This code can go anywhere in your application. È possibile aggiungere una classe Utils o EncryptionHelper.I like to add a Utils or EncryptionHelper class.

//add these using statements
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Threading.Tasks;
using System.Web.Configuration;

//this is an optional property to hold the secret after it is retrieved
public static string EncryptSecret { get; set; }

//the method that will be provided to the KeyVaultClient
public static async Task<string> GetToken(string authority, string resource, string scope)
{
    var authContext = new AuthenticationContext(authority);
    ClientCredential clientCred = new ClientCredential(WebConfigurationManager.AppSettings["ClientId"],
                WebConfigurationManager.AppSettings["ClientSecret"]);
    AuthenticationResult result = await authContext.AcquireTokenAsync(resource, clientCred);

    if (result == null)
        throw new InvalidOperationException("Failed to obtain the JWT token");

    return result.AccessToken;
}

Nota

  • Attualmente, la nuova funzionalità di identità del servizio gestito è il modo più semplice per l'autenticazione.Currently, the new feature Managed Service Identity (MSI) is the easiest way to authenticate. Per altre informazioni, visitare il collegamento seguente all'esempio che usa Key Vault con l'identità del servizio gestito in un'applicazione in .NET e la relativa esercitazione con l'identità del servizio gestito con il servizio app e le funzioni.For further details please see the following link to the sample using Key Vault with MSI in an application in .NET and related MSI with App Service and Functions tutorial.
  • L'uso di un ID client e di un segreto client è un altro modo per autenticare un'applicazione Azure AD.Using Client ID and Client Secret is another way to authenticate an Azure AD application. Utilizzarlo nell'applicazione Web consente una separazione dei compiti e maggiore controllo sulla gestione delle chiavi.And using it in your web application allows for a separation of duties and more control over your key management. Ma si basa sull'inserimento del client secret nelle impostazioni di configurazione, che per alcuni può essere rischioso quanto inserire la chiave privata che si desidera proteggere nelle impostazioni di configurazione.But it does rely on putting the Client Secret in your configuration settings, which for some can be as risky as putting the secret that you want to protect in your configuration settings. Per una discussione su come utilizzare un ID Client e un certificato anziché un ID Client e il client secret per autenticare l'applicazione di Azure AD, vedere di seguito.See the following for a discussion on how to use a Client ID and Certificate instead of Client ID and Client Secret to authenticate the Azure AD application.

Recuperare il segreto all'avvio dell'applicazioneRetrieve the secret on Application Start

A questo punto è necessario il codice per chiamare l'API dell'insieme di credenziali chiave e recuperare il segreto.Now we need code to call the Key Vault API and retrieve the secret. Purché venga chiamato prima che sia necessario usarlo, è possibile inserire il codice seguente in qualsiasi punto.The following code can be put anywhere as long as it is called before you need to use it. In questo caso, viene inserito nell'evento Application Start in Global.asax in modo che venga eseguito una volta all'avvio e renda il segreto disponibile per l'applicazione.I have put this code in the Application Start event in the Global.asax so that it runs once on start and makes the secret available for the application.

//add these using statements
using Microsoft.Azure.KeyVault;
using System.Web.Configuration;

// I put my GetToken method in a Utils class. Change for wherever you placed your method.
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(Utils.GetToken));
var sec = await kv.GetSecretAsync(WebConfigurationManager.AppSettings["SecretUri"]);

//I put a variable in a Utils class to hold the secret for general  application use.
Utils.EncryptSecret = sec.Value;

Aggiungere le impostazioni dell'app nel portale di Azure (facoltativo)Add App Settings in the Azure portal (optional)

Se si dispone di un'app Web di Azure, è ora possibile aggiungere i valori effettivi per AppSettings nel portale di Azure.If you have an Azure Web App, you can now add the actual values for the AppSettings in the Azure portal. In questo modo, i valori effettivi non saranno in web.config, ma saranno protetti tramite il portale in cui si dispone di funzionalità di controllo di accesso separate.By doing this, the actual values will not be in the web.config but protected via the Portal where you have separate access control capabilities. Questi valori verranno sostituiti per i valori immessi in web.config. Assicurarsi che i nomi siano uguali.These values will be substituted for the values that you entered in your web.config. Make sure that the names are the same.

Impostazioni dell'applicazione visualizzate nel portale di Azure

Autenticazione con un certificato anziché un client secretAuthenticate with a Certificate instead of a Client Secret

È possibile autenticare un'applicazione di Azure AD utilizzando un ID Client e un certificato anziché un ID Client e un client secret.Another way to authenticate an Azure AD application is by using a Client ID and a Certificate instead of a Client ID and Client Secret. Di seguito sono indicati i passaggi per utilizzare un certificato in un'applicazione Web di Azure:Following are the steps to use a Certificate in an Azure Web App:

  1. Ottenere o creare un certificatoGet or Create a Certificate
  2. Associare il certificato a un'applicazione di Azure ADAssociate the Certificate with an Azure AD application
  3. Aggiungere codice all'applicazione Web per utilizzare il certificatoAdd code to your Web App to use the Certificate
  4. Aggiungere un certificato a un'applicazione WebAdd a Certificate to your Web App

Ottenere o creare un certificatoGet or Create a Certificate

Per i nostri scopi rendiamo un certificato di prova.For our purposes, we will make a test certificate. Ecco un paio di comandi che è possibile utilizzare in un prompt dei comandi sviluppatore per creare un certificato.Here are a couple of commands that you can use in a Developer Command Prompt to create a certificate. Cambiare la directory in cui si vuole creare i file del certificato.Change directory to where you want the cert files created. Inoltre, per la data di inizio e di fine del certificato usare la data corrente più 1 anno.Also, for the beginning and ending date of the certificate, use the current date plus 1 year.

makecert -sv mykey.pvk -n "cn=KVWebApp" KVWebApp.cer -b 03/07/2017 -e 03/07/2018 -r
pvk2pfx -pvk mykey.pvk -spc KVWebApp.cer -pfx KVWebApp.pfx -po test123

Prendere nota della data finale e della password per il formato .pfx (in questo esempio: 31/07/2016 e test123).Make note of the end date and the password for the .pfx (in this example: 07/31/2016 and test123). Saranno necessarie più avanti.You will need them below.

Per ulteriori informazioni sulla creazione di un certificato di prova, vedere Procedura: creare il proprio certificato di provaFor more information on creating a test certificate, see How to: Create Your Own Test Certificate

Associare il certificato a un'applicazione di Azure ADAssociate the Certificate with an Azure AD application

Ora che si dispone di un certificato, è necessario associarlo a un'applicazione di Azure AD.Now that you have a certificate, you need to associate it with an Azure AD application. Attualmente il portale di Azure non supporta questo flusso di lavoro. Questa operazione può essere completata in PowerShell.Presently, the Azure portal does not support this workflow; this can be completed through PowerShell. Eseguire questi comandi per associare il certificato con l'applicazione Azure AD:Run the following commands to assoicate the certificate with the Azure AD application:

$x509 = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$x509.Import("C:\data\KVWebApp.cer")
$credValue = [System.Convert]::ToBase64String($x509.GetRawCertData())


$adapp = New-AzureRmADApplication -DisplayName "KVWebApp" -HomePage "http://kvwebapp" -IdentifierUris "http://kvwebapp" -CertValue $credValue -StartDate $x509.NotBefore -EndDate $x509.NotAfter


$sp = New-AzureRmADServicePrincipal -ApplicationId $adapp.ApplicationId


Set-AzureRmKeyVaultAccessPolicy -VaultName 'contosokv' -ServicePrincipalName "http://kvwebapp" -PermissionsToSecrets all -ResourceGroupName 'contosorg'

# get the thumbprint to use in your app settings
$x509.Thumbprint

Dopo avere eseguito questi comandi, è possibile visualizzare l'applicazione in Azure AD.After you have run these commands, you can see the application in Azure AD. Durante la ricerca assicurarsi di selezionare "Applicazioni di proprietà dell'azienda" anziché "Applicazioni usate dall'azienda" nella finestra di ricerca.When searching, ensure you select "Applications my company owns" instead of "Applications my company uses" in the search dialog.

Per ulteriori informazioni sugli oggetti dell'applicazione di Azure AD e sugli oggetti ServicePrincipal, vedere Oggetti applicazione e oggetti entità servizio.To learn more about Azure AD Application Objects and ServicePrincipal Objects, see Application Objects and Service Principal Objects.

Aggiungere codice all'applicazione Web per utilizzare il certificatoAdd code to your Web App to use the Certificate

Ora il codice verrà aggiunto all'applicazione Web per accedere al certificato e utilizzarlo per l'autenticazione.Now we will add code to your Web App to access the cert and use it for authentication.

Prima di tutto viene il codice per accedere al certificato.First there is code to access the cert.

public static class CertificateHelper
{
    public static X509Certificate2 FindCertificateByThumbprint(string findValue)
    {
        X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
        try
        {
            store.Open(OpenFlags.ReadOnly);
            X509Certificate2Collection col = store.Certificates.Find(X509FindType.FindByThumbprint,
                findValue, false); // Don't validate certs, since the test root isn't installed.
            if (col == null || col.Count == 0)
                return null;
            return col[0];
        }
        finally
        {
            store.Close();
        }
    }
}

Si noti che StoreLocation è CurrentUser anziché LocalMachine.Note that the StoreLocation is CurrentUser instead of LocalMachine. Si sta specificando 'false' per il metodo Find, poiché si sta utilizzando un certificato di prova.And that we are supplying 'false' to the Find method because we are using a test cert.

Poi viene il codice che utilizza il CertificateHelper e crea un ClientAssertionCertificate necessario per l'autenticazione.Next is code that uses the CertificateHelper and creates a ClientAssertionCertificate which is needed for authentication.

public static ClientAssertionCertificate AssertionCert { get; set; }

public static void GetCert()
{
    var clientAssertionCertPfx = CertificateHelper.FindCertificateByThumbprint(WebConfigurationManager.AppSettings["thumbprint"]);
    AssertionCert = new ClientAssertionCertificate(WebConfigurationManager.AppSettings["clientid"], clientAssertionCertPfx);
}

Questo è il nuovo codice per ottenere il token di accesso.Here is the new code to get the access token. Sostituisce il metodo GetToken nell'esempio precedente.This replaces the GetToken method in the preceding example. È stato indicato un nome diverso per comodità.I have given it a different name for convenience.

public static async Task<string> GetAccessToken(string authority, string resource, string scope)
{
    var context = new AuthenticationContext(authority, TokenCache.DefaultShared);
    var result = await context.AcquireTokenAsync(resource, AssertionCert);
    return result.AccessToken;
}

È stato inserito tutto il codice nella classe Utils del progetto Web App per semplificarne l'utilizzo.I have put all of this code into my Web App project's Utils class for ease of use.

L'ultima modifica del codice è nel metodo Application_Start.The last code change is in the Application_Start method. Innanzitutto è necessario richiamare il metodo GetCert() per caricare il ClientAssertionCertificate.First we need to call the GetCert() method to load the ClientAssertionCertificate. Quindi si modifica il metodo di callback che viene fornito quando si crea un nuovo KeyVaultClient.And then we change the callback method that we supply when creating a new KeyVaultClient. Si noti che questo sostituisce il codice utilizzato nell'esempio precedente.Note that this replaces the code that we had in the preceding example.

Utils.GetCert();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(Utils.GetAccessToken));

Aggiungere un certificato all'app Web tramite il portale di AzureAdd a Certificate to your Web App through the Azure portal

L'aggiunta di un certificato all'app Web è un semplice processo in due passaggi.Adding a Certificate to your Web App is a simple two-step process. In primo luogo, accedere al portale di Azure e passare all'applicazione Web.First, go to the Azure portal and navigate to your Web App. Nel pannello Impostazioni per l'applicazione Web, fare clic sulla voce relativa a "domini personalizzati e SSL".On the Settings blade for your Web App, click on the entry for "Custom domains and SSL". Nel pannello che si apre sarà possibile caricare il certificato creato nell'esempio precedente, KVWebApp.pfx; assicurarsi di ricordare la password per il pfx.On the blade that opens you will be able to upload the Certificate that you created in the preceding example, KVWebApp.pfx, make sure that you remember the password for the pfx.

Aggiunta di un certificato a un'applicazione Web nel portale di Azure

Come ultima cosa, occorre aggiungere un'impostazione dell'applicazione all'app Web denominata WEBSITE_LOAD_CERTIFICATES e il valore *.The last thing that you need to do is to add an Application Setting to your Web App that has the name WEBSITE_LOAD_CERTIFICATES and a value of *. Ciò garantisce che siano caricati tutti i certificati.This will ensure that all Certificates are loaded. Se si desidera caricare solo i certificati caricati, è possibile immettere un elenco delimitato da virgole delle identificazioni personali.If you wanted to load only the Certificates that you have uploaded, then you can enter a comma-separated list of their thumbprints.

Per ulteriori informazioni sull'aggiunta di un certificato a un'applicazione Web, vedere Utilizzo di certificati nelle applicazioni di siti Web di AzureTo learn more about adding a Certificate to a Web App, see Using Certificates in Azure Websites Applications

Aggiungere un certificato all'insieme di credenziali delle chiavi come segretoAdd a Certificate to Key Vault as a secret

Invece di caricare il certificato direttamente nel servizio App Web, è possibile archiviarlo nell'insieme di credenziali delle chiavi come segreto e distribuirlo da questa posizione.Instead of uploading your certificate to the Web App service directly, you can store it in Key Vault as a secret and deploy it from there. Si tratta di un processo in due fasi descritto nel post di blog seguente, Deploying Azure Web App Certificate through Key VaultThis is a two-step process that is outlined in the following blog post, Deploying Azure Web App Certificate through Key Vault

Passaggi successiviNext steps

Per i riferimenti alla programmazione, vedere Informazioni di riferimento sull'API client C# dell'insieme di credenziali chiave di Azure.For programming references, see Azure Key Vault C# Client API Reference.