Tutorial: Verwenden von Azure Key Vault aus einer WebanwendungTutorial: Use Azure Key Vault from a web application

In diesem Tutorial erfahren Sie, wie Sie Azure Key Vault aus einer Webanwendung in Azure verwenden.Use this tutorial to help you learn how to use Azure Key Vault from a web application in Azure. Es zeigt den Prozess für den Zugriff auf einen geheimen Schlüssel aus Azure Key Vault für die Verwendung in einer Webanwendung.It shows the process of accessing a secret from an Azure Key Vault for use in a web application. Anschließend baut das Tutorial auf dem Prozess auf und verwendet ein Zertifikat anstelle eines geheimen Clientschlüssels.The tutorial then builds on the process and uses a certificate instead of a client secret. Dieses Tutorial richtet sich an Webentwickler, die die Grundlagen zum Erstellen von Webanwendungen in Azure kennen.This tutorial is designed for web developers that understand the basics of creating web applications on Azure.

In diesem Tutorial lernen Sie Folgendes:In this tutorial, you learn how to:

  • Hinzufügen von Anwendungseinstellungen zur Datei „web.config“Add application settings to the web.config file
  • Hinzufügen einer Methode zum Abrufen eines ZugriffstokensAdd a method to get an access token
  • Abrufen des Tokens beim AnwendungsstartRetrieve the token on Application Start
  • Authentifizierung mit einem ZertifikatAuthenticate with a certificate

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.If you don't have an Azure subscription, create a free account before you begin.

VoraussetzungenPrerequisites

Für dieses Tutorial benötigen Sie folgende Elemente:To complete this tutorial, you must have the following items:

  • Einen URI eines geheimen Schlüssels in Azure Key VaultA URI to a secret in an Azure Key Vault
  • Eine Client-ID und einen geheimen Schlüssel für den Client für eine Webanwendung, die in Azure Active Directory registriert ist und Zugriff auf Ihren Schlüsseltresor hatA Client ID and a Client Secret for a web application registered with Azure Active Directory that has access to your Key Vault
  • Eine Webanwendung.A web application. In diesem Tutorial werden die Schritte für eine ASP.NET MVC-Anwendung gezeigt, die in Azure als Web-App bereitgestellt wurde.This tutorial shows the steps for an ASP.NET MVC application deployed in Azure as a Web App.

Führen Sie die Schritte unter Erste Schritte mit Azure Key Vault aus, um den URI für einen geheimen Schlüssel, eine Client-ID, einen geheimen Clientschlüssel abzurufen und die Anwendung zu registrieren.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. Die Webanwendung hat Zugriff auf den Tresor und muss in Azure Active Directory registriert werden.The web application will access the vault and needs to be registered in Azure Active Directory. Darüber hinaus benötigt sie Zugriffsrechte für Key Vault.It also needs to have access rights to Key Vault. Wenn dies nicht der Fall ist, kehren Sie zur Registrierung der Anwendung im Tutorial „Erste Schritte“ zurück, und wiederholen Sie die dort aufgeführten Schritte.If not, go back to Register an Application in the Get Started tutorial and repeat the steps listed. Weitere Informationen zur Erstellung von Azure-Web-Apps finden Sie unter Web-Apps – Übersicht.For more information about creating Azure Web Apps, see Web Apps overview.

Dieses Beispiel basiert auf der manuellen Bereitstellung von Azure Active Directory-Identitäten.This sample depends on manually provisioning Azure Active Directory Identities. Derzeit gibt es eine Vorschauversion eines neuen Features namens Verwaltete Dienstidentität (Managed Service Identity, MSI). Mit diesem Feature können Azure AD-Identitäten automatisch bereitgestellt werden.Currently, there's a new feature in preview called Managed Service Identity (MSI), which can automatically provision Azure AD Identities. Weitere Informationen finden Sie im Beispiel im GitHub und im zugehörigen Tutorial MSI mit App Service und Functions.For more information, see the sample on GitHub and the related MSI with App Service and Functions tutorial.

Hinzufügen von NuGet-PaketenAdd NuGet packages

Für Ihre Webanwendung müssen zwei Pakete installiert sein.There are two packages that your web application needs to have installed.

  • Active Directory-Authentifizierungsbibliothek: enthält Methoden für die Interaktion mit Azure Active Directory und die Verwaltung der BenutzeridentitätActive Directory Authentication Library - has methods for interacting with Azure Active Directory and managing user identity
  • Azure Key Vault-Bibliothek: enthält Methoden für die Interaktion mit Azure Key VaultAzure Key Vault Library - has methods for interacting with Azure Key Vault

Beide Pakete können mithilfe der Paket-Manager-Konsole mit dem Befehl „Install-Package“ installiert werden.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

Ändern der Datei „web.config“Modify web.config

Es gibt drei Anwendungseinstellungen, die wie folgt zur Datei „web.config“ hinzugefügt werden müssen.There are three application settings that need to be added to the web.config file as follows. Zur Erhöhung der Sicherheit fügen wir die tatsächlichen Werte im Azure-Portal hinzu.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 -->

