Używanie certyfikatu TLS/SSL w kodzie w usłudze Azure App Service

W kodzie aplikacji możesz uzyskać dostęp do certyfikatów publicznych lub prywatnych dodanych do usługi App Service. Kod aplikacji może działać jako klient i uzyskać dostęp do usługi zewnętrznej wymagającej uwierzytelniania certyfikatu lub może być konieczne wykonanie zadań kryptograficznych. W tym przewodniku z instrukcjami pokazano, jak używać certyfikatów publicznych lub prywatnych w kodzie aplikacji.

Takie podejście do używania certyfikatów w kodzie korzysta z funkcji PROTOKOŁU TLS w usłudze App Service, która wymaga, aby aplikacja znajdowała się w warstwie Podstawowa lub wyższej. Jeśli aplikacja znajduje się w warstwie Bezpłatna lub Współdzielona , możesz dołączyć plik certyfikatu do repozytorium aplikacji.

Gdy zezwolisz usłudze App Service na zarządzanie certyfikatami TLS/SSL, możesz obsługiwać certyfikaty i kod aplikacji oddzielnie oraz chronić poufne dane.

Wymagania wstępne

Aby postępować zgodnie z tym przewodnikiem z instrukcjami:

• Utwórz aplikację usługi App Service
• Dodawanie certyfikatu do aplikacji

Znajdowanie odcisku palca

W witrynie Azure Portal z menu po lewej stronie wybierz pozycję Nazwa> aplikacji usługi App Services<>.

W obszarze nawigacji po lewej stronie aplikacji wybierz pozycję Certyfikaty, a następnie wybierz pozycję Bring your own certificates (pfx) lub Public key certificates (.cer).

Znajdź certyfikat, którego chcesz użyć, i skopiuj odcisk palca.

Udostępnianie certyfikatu

Aby uzyskać dostęp do certyfikatu w kodzie aplikacji, dodaj jego odcisk palca do WEBSITE_LOAD_CERTIFICATES ustawienia aplikacji, uruchamiając następujące polecenie w usłudze Cloud Shell:

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

Aby udostępnić wszystkie certyfikaty, ustaw wartość na *.

Uwaga

Po WEBSITE_LOAD_CERTIFICATES ustawieniu *parametru wszystkie wcześniej dodane certyfikaty są dostępne dla kodu aplikacji. Jeśli później dodasz certyfikat do aplikacji, uruchom ponownie aplikację, aby nowy certyfikat był dostępny dla aplikacji. Aby uzyskać więcej informacji, zobacz Aktualizowanie (odnawianie) certyfikatu.

Ładowanie certyfikatu w aplikacjach systemu Windows

Ustawienie WEBSITE_LOAD_CERTIFICATES aplikacji sprawia, że określone certyfikaty są dostępne dla aplikacji hostowanej w systemie Windows w magazynie certyfikatów systemu Windows w obszarze Bieżący użytkownik\My.

W kodzie języka C# uzyskujesz dostęp do certyfikatu za pomocą odcisku palca certyfikatu. Poniższy kod ładuje certyfikat z odciskiem E661583E8FABEF4C0BEF694CBC41C28FB81CD870palca .

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
}

W kodzie Java uzyskujesz dostęp do certyfikatu z magazynu "Windows-MY" przy użyciu pola Nazwa pospolita podmiotu (zobacz Certyfikat klucza publicznego). Poniższy kod pokazuje, jak załadować certyfikat klucza prywatnego:

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
...

W przypadku języków, które nie obsługują magazynu certyfikatów systemu Windows lub oferują niewystarczającą obsługę, zobacz Ładowanie certyfikatu z pliku.

Ładowanie certyfikatu z pliku

Jeśli musisz załadować ręcznie przekazany plik certyfikatu, lepiej jest przekazać certyfikat przy użyciu usługi FTPS zamiast usługi Git, na przykład. Należy zachować poufne dane, takie jak certyfikat prywatny, poza kontrolą źródła.

Uwaga

ASP.NET i ASP.NET Core w systemie Windows muszą uzyskiwać dostęp do magazynu certyfikatów, nawet jeśli załadujesz certyfikat z pliku. Aby załadować plik certyfikatu w aplikacji .NET systemu Windows, załaduj bieżący profil użytkownika za pomocą następującego polecenia w usłudze Cloud Shell:

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

Takie podejście do używania certyfikatów w kodzie korzysta z funkcji PROTOKOŁU TLS w usłudze App Service, która wymaga, aby aplikacja znajdowała się w warstwie Podstawowa lub wyższej.

Poniższy przykład w języku C# ładuje certyfikat publiczny ze ścieżki względnej w aplikacji:

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

