Verwenden von TLS/SSL-Zertifikaten im Anwendungscode

In Ihrem Anwendungscode können Sie auf die öffentlichen oder privaten Zertifikate zugreifen, die 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 öffentliche oder private 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/Secure Sockets Layer (SSL)-Zertifikate verwaltet, können Sie die Zertifikate und den Anwendungscode separat verwalten und Ihre vertraulichen Daten schützen.

Voraussetzungen

Um die Anweisungen in diesem Artikel zu befolgen, siehe:

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

Finde den Daumenabdruck

1. Wählen Sie im Azure-Portal im linken Bereich App Services><App-Name> aus.

2. Wählen Sie im linken Bereich Ihrer App "Zertifikate" aus. Wählen Sie dann Eigene Zertifikate mitbringen (.pfx) oder Öffentliche Schlüsselzertifikate (.cer) aus.

3. 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. Führen Sie den folgenden Befehl in Azure Cloud Shell aus:

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 von Windows gehostete App im Windows-Zertifikatspeicher in "Aktueller Benutzer\Mein" zugänglich.

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

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

string certThumbprint = "E661583E8FABEF4C0BEF694CBC41C28FB81CD870";
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 Feld "Windows-MY" auf das Zertifikat aus dem Store 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 nur 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 ein privates Zertifikat aus der Quellcodeverwaltung heraus.

ASP.NET und ASP.NET Core unter 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 in Cloud Shell:

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 bytes = File.ReadAllBytes("~/<relative-path-to-cert-file>");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

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.

Laden von Zertifikaten in Linux-/Windows-Containern

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

Containerplattform	Öffentliche Zertifikate	Private Zertifikate
Windows-Container	C:\appservice\certificates\public	C:\appservice\certificates\private
Linux-Container	/var/ssl/certs	/var/ssl/private

Die Zertifikatsdateinamen sind die Zertifikatfingerabdrücke.

Hinweis

Der App-Dienst fügt die Zertifikatpfade in Windows-Container als die folgenden Umgebungsvariablen ein: WEBSITE_PRIVATE_CERTS_PATH, , WEBSITE_INTERMEDIATE_CERTS_PATH, WEBSITE_PUBLIC_CERTS_PATHund WEBSITE_ROOT_CERTS_PATH. Es ist besser, auf den Zertifikatpfad mit den Umgebungsvariablen zu verweisen, anstatt den Zertifikatpfad zu hartcodieren, falls sich die Zertifikatpfade in Zukunft ändern.

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 dargestellt. Verwenden Sie für Windows Nano-basierte Container die Dateipfade wie im Laden eines Zertifikats aus einer Datei dargestellt.

Linux

Der folgende C#-Code zeigt, wie ein öffentliches Zertifikat in einer Linux-App geladen wird.

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

...
var bytes = File.ReadAllBytes("/var/ssl/certs/<thumbprint>.der");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

Der folgende C#-Code zeigt, wie ein privates Zertifikat in einer Linux-App geladen wird.

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;
...
var bytes = File.ReadAllBytes("/var/ssl/private/<thumbprint>.p12");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

Fenster

Das folgende C#-Beispiel zeigt, wie ein öffentliches Zertifikat in einer .NET Framework-App in einem Windows Server Core-Container geladen wird.

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
}

Das folgende C#-Beispiel zeigt, wie sie ein öffentliches Zertifikat in einer .NET Core-App in einem Windows Server Core- oder Windows Nano Server-Container laden.

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 im Azure Key Vault verlängern, z. B. mit einem App Service-Zertifikat, führt die tägliche Synchronisierung von Key Vault die erforderliche Aktualisierung automatisch durch, wenn Ihre App mit dem erneuerten 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

• Schützen eines benutzerdefinierten DNS-Namens mit einer TLS-/SSL-Bindung in Azure App Service
• Erzwingen von HTTPS
• Erzwingen von TLS 1.1/1.2
• Häufig gestellte Fragen: App Service-Zertifikate
• Referenz zu Umgebungsvariablen und App-Einstellungen