在 Azure 应用服务中通过代码使用 TLS/SSL 证书

在应用程序代码中，可以访问已添加到应用服务的公用证书或私用证书。 应用代码可以充当客户端并可访问需要证书身份验证的外部服务，否则可能需要执行加密任务。 本操作方法指南介绍如何在应用程序代码中使用公共或专用证书。

这种在代码中使用证书的方法利用了应用服务中的 TLS 功能，要求应用属于“基本”层或更高层。 如果应用位于“免费”或“共享”层，则你可以在应用存储库中包含证书文件。

让应用服务管理 TLS/SSL 证书时，可以分开维护证书和应用程序代码，并保护敏感数据。

先决条件

按照本操作方法指南操作：

• 创建应用服务应用
• 将证书添加到应用

查找指纹

在 Azure 门户的左侧菜单中，选择“应用程序服务”>“<app-name>”。

在应用的左侧导航栏中，选择“证书”，然后选择“自使用自己的证书(.pfx)”或“公钥证书(.cer)”。

找到要使用的证书并复制指纹。

使证书可供访问

若要在应用代码中访问某个证书，请在 Azure CLI 中运行以下命令，将其指纹添加到 WEBSITE_LOAD_CERTIFICATES 应用设置：

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

若要使所有证书可供访问，请将值设置为 *。

在 Windows 应用中加载证书

Current User\My 中的 Windows 证书存储中的 Windows 托管应用可以通过 WEBSITE_LOAD_CERTIFICATES 应用设置访问指定的证书。

在 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 上传证书。 应将专用证书之类的敏感信息置于源代码管理之外。

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

这种在代码中使用证书的方法利用了应用服务中的 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 Server Core 和 Windows Nano Server 容器会自动将证书加载到 LocalMachine\My 中的证书存储中。 若要加载证书，请遵循与在 Windows 应用中加载证书相同的模式。 对于基于 Windows Nano 的容器，请使用这些文件路径直接从文件加载证书。

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

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

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

若要了解如何从 Node.js、PHP、Python 或 Java 文件加载 TLS/SSL 证书，请参阅适用于相应语言或 Web 平台的文档。

更新（续订）证书时

续订证书并将其添加到应用时，它会获得一个新的指纹，该指纹也需要是可供访问的。 工作原理取决于证书类型。

如果手动上传公共或专用证书：

• 如果在 WEBSITE_LOAD_CERTIFICATES 中明确列出指纹，请将新指纹添加到应用设置中。
• 如果 WEBSITE_LOAD_CERTIFICATES 设置为 *，请重启应用以使新证书可供访问。

如果续订 Key Vault 中的证书（例如使用应用服务证书来这样做），则在将应用与续订的证书同步时，来自 Key Vault 的每日同步会自动进行必要的更新。

• 如果 WEBSITE_LOAD_CERTIFICATES 包含已续订证书的旧指纹，则每日同步会自动将旧指纹更新为新指纹。
• 如果 WEBSITE_LOAD_CERTIFICATES 设置为 *，则每日同步会自动使新证书可供访问。

更多资源

• 在 Azure 应用服务中使用 TLS/SSL 绑定保护自定义 DNS 名称
• 实施 HTTPS
• 实施 TLS 1.1/1.2
• 常见问题解答：应用服务证书
• 环境变量和应用设置参考