Hinzufügen einer Methode zum Abrufen eines ZugriffstokensAdd method to get an access token

Sie benötigen für die Verwendung der Key Vault-API ein Zugriffstoken.To use the Key Vault API, you need an access token. Der Key Vault Client verarbeitet die Aufrufe in der Key Vault-API. Sie müssen dafür jedoch eine Funktion angeben, die das Zugriffstoken übernimmt.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. Im folgenden Beispiel ist Code für das Abrufen eines Zugriffstokens von Azure Active Directory enthalten.The following example is code to get an access token from Azure Active Directory. Dieser Code kann überall in Ihrer Anwendung eingefügt werden.This code can go anywhere in your application. Ich füge dafür i.d.R. die Klasse „Utils“ oder „EncryptionHelper“ hinzu.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.

Abrufen des geheimen Schlüssel beim AnwendungsstartRetrieve the secret on Application Start

Wir benötigen nun Code zum Aufrufen der Key Vault-API, um den geheimen Schlüssel abzurufen.Now we need code to call the Key Vault API and retrieve the secret. Der folgende Code kann an einer beliebigen Stelle eingefügt werden, sofern er aufgerufen wird, bevor Sie ihn verwenden müssen.The following code can be put anywhere as long as it's called before you need to use it. Ich habe diesen Code im Ereignis „Application Start“ (Anwendungsstart) in der Datei „Global.asax“ eingefügt, sodass es einmal beim Start ausgeführt wird und den geheimen Schlüssel für die Anwendung verfügbar macht.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;

Hinzufügen von App-Einstellungen im Azure-PortalAdd app settings in the Azure Portal

In der Azure-Web-App können Sie jetzt die tatsächlichen Werte für die App-Einstellungen im Azure-Portal hinzufügen.In the Azure Web App, you can now add the actual values for the AppSettings in the Azure portal. Damit befinden sich die tatsächlichen Werte nicht in der Datei „web.config“, sondern sie werden über das Portal geschützt, für das Sie eigene Zugriffssteuerungsfunktionen verwenden können.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. Diese Werte ersetzen die Werte, die Sie in der Datei „web.config“ eingegeben haben. Stellen Sie sicher, dass die Namen übereinstimmen.These values will be substituted for the values that you entered in your web.config. Make sure that the names are the same.

Anwendungseinstellungen im Azure-Portal

Authentifizieren mit einem Zertifikat anstelle eines geheimen ClientschlüsselsAuthenticate with a certificate instead of a client secret

Nun, da Sie eine Azure AD-App mithilfe einer Client-ID und eines geheimen Clientschlüssels authentifizieren können, verwenden wir eine Client-ID und ein Zertifikat.Now that you understand authenticating an Azure AD app using Client ID and Client Secret, let's use a Client ID and a certificate. Führen Sie die folgenden Schritte aus, um ein Zertifikat in einer Azure-Web-App zu verwenden:To use a certificate in an Azure Web App, use the following steps:

  1. Abrufen oder Erstellen eines ZertifikatsGet or create a Certificate
  2. Zuordnen des Zertifikats zu einer Azure AD-AppAssociate the certificate with an Azure AD application
  3. Hinzufügen von Code zur Web-App für die Verwendung des ZertifikatsAdd code to your web app to use the certificate
  4. Hinzufügen eines Zertifikats zur Web-AppAdd a certificate to your web app

Abrufen oder Erstellen eines ZertifikatsGet or create a certificate

Wir erstellen für dieses Tutorial ein Testzertifikat.We'll make a test certificate for this tutorial. Im Folgenden finden Sie ein Skript zur Erstellung eines selbstsignierten Zertifikats.Here is a script to create a self-signed certificate. Passen Sie das Verzeichnis an, um den Speicherort für die Zertifikatdateien festzulegen.Change directory to where you want the cert files created. Erhöhen Sie zur Angabe des Start- und Enddatums für das Zertifikat das aktuelle Datum jeweils um ein Jahr.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 = "c:\data\KVWebApp.pfx" 
$CerFilePath = "c:\data\KVWebApp.cer" 
$DNSName = "MyComputer.Contoso.com" 
$Password ="MyPassword" 
$SecStringPw = ConvertTo-SecureString -String $Password -Force -AsPlainText 
$Cert = New-SelfSignedCertificate -DnsName $DNSName -CertStoreLocation "cert:\LocalMachine\My" -NotBefore 05/15/2018 -NotAfter 05/15/2019 
Export-PfxCertificate -cert $cert -FilePath $PFXFilePath -Password $SecStringPw 
Export-Certificate -cert $cert -FilePath $CerFilePath 

Notieren Sie sich das Enddatum und das Kennwort für die PFX-Datei (in diesem Beispiel: 15. Mai 2019 und „MyPassword“).Make note of the end date and the password for the .pfx (in this example: May 15, 2019 and MyPassword). Sie benötigen diese für das nachfolgende Skript.You'll need them for the script below.

