在 Azure App Service 的程式碼中使用 TLS/SSL 憑證

發行項
03/11/2024

在您的應用程式程式碼中，您可以存取您新增至 App Service 的公用或私人憑證。您的應用程式程式碼可以作為用戶端，並存取需要憑證驗證的外部服務，或其可能需要執行密碼編譯工作。本操作指南說明如何在您的應用程式程式碼中使用公用或私人憑證。

這種要在程式碼中使用憑證的方法會利用 App Service 中的 TLS 功能，這需要應用程式處於基本層或更高階層。如果您的應用程式處於免費或共用層，您可以在應用程式存放庫中包含憑證檔案。

當您讓 App Service 管理您的 TLS/SSL 憑證時，您可以分開維護憑證以及應用程式程式碼，並保護您的敏感性資料。

必要條件

若要遵循本操作說明指南：

尋找指紋

在 Azure 入口網站中，從左側功能表選取 [應用程式服務]><app-name>>。

從應用程式的左側導覽中，選取 [憑證]，然後選取 [自備憑證 (.pfx)] 或 [公開金鑰憑證 (.cer)]。

尋找您要使用的憑證並複製指紋。

Copy the certificate thumbprint

使憑證可供存取

若要在您的應用程式碼中存取憑證，請在 Cloud Shell 中執行下列命令，將其指紋新增至 WEBSITE_LOAD_CERTIFICATES 應用程式設定：

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

若要使您的所有憑證都可供存取，請將值設定為 *。

注意

將 WEBSITE_LOAD_CERTIFICATES 設定為 * 時，所有先前新增的憑證都可供應用程式程式碼存取。如果您稍後將憑證新增至應用程式，請重新啟動應用程式，讓應用程式能夠存取新的憑證。如需詳細資訊，請參閱更新憑證時。

在 Windows 應用程式中載入憑證

WEBSITE_LOAD_CERTIFICATES 應用程式設定可讓 Windows 憑證存放區 (位於目前使用者/我的) 中 Windows 裝載的應用程式存取指定的憑證。

在 C# 程式碼中，您可以透過憑證指紋來存取憑證。下列程式碼會載入指紋為 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
}

在 Java 程式碼中，您可以使用 [主體一般名稱] 欄位，從 "Windows-MY" 存放區存取憑證 (請參閱公開金鑰憑證)。下列程式碼說明如何載入私密金鑰憑證：

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

如需不支援或不足以支援 Windows 憑證存放區的語言，請參閱從檔案載入憑證。

從檔案載入憑證

如果您需要載入您手動上傳的憑證檔案，最好是使用 FTPS 而非例如 Git 上傳憑證。您應該讓敏感性資料就像私人憑證不在原始檔控制中。

注意

即使您從檔案載入憑證，Windows 上的 ASP.NET 和 ASP.NET Core 仍須存取憑證存放區。若要在 Windows .NET 應用程式中載入憑證檔案，請在 Cloud Shell 中使用下列命令載入目前的使用者設定檔：

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

這種要在程式碼中使用憑證的方法會利用 App Service 中的 TLS 功能，這需要應用程式處於基本層或更高階層。

下列 C# 範例會從應用程式中的相對路徑載入公開憑證：

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

若要查看如何從 Node.js、PHP、Python 或 Java 中的檔案載入 TLS/SSL 憑證，請參閱個別語言或 Web 平台的文件。

在 Linux/Windows 容器中載入憑證

WEBSITE_LOAD_CERTIFICATES 應用程式設定可讓 Windows 或 Linux 自訂容器 (包含內建 Linux 容器) 存取指定的憑證，如同檔案一樣。這些檔案可在下列目錄底下找到：

容器平台	公開憑證	私人憑證
Windows 容器	`C:\appservice\certificates\public`	`C:\appservice\certificates\private`
Linux 容器	`/var/ssl/certs`	`/var/ssl/private`

憑證檔案名稱是憑證指紋。

注意

App Service將憑證路徑插入至 Windows 容器，作為下列環境變數 WEBSITE_PRIVATE_CERTS_PATHWEBSITE_INTERMEDIATE_CERTS_PATHWEBSITE_PUBLIC_CERTS_PATH 和 WEBSITE_ROOT_CERTS_PATH。最好是使用環境變數來參考憑證路徑，而不是硬式編碼憑證路徑，以防未來憑證路徑變更。

此外，Windows Server Core 容器會在 LocalMachine\My 中自動將憑證載入至憑證存放區。若要載入憑證，請遵循與在 Windows 應用程式中載入憑證相同的模式。若為 Windows Nano 型容器，請使用這些檔案路徑直接從檔案載入憑證。

下列 C# 程式碼說明如何在 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

下列 C# 程式碼說明如何在 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

若要查看如何從 Node.js、PHP、Python 或 Java 中的檔案載入 TLS/SSL 憑證，請參閱個別語言或 Web 平台的文件。

更新憑證時

當您更新憑證並將其新增至應用程式時，其會取得新的指紋，同時也必須將該指紋設為可供存取。其運作方式取決於憑證類型。

如果您手動上傳公用或私人憑證：

如果您在 WEBSITE_LOAD_CERTIFICATES 中明確列出指紋，請將新的指紋新增至應用程式設定。
如果將 WEBSITE_LOAD_CERTIFICATES 設定為 *，請重新啟動應用程式，讓新的憑證可供存取。

如果您在金鑰保存庫中更新憑證，例如使用 App Service 憑證，則來自金鑰保存庫的每日同步處理會在同步處理應用程式與更新的憑證時自動進行必要的更新。

如果 WEBSITE_LOAD_CERTIFICATES 包含更新憑證的舊指紋，則每日同步處理會自動將舊的指紋更新為新的指紋。
如果將 WEBSITE_LOAD_CERTIFICATES 設定為 *，則每日同步處理會自動將新的憑證設為可供存取。