Tutorial: Uso de Azure Key Vault desde una aplicación webTutorial: Use Azure Key Vault from a web application

Use este tutorial como ayuda para aprender a usar Azure Key Vault desde una aplicación web.Use this tutorial to help you learn how to use Azure Key Vault from a web application in Azure. Muestra el proceso de acceder a un secreto de un Azure Key Vault para usarlo en una aplicación web.It shows the process of accessing a secret from an Azure Key Vault for use in a web application. Luego, el tutorial se basa en el proceso y usa un certificado en lugar de un secreto de cliente.The tutorial then builds on the process and uses a certificate instead of a client secret. Este tutorial está diseñado para desarrolladores web que comprendan los conceptos básicos de la creación de aplicaciones web en Azure.This tutorial is designed for web developers that understand the basics of creating web applications on Azure.

En este tutorial, aprenderá a:In this tutorial, you learn how to:

  • Incorporar la configuración de la aplicación al archivo web.configAdd application settings to the web.config file
  • Agregar un método para obtener un token de accesoAdd a method to get an access token
  • Recuperar el token en Inicio de aplicaciónRetrieve the token on Application Start
  • Autenticar con un certificadoAuthenticate with a certificate

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Requisitos previosPrerequisites

Para realizar este tutorial, necesitará los siguientes elementos:To complete this tutorial, you must have the following items:

  • Un URI de un secreto en una instancia de Azure Key Vault.A URI to a secret in an Azure Key Vault
  • Un Id. de cliente y un secreto de cliente para una aplicación web registrada en Azure Active Directory que tenga acceso a su almacén de claves.A Client ID and a Client Secret for a web application registered with Azure Active Directory that has access to your Key Vault
  • Una aplicación web.A web application. En este tutorial se muestran los pasos para una aplicación ASP.NET MVC implementada en Azure como una aplicación web.This tutorial shows the steps for an ASP.NET MVC application deployed in Azure as a Web App.

Complete los pasos que aparecen en Introducción a Azure Key Vault para obtener el URI a un secreto, el identificador de cliente, el secreto de cliente y registrar la aplicación.Complete the steps in Get Started with Azure Key Vault to get the URI to a secret, Client ID, Client Secret, and register the application. La aplicación web accederá al almacén y tendrá que estar registrada en Azure Active Directory.The web application will access the vault and must be registered in Azure Active Directory. También debe tener derechos de acceso a Key Vault.It also needs to have access rights to Key Vault. Si no es así, vuelva al apartado sobre cómo registrar una aplicación del tutorial de introducción y repita los pasos enumerados.If not, go back to Register an Application in the Get Started tutorial and repeat the steps listed. Para más información sobre cómo crear instancias de Azure Web Apps, consulte Información general de Web Apps.For more information about creating Azure Web Apps, see Web Apps overview.

Este ejemplo depende del aprovisionamiento manual de identidades de Azure Active Directory.This sample depends on manually provisioning Azure Active Directory identities. Pero debe usar Identidades administradas de recursos de Azure en su lugar, que aprovisiona automáticamente identidades de Azure AD.But you should use Managed identities for Azure resources instead, which automatically provisions Azure AD identities. Para más información, consulte el ejemplo en GitHub y el tutorial de App Service y Functions.For more information, see the sample on GitHub and the related App Service and Functions tutorial. También puede examinar el artículo Configuración de una aplicación web de Azure para que lea un secreto desde el almacén de claves específico de Key Vault.You can also look at the Key Vault specific Configure an Azure web application to read a secret from Key Vault tutorial.

Incorporación de paquetes NuGetAdd NuGet packages

Hay dos paquetes que la aplicación web debe tener instalados.There are two packages that your web application needs to have installed.

  • Biblioteca de autenticación de Active Directory: contiene métodos para interactuar con Azure Active Directory y administrar la identidad de usuario.Active Directory Authentication Library - has methods for interacting with Azure Active Directory and managing user identity
  • Biblioteca de Almacén claves de Azure: contiene métodos para interactuar con Azure Key Vault.Azure Key Vault Library - has methods for interacting with Azure Key Vault

Los dos paquetes se pueden instalar mediante la Consola del Administrador de paquetes con el comando Install-Package.Both of these packages can be installed using the Package Manager Console using the Install-Package command.

Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory 
Install-Package Microsoft.Azure.KeyVault

Modificación de web.configModify web.config

Hay tres configuraciones de aplicaciones que deben agregarse al archivo web.config como se indica a continuación.There are three application settings that need to be added to the web.config file as follows. Agregaremos los valores reales en Azure Portal para lograr un nivel de seguridad adicional.We'll be adding the actual values in the Azure portal for an additional level of security.

    <!-- 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" />
    <!-- If you aren't hosting your app as an Azure Web App, then you should use the actual ClientId, Client Secret, and Secret URI values -->