Zuordnen des Zertifikats zu einer Azure AD-AppAssociate the certificate with an Azure AD application

Nachdem Sie ein Zertifikat erstellt haben, müssen Sie es einer Azure AD-Anwendung zuordnen.Now that you have a certificate, you need to associate it with an Azure AD application. Die Zuordnung kann über PowerShell ausgeführt werden.The association can be completed through PowerShell. Führen Sie die folgenden Befehle aus, um das Zertifikat der Azure AD-Anwendung zuzuordnen: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 all -ResourceGroupName 'contosorg'

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

Nachdem Sie diese Befehle ausgeführt haben, wird die Anwendung in Azure AD angezeigt.After you've run these commands, you can see the application in Azure AD. Beim Durchsuchen der App-Registrierungen müssen Sie sicherstellen, dass Sie im Dialogfeld für die Suche Meine Apps anstelle von „Alle Apps“ ausgewählt haben.When searching the app registrations, make sure you select My apps instead of "All apps" in the search dialog.

Hinzufügen von Code zur Web-App für die Verwendung des ZertifikatsAdd code to your web app to use the certificate

Nun fügen wir Code zur Web-App hinzu, um auf das Zertifikat zuzugreifen und es für die Authentifizierung zu verwenden.Now we'll add code to your Web App to access the cert and use it for authentication.

Zunächst erstellen wir den Code für den Zugriff auf das Zertifikat. Beachten Sie, dass „StoreLocation“ den Wert „CurrentUser“ anstelle von „LocalMachine“ enthält.First, there's code to access the cert. Note that StoreLocation is CurrentUser instead of LocalMachine. Beachten Sie auch, dass wir „False“ für die Find-Methode bereitstellen, da wir ein Testzertifikat verwenden.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();
        }
    }
}

Als Nächstes folgt Code, der „CertificateHelper“ verwendet und das für die Authentifizierung benötigte „ClientAssertionCertificate“ erstellt.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);
}

Dies ist der neue Code zum Abrufen des Zugriffstokens.Here is the new code to get the access token. Dieser Code ersetzt die GetToken-Methode im vorherigen Beispiel.This code replaces the GetToken method in the preceding example. Ich habe ihr der Einfachheit halber einen anderen Namen gegeben.I've given it a different name for convenience. Zur einfacheren Handhabung habe ich all diesen Code in die Klasse „Utils“ meines Web-App-Projekts eingefügt.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;
}

Die letzte Codeänderung betrifft die Application_Start-Methode.The last code change is in the Application_Start method. Zunächst müssen wir die GetCert()-Methode aufrufen, um das „ClientAssertionCertificate“ zu laden.First we need to call the GetCert() method to load the ClientAssertionCertificate. Anschließend ändern wir die Callback-Methode, die wir beim Erstellen eines neues „KeyVaultClient“ bereitstellen.And then we change the callback method that we supply when creating a new KeyVaultClient. Beachten Sie, dass dieser Code den Code im vorherigen Beispiel ersetzt.This code replaces the code that we had in the preceding example.

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

Hinzufügen eines Zertifikats zu Ihrer Web-App über das Azure-PortalAdd a certificate to your web app through the Azure Portal

Das Hinzufügen eines Zertifikats zu Ihrer Web-App ist ein einfacher Zwei-Schritte-Prozess.Adding a Certificate to your Web App is a simple two-step process. Navigieren Sie zunächst im Azure-Portal zu Ihrer Web-App.First, go to the Azure portal and navigate to your Web App. Klicken Sie in Ihrer Web-App unter „Einstellungen“ auf den Eintrag für SSL-Einstellungen.On the Settings for your Web App, click on the entry for SSL settings. Wenn dieser geöffnet wird, laden Sie das im vorherigen Beispiel erstellte Zertifikat, „KVWebApp.pfx“ hoch.When it opens, upload the Certificate that you created in the preceding example, KVWebApp.pfx. Stellen Sie sicher, dass Sie das Kennwort für die PFX-Datei merken.Make sure that you remember the password for the pfx.

Hinzufügen eines Zertifikats zu einer Web-App im Azure-Portal

Abschließend müssen Sie eine Anwendungseinstellung mit dem Namen „WEBSITE_LOAD_CERTIFICATES“ und dem Wert „*“ zu Ihrer Web-App hinzufügen.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 *. Dadurch wird sichergestellt, dass alle Zertifikate geladen werden.This step will make sure that all Certificates are loaded. Wenn Sie nur die von Ihnen hochgeladenen Zertifikate laden möchten, können Sie eine durch Kommas getrennte Liste ihrer Fingerabdrücke eingeben.If you wanted to load only the Certificates that you've uploaded, then you can enter a comma-separated list of their thumbprints.

Bereinigen von RessourcenClean up resources

Sie können den App-Dienst, den Schlüsseltresor und die Azure AD-Anwendung löschen, die Sie für das Tutorial verwendet haben, wenn Sie diese nicht mehr benötigen.When no longer needed, delete the app service, key vault, and Azure AD application you used for the tutorial.

Nächste SchritteNext steps