在 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>
若要使所有证书可供访问,请将值设置为 *
。
注意
将 WEBSITE_LOAD_CERTIFICATES
设置为 *
时,应用程序代码可以访问所有以前添加的证书。 如果稍后将证书添加到应用,请重启该应用,使新证书可供应用访问。 有关详细信息,请参阅更新(续订)证书时。
在 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 上传证书。 应将专用证书之类的敏感信息置于源代码管理之外。
注意
即使从文件加载证书,Windows 上的 ASP.NET 和 ASP.NET Core 也必须访问证书存储。 若要在 Windows .NET 应用中加载证书文件,请在 Azure CLI 中使用以下命令加载当前用户配置文件:
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 容器 | C:\appservice\certificates\public |
C:\appservice\certificates\private |
Linux 容器 | /var/ssl/certs |
/var/ssl/private |
证书文件名是证书指纹。
注意
应用服务将证书路径作为以下环境变量 WEBSITE_PRIVATE_CERTS_PATH
、WEBSITE_INTERMEDIATE_CERTS_PATH
、WEBSITE_PUBLIC_CERTS_PATH
和 WEBSITE_ROOT_CERTS_PATH
注入到 Windows 容器中。 最好使用环境变量引用证书路径,而不是对证书路径进行硬编码,以防将来证书路径发生更改。
此外,Windows Server Core 和 Windows Nano Server 容器会自动将证书加载到 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
设置为*
,请重启应用以使新证书可供访问。
如果续订 Key Vault 中的证书(例如使用应用服务证书来这样做),则在将应用与续订的证书同步时,来自 Key Vault 的每日同步会自动进行必要的更新。
- 如果
WEBSITE_LOAD_CERTIFICATES
包含已续订证书的旧指纹,则每日同步会自动将旧指纹更新为新指纹。 - 如果
WEBSITE_LOAD_CERTIFICATES
设置为*
,则每日同步会自动使新证书可供访问。