Incorporación del método para obtener un token de accesoAdd method to get an access token

Para usar la API de Key Vault necesita un token de acceso.To use the Key Vault API, you need an access token. El cliente de Key Vault controla las llamadas a la API de Key Vault, pero deberá suministrarle una función que obtenga el token de acceso.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. En el ejemplo siguiente se muestra el código para obtener un token de acceso de Azure Active Directory.The following example is code to get an access token from Azure Active Directory. Este código puede estar en cualquier parte de la aplicación.This code can go anywhere in your application. Quiero agregar una clase 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;
}
// Using Client ID and Client Secret is a way to authenticate an Azure AD application.
// Using it in your web application allows for a separation of duties and more control over your key management. 
// However, it does rely on putting the Client Secret in your configuration settings.
// For some people, this can be as risky as putting the secret in your configuration settings.

Recuperación del secreto en Inicio de aplicaciónRetrieve the secret on Application Start

Ahora tenemos el código para llamar a la API de Key Vault y recuperar el secreto.Now we need code to call the Key Vault API and retrieve the secret. El siguiente código se puede colocar en cualquier parte siempre que se llame antes de que sea necesario usarlo.The following code can be put anywhere as long as it's called before you need to use it. Coloqué este código en el evento Inicio de aplicación en Global.asax para que se ejecute una vez en el inicio y permita que esté disponible el secreto para la aplicación.I've put this code in the Application Start event in the Global.asax so 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;

Incorporación de la configuración de la aplicación en Azure PortalAdd app settings in the Azure portal

En Azure Web App, ahora puede agregar los valores reales para AppSettings en Azure Portal.In the Azure Web App, you can now add the actual values for the AppSettings in the Azure portal. Con este paso, los valores reales no estarán en web.config sino que estarán protegidos a través de Portal donde cuenta con funcionalidades de control de acceso independientes.By doing this step, the actual values won't be in the web.config but protected via the Portal where you have separate access control capabilities. Estos valores se sustituirán por los valores que escribió en web.config. Asegúrese de que los nombres sean los mismos.These values will be substituted for the values that you entered in your web.config. Make sure that the names are the same.

Configuración de la aplicación mostrada en Azure Portal

Autenticación con un certificado en lugar de hacerlo con un secreto de clienteAuthenticate with a certificate instead of a client secret

Ahora que comprende la autenticación de una aplicación de Azure AD con el identificador de cliente y el secreto de cliente, usemos un identificador de cliente y un certificado.Now that you understand authenticating an Azure AD app using Client ID and Client Secret, let's use a Client ID and a certificate. Para usar un certificado en una instancia de Azure Web App, use estos pasos:To use a certificate in an Azure Web App, use the following steps:

  1. Obtener o crear un certificadoGet or create a Certificate
  2. Asociar el certificado a una aplicación de Azure ADAssociate the certificate with an Azure AD application
  3. Agregar código a la aplicación web para usar el certificadoAdd code to your web app to use the certificate
  4. Agregar un certificado a la aplicación webAdd a certificate to your web app

Obtener o crear un certificadoGet or create a certificate

Nos aseguraremos de hacer un certificado de prueba para este tutorial.We'll make a test certificate for this tutorial. Este es un script para crear un certificado autofirmado.Here is a script to create a self-signed certificate. Cambie al directorio a aquel en el que desea que se creen los archivos de certificado.Change directory to where you want the cert files created. Para las fechas de inicio y finalización del certificado, puede usar la fecha de hoy más un año.For the beginning and ending date of the certificate, you can use the current date plus one year.

#Create self-signed certificate and export pfx and cer files 
$PfxFilePath = 'KVWebApp.pfx'
$CerFilePath = 'KVWebApp.cer'
$DNSName = 'MyComputer.Contoso.com'
$Password = 'MyPassword"'

$StoreLocation = 'CurrentUser' #be aware that LocalMachine requires elevated privileges
$CertBeginDate = Get-Date
$CertExpiryDate = $CertBeginDate.AddYears(1)

$SecStringPw = ConvertTo-SecureString -String $Password -Force -AsPlainText 
$Cert = New-SelfSignedCertificate -DnsName $DNSName -CertStoreLocation "cert:\$StoreLocation\My" -NotBefore $CertBeginDate -NotAfter $CertExpiryDate -KeySpec Signature
Export-PfxCertificate -cert $Cert -FilePath $PFXFilePath -Password $SecStringPw 
Export-Certificate -cert $Cert -FilePath $CerFilePath 