Aby dowiedzieć się, jak załadować certyfikat TLS/SSL z pliku w Node.js, PHP, Python lub Java, zobacz dokumentację odpowiedniego języka lub platformy internetowej.

Ładowanie certyfikatu w kontenerach systemu Linux/Windows

Ustawienie WEBSITE_LOAD_CERTIFICATES aplikacji sprawia, że określone certyfikaty są dostępne dla kontenerów niestandardowych systemu Windows lub Linux (w tym wbudowanych kontenerów systemu Linux) jako plików. Pliki znajdują się w następujących katalogach:

Platforma kontenerów	Certyfikaty publiczne	Certyfikaty prywatne
Kontener systemu Windows	C:\appservice\certificates\public	C:\appservice\certificates\private
Kontener systemu Linux	/var/ssl/certs	/var/ssl/private

Nazwy plików certyfikatów to odciski palca certyfikatu.

Uwaga

Usługa App Service wprowadza ścieżki certyfikatów do kontenerów systemu Windows jako następujące zmienne WEBSITE_PRIVATE_CERTS_PATHśrodowiskowe , WEBSITE_INTERMEDIATE_CERTS_PATH, WEBSITE_PUBLIC_CERTS_PATHi WEBSITE_ROOT_CERTS_PATH. Lepiej jest odwołać się do ścieżki certyfikatu ze zmiennymi środowiskowymi zamiast trwale połączyć ścieżkę certyfikatu, jeśli ścieżki certyfikatów zmienią się w przyszłości.

Ponadto kontenery systemów Windows Server Core i Windows Nano Server automatycznie ładują certyfikaty do magazynu certyfikatów w folderze LocalMachine\My. Aby załadować certyfikaty, postępuj zgodnie z tym samym wzorcem co Ładowanie certyfikatu w aplikacjach systemu Windows. W przypadku kontenerów opartych na systemie Windows Nano użyj tych ścieżek plików Załaduj certyfikat bezpośrednio z pliku.

Linux

Poniższy kod w języku C# pokazuje, jak załadować certyfikat publiczny w aplikacji systemu Linux.

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

Poniższy kod w języku C# pokazuje, jak załadować certyfikat prywatny w aplikacji systemu Linux.

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

Windows

W poniższym przykładzie w języku C# pokazano, jak załadować certyfikat publiczny w aplikacji .NET Framework w kontenerze windows Server Core.

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
}

W poniższym przykładzie w języku C# pokazano, jak załadować certyfikat publiczny w aplikacji .NET Core w kontenerze systemu Windows Server Core lub Windows Nano Server.

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

Aby dowiedzieć się, jak załadować certyfikat TLS/SSL z pliku w Node.js, PHP, Python lub Java, zobacz dokumentację odpowiedniego języka lub platformy internetowej.

Podczas aktualizowania (odnawiania) certyfikatu

Po odnowieniu certyfikatu i dodaniu go do aplikacji zostanie wyświetlony nowy odcisk palca, który również musi być dostępny. Sposób jego działania zależy od typu certyfikatu.

Jeśli ręcznie przekażesz certyfikat publiczny lub prywatny :

• Jeśli jawnie wyświetlisz odciski palca w programie WEBSITE_LOAD_CERTIFICATES, dodaj nowy odcisk palca do ustawienia aplikacji.
• Jeśli WEBSITE_LOAD_CERTIFICATES ustawiono wartość *, uruchom ponownie aplikację, aby udostępnić nowy certyfikat.

W przypadku odnowienia certyfikatu w usłudze Key Vault, takiego jak przy użyciu certyfikatu usługi App Service, codzienna synchronizacja z usługi Key Vault powoduje automatyczne zaktualizowanie niezbędnej aktualizacji podczas synchronizowania aplikacji z odnowionym certyfikatem.

• Jeśli WEBSITE_LOAD_CERTIFICATES zawiera stary odcisk palca odnowionego certyfikatu, codzienna synchronizacja automatycznie aktualizuje stary odcisk palca do nowego odcisku palca.
• Jeśli WEBSITE_LOAD_CERTIFICATES ustawiono wartość *, synchronizacja dzienna powoduje, że nowy certyfikat jest dostępny automatycznie.

Więcej zasobów

• Zabezpieczanie niestandardowej nazwy DNS przy użyciu powiązania TLS/SSL w usłudze aplikacja systemu Azure
• Wymuszanie protokołu HTTPS
• Wymuszanie protokołu TLS 1.1/1.2
• Często zadawane pytania: Certyfikaty usługi App Service
• Dokumentacja zmiennych środowiskowych i ustawień aplikacji