Verwenden von TLS/SSL-Zertifikaten im Anwendungscode

In Ihrem Anwendungscode können Sie sowohl auf public-Schlüsselzertifikate als auch auf Zertifikate zugreifen, die einen privaten Schlüssel enthalten, den Sie Azure App Service hinzufügen. Ihr App-Code kann als Client fungieren und auf einen externen Dienst zugreifen, der eine Zertifikatauthentifizierung erfordert. Es kann auch erforderlich sein, kryptografische Aufgaben auszuführen. In diesem Artikel wird gezeigt, wie Sie öffentlich oder privat signierte Zertifikate in Ihrem Anwendungscode verwenden.

Dieser Ansatz zur Verwendung von Zertifikaten in Ihrem Code verwendet die Tls-Funktionalität (Transport Layer Security) in App Service, die erfordert, dass Ihre App auf der Ebene "Einfach" oder höher ist. Wenn sich Ihre App auf der Stufe "Frei" oder "Freigegeben" befindet, können Sie die Zertifikatdatei in Ihr App-Repository einschließen.

Wenn Sie zulassen, dass App Service Ihre TLS-Zertifikate verwaltet, können Sie die Zertifikate und den Anwendungscode separat verwalten und Ihre vertraulichen Daten schützen.

Voraussetzungen

• Erstellen einer App Service-App
• Hinzufügen eines Zertifikats zu Ihrer App

Finde den Daumenabdruck

1. Melden Sie sich im Azure-Portal an.

2. Wählen Sie Ihre App Service-App aus.

3. Wählen Sie unter "Einstellungen" im Randleistenmenü "Zertifikate" aus.

4. Wählen Sie Mitgebrachte Zertifikate (PFX) oder Öffentliche Schlüsselzertifikate (.cer) aus.

5. Suchen Sie das Zertifikat, das Sie verwenden möchten, und kopieren Sie den Fingerabdruck.

Das Zertifikat zugänglich machen

Um auf ein Zertifikat im App-Code zuzugreifen, fügen Sie der App-Einstellung „WEBSITE_LOAD_CERTIFICATES“ den Fingerabdruck hinzu. Sie können den folgenden Befehl in Azure Cloud Shell ausführen.

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_LOAD_CERTIFICATES=<comma-separated-certificate-thumbprints>

Um alle Ihre Zertifikate barrierefrei zu machen, legen Sie den Wert auf *.

Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, sind alle zuvor hinzugefügten Zertifikate für den Anwendungscode zugänglich. Wenn Sie Ihrer App später ein Zertifikat hinzufügen, starten Sie die App neu, um das neue Zertifikat für Ihre App zugänglich zu machen. Weitere Informationen finden Sie unter Aktualisieren oder Erneuern eines Zertifikats.

Laden von Zertifikaten in Windows-Apps

Die WEBSITE_LOAD_CERTIFICATES-App Einstellung macht die angegebenen Zertifikate für Ihre Windows-gehostete App im Windows-Zertifikatspeicher unter Current User\My zugänglich.

In C#-Code greifen Sie mithilfe des Zertifikatfingerabdrucks auf das Zertifikat zu. Der folgende Code lädt ein Zertifikat mit dem Fingerabdruck <your-cert-thumbprint>.

using System;
using System.Linq;
using System.Security.Cryptography.X509Certificates;

string certThumbprint = "<your-cert-thumbprint>";
bool validOnly = false;

using (X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
  certStore.Open(OpenFlags.ReadOnly);

  X509Certificate2Collection certCollection = certStore.Certificates.Find(
                              X509FindType.FindByThumbprint,
                              // Replace below with your certificate's thumbprint
                              certThumbprint,
                              validOnly);
  // Get the first cert with the thumbprint
  X509Certificate2 cert = certCollection.OfType<X509Certificate2>().FirstOrDefault();

  if (cert is null)
      throw new Exception($"Certificate with thumbprint {certThumbprint} was not found");

  // Use certificate
  Console.WriteLine(cert.FriendlyName);
  
  // Consider to call Dispose() on the certificate after it's being used, available in .NET 4.6 and later
}

In Java-Code greifen Sie über das Windows-MY-Lager mithilfe des Feldes Subject Common Name auf das Zertifikat zu. Weitere Informationen finden Sie unter Public Key-Zertifikat. Der folgende Code zeigt, wie ein privates Schlüsselzertifikat geladen wird:

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import java.security.KeyStore;
import java.security.cert.Certificate;
import java.security.PrivateKey;

...
KeyStore ks = KeyStore.getInstance("Windows-MY");
ks.load(null, null); 
Certificate cert = ks.getCertificate("<subject-cn>");
PrivateKey privKey = (PrivateKey) ks.getKey("<subject-cn>", ("<password>").toCharArray());

// Use the certificate and key
...

Informationen zu Sprachen, die den Windows-Zertifikatspeicher nicht unterstützen oder unzureichend unterstützen, finden Sie unter Laden eines Zertifikats aus einer Datei.

Laden eines Zertifikats aus einer Datei

Wenn Sie eine Zertifikatdatei laden müssen, die Sie manuell hochladen müssen, ist es besser, das Zertifikat mithilfe von FTPS (File Transfer Protocol Secure) anstelle von Git hochzuladen. Halten Sie vertrauliche Daten wie beispielsweise private Zertifikatschlüssel aus der Quellcodeverwaltung heraus.