Anote la fecha de finalización y la contraseña del archivo .pfx (en este ejemplo: 15 de mayo de 2019 y MyPassword).Make note of the end date and the password for the .pfx (in this example: May 15, 2019 and MyPassword). Necesitará esta información en el script siguiente.You'll need them for the script below.

Asociar el certificado a una aplicación de Azure ADAssociate the certificate with an Azure AD application

Ahora que tiene un certificado, tendrá que asociarlo a una aplicación de Azure AD.Now that you have a certificate, you need to associate it with an Azure AD application. La asociación se puede completar mediante PowerShell.The association can be completed through PowerShell. Ejecute los siguientes comandos para asociar el certificado con la aplicación de Azure AD:Run the following commands to associate 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 get,list,set,delete,backup,restore,recover,purge -ResourceGroupName 'contosorg'

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

Después de ejecutar estos comandos, podrá ver la aplicación en Azure AD.After you've run these commands, you can see the application in Azure AD. Cuando busque los registros de la aplicación, asegúrese de seleccionar My apps (Mis aplicaciones) en lugar de "All apps" (Todas las aplicaciones) en el cuadro de búsqueda.When searching the app registrations, make sure you select My apps instead of "All apps" in the search dialog.

Agregar código a la aplicación web para usar el certificadoAdd code to your web app to use the certificate

Ahora agregaremos código a Web App para tener acceso al certificado y usarlo para la autenticación.Now we'll add code to your Web App to access the cert and use it for authentication.

En primer lugar, este es el código para tener acceso al certificado. Observe que StoreLocation es CurrentUser y no LocalMachine.First, there's code to access the cert. Note that StoreLocation is CurrentUser instead of LocalMachine. Fíjese también en que usamos "false" en el método Find, ya que usamos un certificado de prueba.And that we're supplying 'false' to the Find method because we're using a test cert.

//Add this using statement
using System.Security.Cryptography.X509Certificates;  

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();
        }
    }
}

El código siguiente usa CertificateHelper y crea ClientAssertionCertificate, que es necesario para la autenticación.Next is code that uses the CertificateHelper and creates a ClientAssertionCertificate that 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);
}

Este es el nuevo código para obtener el token de acceso.Here is the new code to get the access token. Este código reemplaza al método GetToken en el ejemplo anterior.This code replaces the GetToken method in the preceding example. Para su comodidad, le hemos dado un nombre diferente.I've given it a different name for convenience. Para facilitar su uso, hemos colocado todo este código en la clase Utils del proyecto de aplicación web.I've put all of this code into my Web App project's Utils class for ease of use.

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;
}

El último cambio de código se da en el método Application_Start.The last code change is in the Application_Start method. En primer lugar, es preciso llamar al método GetCert() para cargar ClientAssertionCertificate.First we need to call the GetCert() method to load the ClientAssertionCertificate. Y, a continuación, se cambia el método de devolución de llamada que se suministra al crear un nuevo KeyVaultClient.And then we change the callback method that we supply when creating a new KeyVaultClient. Este código reemplaza al código que teníamos en el ejemplo anterior.This code replaces the code that we had in the preceding example.

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

Incorporación de un certificado a una aplicación web a través de Azure PortalAdd a certificate to your web app through the Azure portal

La incorporación de un certificado a la instancia de Web App es un sencillo proceso de dos pasos.Adding a Certificate to your Web App is a simple two-step process. En primer lugar, vaya a Azure Portal y navegue a Web App.First, go to the Azure portal and navigate to your Web App. En la configuración de la aplicación web, haga clic en la entrada de configuración de SSL.On the Settings for your Web App, click on the entry for SSL settings. Cuando se abra. cargue el certificado que creó en el ejemplo anterior, KVWebApp.pfx.When it opens, upload the Certificate that you created in the preceding example, KVWebApp.pfx. Asegúrese de recordar la contraseña para el archivo pfx.Make sure that you remember the password for the pfx.

Incorporación de un certificado a Web App en Azure Portal

Lo último que debe hacer es agregar una configuración de aplicación a la aplicación web cuyo nombre es WEBSITE_LOAD_CERTIFICATES y cuyo valor es *.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 *. Este paso garantizará que se cargan todos los certificados.This step will make sure that all Certificates are loaded. Si desea cargar solo los certificados que ha cargado, puede escribir una lista separada por comas de sus huellas digitales.If you wanted to load only the Certificates that you've uploaded, then you can enter a comma-separated list of their thumbprints.

Limpieza de recursosClean up resources

Cuando ya no lo necesite, elimine el servicio de la aplicación, el almacén de claves y la aplicación de Azure AD que usó para el tutorial.When no longer needed, delete the app service, key vault, and Azure AD application you used for the tutorial.

Pasos siguientesNext steps