Verwenden eines TLS-/SSL-Zertifikats in Ihrem Code in Azure App Service

  • Artikel

Sie können in Ihrem Anwendungscode auf die öffentlichen oder privaten Zertifikate zugreifen, die Sie App Service hinzufügen. Der App-Code kann als Client fungieren und auf einen externen Dienst mit erforderlicher Zertifikatauthentifizierung zugreifen oder ggf. kryptografische Aufgaben ausführen. Diese Schrittanleitung zeigt, wie Sie öffentliche oder private Zertifikate in Ihrem Anwendungscode verwenden.

Bei der Verwendung von Zertifikaten in Ihrem Code wird die TLS-Funktionalität in App Service genutzt. Dazu muss Ihre App auf der Ebene Basic oder höher ausgeführt werden. Befindet sich Ihre App in der Ebene Free oder Shared, können Sie die Zertifikatsdatei in Ihr App-Repository aufnehmen.

Wenn Sie Ihre TLS-/SSL-Zertifikate über App Service verwalten, können Sie die Zertifikate und Ihren Anwendungscode separat verwalten und Ihre sensiblen Daten schützen.

Voraussetzungen

Im Rahmen dieser Schrittanleitung müssen Sie folgende Schritte durchführen:

Ermitteln des Fingerabdrucks

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

Wählen Sie in der linken Navigation Ihrer App Zertifikate und dann Eigene Zertifikate (.pfx) mitbringen oder Öffentliche Zertifikatsschlüssel (.cer) aus.

Ermitteln Sie das Zertifikat, das Sie verwenden möchten, und kopieren Sie den Fingerabdruck des Zertifikats.

Copy the certificate thumbprint

Sicherstellen, dass auf das Zertifikat zugegriffen werden kann

Fügen Sie zum Zugreifen auf ein Zertifikat in Ihrem App-Code der App-Einstellung WEBSITE_LOAD_CERTIFICATES den Fingerabdruck hinzu, indem Sie den folgenden Befehl in 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>

Damit auf alle Zertifikate zugegriffen werden kann, legen Sie den Wert auf * fest.

Hinweis

Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, kann auf alle zuvor hinzugefügten Zertifikate durch Anwendungscode zugegriffen werden. 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 (Verlängern) eines Zertifikats.

Laden eines Zertifikats in Windows-Apps

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

In C#-Code greifen Sie auf das Zertifikat anhand des Zertifikatfingerabdrucks 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 den Speicher „Windows-MY“ unter Verwendung des Felds für den Antragstellernamen auf das Zertifikat zu (siehe Öffentliches Schlüsselzertifikat). Der folgende Code zeigt, wie Sie ein Zertifikat für einen privaten Schlüssel laden:

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 keine Unterstützung oder nur unzureichende Unterstützung für den Windows-Zertifikatspeicher bieten, finden Sie unter Laden des Zertifikats aus einer Datei.

Laden des Zertifikats aus einer Datei

Wenn Sie eine manuell hochgeladene Zertifikatsdatei laden müssen, sollte der Upload eher über FTPS statt beispielsweise über Git erfolgen. Halten Sie vertrauliche Daten wie beispielsweise ein privates Zertifikat aus der Quellcodeverwaltung heraus.

Hinweis

ASP.NET und ASP.NET Core unter Windows müssen auf den Zertifikatspeicher auch dann zugreifen, wenn Sie ein Zertifikat aus einer Datei laden. Laden Sie zum Laden einer Zertifikatsdatei in eine Windows .NET-App 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

Bei der Verwendung von Zertifikaten in Ihrem Code wird die TLS-Funktionalität in App Service genutzt. Dazu muss Ihre App auf der Ebene Basic oder höher ausgeführt werden.

Im folgenden C#-Beispiel wird ein öffentliches Zertifikat aus einem relativen Pfad in die 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

Wie Sie ein TLS/SSL-Zertifikat aus einer Datei in Node.js, PHP, Python oder Java laden können, erfahren Sie in der Dokumentation der jeweiligen Sprache oder Webplattform.

Laden eines Zertifikats in Linux-/Windows-Containern

Die WEBSITE_LOAD_CERTIFICATES App-Einstellung macht die angegebenen Zertifikate für Ihre benutzerdefinierten Windows- oder Linux-Container (einschließlich integrierte Linux-Container) als Dateien zugänglich. Die Dateien befinden sich in 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

Von App Service werden die Zertifikatpfade in Windows-Container als Umgebungsvariablen (WEBSITE_PRIVATE_CERTS_PATH, WEBSITE_INTERMEDIATE_CERTS_PATH, WEBSITE_PUBLIC_CERTS_PATH und WEBSITE_ROOT_CERTS_PATH) eingefügt. Für den Fall, dass sich die Zertifikatpfade später ändern, ist es besser, auf den Zertifikatpfad mit den Umgebungsvariablen zu verweisen, anstatt einen hartcodierten Zertifikatpfad zu verwenden.

Darüber hinaus laden Windows Server Core-Container die Zertifikate automatisch in den Zertifikatspeicher (in LocalMachine\My). Verwenden Sie zum Laden der Zertifikate das gleiche Muster wie beim Laden eines Zertifikats in Windows-Apps. Verwenden Sie für Windows Nano-basierte Container diese Dateipfade, um das Zertifikat direkt aus der Datei zu laden.

Der folgende C#-Code zeigt, wie ein öffentliches Zertifikat in eine 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 eine 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

Wie Sie ein TLS/SSL-Zertifikat aus einer Datei in Node.js, PHP, Python oder Java laden können, erfahren Sie in der Dokumentation der jeweiligen Sprache oder Webplattform.

Aktualisieren (Verlängern) eines Zertifikats

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

Wenn Sie das öffentliche oder private Zertifikat manuell hochladen:

  • Wenn Sie Fingerabdrücke explizit in WEBSITE_LOAD_CERTIFICATES auflisten, fügen Sie der App-Einstellung den neuen Fingerabdruck hinzu.
  • Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, starten Sie die App neu, um Zugriff auf das neue Zertifikat zu ermöglichen.

Wenn Sie ein Zertifikat in Key Vault erneuern, z. B. mit einem App Service-Zertifikat, führt die tägliche Synchronisierung von Key Vault das erforderliche Update automatisch durch, wenn Ihre App mit dem erneuerten Zertifikat synchronisiert wird.

  • Wenn WEBSITE_LOAD_CERTIFICATES den alten Fingerabdruck Ihres erneuerten Zertifikats enthält, aktualisiert die tägliche Synchronisierung den alten Fingerabdruck automatisch auf den neuen Fingerabdruck.
  • Wenn WEBSITE_LOAD_CERTIFICATES auf * festgelegt ist, wird der Zugriff auf das neue Zertifikat durch die tägliche Synchronisierung automatisch ermöglicht.

Weitere Ressourcen