ASP.NET und ASP.NET Core für Windows müssen auch dann auf den Zertifikatspeicher zugreifen, wenn Sie ein Zertifikat aus einer Datei laden. Um eine Zertifikatdatei in einer Windows .NET-App zu laden, laden Sie das aktuelle Benutzerprofil mit dem folgenden Befehl:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_LOAD_USER_PROFILE=1

Dieser Ansatz zur Verwendung von Zertifikaten in Ihrem Code verwendet die TLS-Funktionalität in App Service, die erfordert, dass Ihre App auf der Stufe "Einfach" oder höher ist.

Im folgenden C#-Beispiel wird ein öffentliches Zertifikat aus einem relativen Pfad in Ihrer App geladen:

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;

...

var cert = X509CertificateLoader.LoadCertificateFromFile("~/<relative-path-to-cert-file>");

// Use the loaded certificate

Informationen zum Laden eines TLS-Zertifikats aus einer Datei in Node.js, PHP, Python oder Java finden Sie in der Dokumentation für die jeweilige Sprache oder Webplattform.

Laden von Zertifikaten in Linux/Windows-Containern

Die App-Einstellung WEBSITE_LOAD_CERTIFICATES macht die angegebenen Zertifikate für Ihre Windows oder linux-benutzerdefinierten Container (einschließlich integrierter Linux-Container) als Dateien zugänglich. Die Dateien finden Sie unter den folgenden Verzeichnissen:

Die Zertifikatsdateinamen sind die Zertifikatfingerabdrücke.

Darüber hinaus laden Windows Server Core- und Windows Nano Server-Container die Zertifikate automatisch in den Zertifikatspeicher in LocalMachine\My. Um die Zertifikate zu laden, befolgen Sie das gleiche Muster wie in Laden von Zertifikaten in Windows Apps. Bei Windows Nano-basierten Containern verwenden Sie die Dateipfade wie in Laden eines Zertifikats aus einer Datei gezeigt.

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;

...

var cert = X509CertificateLoader.LoadCertificateFromFile("/var/ssl/certs/<thumbprint>.der");

// Use the loaded certificate

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;

...

var cert = X509CertificateLoader.LoadCertificateFromFile("/var/ssl/private/<thumbprint>.p12");

// Use the loaded certificate

using System;
using System.Linq;
using System.Security.Cryptography.X509Certificates;

string certThumbprint = "E661583E8FABEF4C0BEF694CBC41C28FB81CD870";
bool validOnly = false;

using (X509Store certStore = new X509Store(StoreName.My, StoreLocation.LocalMachine))
{
  certStore.Open(OpenFlags.ReadOnly);

  X509Certificate2Collection certCollection = certStore.Certificates.Find(
                              X509FindType.FindByThumbprint,
                              // Replace below with your certificate's thumbprint
                              certThumbprint,
                              validOnly);
  // Get the first cert with the thumbprint
  X509Certificate2 cert = certCollection.OfType<X509Certificate2>().FirstOrDefault();

  if (cert is null)
      throw new Exception($"Certificate with thumbprint {certThumbprint} was not found");

  // Use certificate
  Console.WriteLine(cert.FriendlyName);
  
  // Consider to call Dispose() on the certificate after it's being used, available in .NET 4.6 and later
}

using System.Security.Cryptography.X509Certificates;

string Thumbprint = "C0CF730E216F5D690D1834446554DF5DC577A78B";

using X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
{
    store.Open(OpenFlags.ReadOnly);
    
    // Get the first cert with the thumbprint
    var certificate = store.Certificates.OfType<X509Certificate2>()
        .First(c => c.Thumbprint == Thumbprint) ?? throw new Exception($"Certificate with thumbprint {Thumbprint} was not found");

    // Use certificate
    ViewData["certificateDetails"] = certificate.IssuerName.Name.ToString();
}

Informationen zum Laden eines TLS/SSL-Zertifikats aus einer Datei in Node.js, PHP, Python oder Java finden Sie in der Dokumentation für die jeweilige Sprache oder Webplattform.

Aktualisieren oder Erneuern eines Zertifikats

Wenn Sie ein Zertifikat erneuern und ihrer App hinzufügen, erhält es einen neuen Fingerabdruck, der auch zugänglich gemacht werden muss. Die Funktionsweise hängt vom Zertifikattyp ab.

Wenn Sie das öffentliche oder private Zertifikat manuell hochladen:

• Wenn Sie Fingerabdrücke explizit auflisten WEBSITE_LOAD_CERTIFICATES, fügen Sie den neuen Fingerabdruck zur App-Einstellung hinzu.
• Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, starten Sie die App neu, um das neue Zertifikat zugänglich zu machen.

Wenn Sie ein Zertifikat in Azure Key Vault verlängern, z. B. mit einem App Service-Zertifikat, nimmt die tägliche Synchronisierung durch Key Vault die erforderliche Aktualisierung automatisch vor, wenn Ihre App mit dem verlängerten Zertifikat synchronisiert wird.

• Wenn WEBSITE_LOAD_CERTIFICATES der alte Fingerabdruck Ihres erneuerten Zertifikats enthalten ist, aktualisiert die tägliche Synchronisierung den alten Fingerabdruck automatisch auf den neuen Fingerabdruck.
• Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, macht die tägliche Synchronisierung das neue Zertifikat automatisch verfügbar.

Verwandte Inhalte

• Enable HTTPS für eine benutzerdefinierte Domäne in Azure App Service
• Erzwingen von HTTPS
• TLS 1.2 erzwingen
• FAQ: Erstellen oder Löschen von Ressourcen in Azure App Service
• Referenz zu Umgebungsvariablen und App-Einstellungen