将群集证书从基于指纹的声明转换为公用名Convert cluster certificates from thumbprint-based declarations to common names

证书的签名(通常称为指纹)是唯一的。The signature of a certificate (commonly known as a thumbprint) is unique. 指纹声明的群集证书指的是证书的特定实例。A cluster certificate declared by thumbprint refers to a specific instance of a certificate. 由于这种特异性,证书滚动更新和常规管理变得很困难,必须采取显式方式。This specificity makes certificate rollover, and management in general, difficult and explicit. 每个更改都需要协调群集和基础计算主机的升级。Each change requires orchestrating upgrades of the cluster and the underlying computing hosts.

将 Azure Service Fabric 群集的证书声明从基于指纹转换为基于证书使用者公用名 (CN) 的声明可显著简化管理。Converting an Azure Service Fabric cluster's certificate declarations from thumbprint-based to declarations based on the certificate's subject common name (CN) simplifies management considerably. 特别是,滚动更新证书不再需要群集升级。In particular, rolling over a certificate no longer requires a cluster upgrade. 本文介绍了如何在不停机的情况下将现有群集转换为基于 CN 的声明。This article describes how to convert an existing cluster to CN-based declarations without downtime.

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

迁移到证书颁发机构签名的证书Move to certificate authority-signed certificates

其证书由指纹声明的群集的安全性依赖于以下事实:伪造与另一证书具有相同签名的证书是不可能的,或者在计算上是不可行的。The security of a cluster whose certificate is declared by thumbprint rests on the fact that it's impossible, or computationally unfeasible, to forge a certificate with the same signature as another one. 在这种情况下,证书的来源不太重要,因此,自签名证书就足够了。In this case, the provenance of the certificate is less important, so self-signed certificates are adequate.

相对而言,其证书通过 CN 进行声明的群集的安全性源自群集所有者对其证书提供者的隐式信任。By contrast, the security of a cluster whose certificates are declared by CN flows from the implicit trust the cluster owner has in their certificate provider. 提供者是颁发证书的公钥基础结构 (PKI) 服务。The provider is the public key infrastructure (PKI) service that issued the certificate. 除其他因素外,信任还基于 PKI 的认证实践、是否由其他受信任方审核和批准其操作安全性,等等。Trust is based, among other factors, on the PKI's certification practices, whether their operational security is audited and approved by yet-other trusted parties, and so on.

群集所有者还必须详细了解哪些证书颁发机构 (CA) 在颁发其证书,因为这是按使用者验证证书的基本要求。The cluster owner must also have detailed knowledge of which certificate authorities (CAs) are issuing their certificates, since this is a fundamental aspect of validating certificates by subject. 这也意味着自签名证书完全不适用。This also implies that self-signed certificates are wholly unsuitable for this purpose. 不夸张地说,任何人都可以生成具有给定使用者的证书。Literally anyone can generate a certificate with a given subject.

在以下情况下,由 CN 声明的证书通常被视为有效证书:A certificate declared by CN is typically considered valid if:

  • 它的链可以成功生成。Its chain can be built successfully.
  • 使用者具有预期的 CN 元素。The subject has the expected CN element.
  • 执行验证的代理信任其颁发者(链中的直接颁发者或更高级别颁发者)。Its issuer (immediate or higher in the chain) is trusted by the agent performing the validation.

Service Fabric 支持以两种方式通过 CN 声明证书:Service Fabric supports declaring certificates by CN in two ways:

  • 使用隐式颁发者,这意味着链必须以信任定位点结束。With implicit issuers, which means the chain must end in a trust anchor.
  • 使用由指纹声明的颁发者(称为颁发者固定)。With issuers declared by thumbprint, which is known as issuer pinning.

有关详细信息,请参阅基于公用名的证书验证声明For more information, see Common-name-based certificate validation declarations.

若要使用由指纹声明的自签名证书将群集转换为 CN(目标),必须先通过指纹将 CA 签名的证书引入到群集中。To convert a cluster by using a self-signed certificate declared by thumbprint to CN, the target, CA-signed certificate must be first introduced into the cluster by thumbprint. 只有这样才可以从指纹转换为 CN。Only then is the conversion from thumbprint to CN possible.

对于测试用途,自签名证书可以由 CN 声明,但前提是颁发者已固定到其自己的指纹。For testing purposes, a self-signed certificate could be declared by CN, but only if the issuer is pinned to its own thumbprint. 从安全角度来看,此操作几乎相当于通过指纹声明相同的证书。From a security standpoint, this action is nearly equivalent to declaring the same certificate by thumbprint. 此类型的成功转换不保证能够使用 CA 签名的证书成功地从指纹转换为 CN。A successful conversion of this kind doesn't guarantee a successful conversion from thumbprint to CN with a CA-signed certificate. 建议使用正确的由 CA 签名的证书来测试转换。We recommend you test conversion with a proper, CA-signed certificate. 此测试存在免费选项。Free options exist for this testing.

上传证书并将其安装在规模集中Upload the certificate and install it in the scale set

在 Azure 中,用于获取和预配证书的推荐机制涉及 Azure Key Vault 及其工具。In Azure, the recommended mechanism for obtaining and provisioning certificates involves Azure Key Vault and its tooling. 与群集证书声明匹配的证书必须预配到构成群集的虚拟机规模集的每个节点。A certificate matching the cluster certificate declaration must be provisioned to every node of the virtual machine scale sets that comprise your cluster. 有关详细信息,请参阅虚拟机规模集上的机密For more information, see Secrets on virtual machine scale sets.

在群集的证书声明中进行更改之前,必须在群集的每个节点类型的虚拟机上安装当前群集证书和目标群集证书。It's important to install both current and target cluster certificates on the virtual machines of every node type of the cluster before you make changes in the cluster's certificate declarations. 证书的旅程中深入讨论了从证书颁发到预配到 Service Fabric 节点中这一段旅程。The journey from certificate issuance to provisioning onto a Service Fabric node is discussed in depth in The journey of a certificate.

使群集进入最佳起始状态Bring the cluster to an optimal starting state

将证书声明从基于指纹转换为基于 CN 将影响:Converting a certificate declaration from thumbprint-based to CN-based impacts:

  • 群集中的每个节点如何查找其凭据并将其提供给其他节点。How each node in the cluster finds and presents its credentials to other nodes.
  • 建立安全连接后,每个节点如何验证其对应节点的凭据。How each node validates the credentials of its counterpart upon establishing a secure connection.

继续操作之前,请查看两种配置的表示和验证规则Review the presentation and validation rules for both configurations before you proceed. 执行从指纹到 CN 的转换时,最重要的注意事项是已升级的和尚未升级的节点(即属于不同升级域的节点)必须能够在升级过程中的任何时候执行成功的相互身份验证。The most important consideration when you perform a thumbprint-to-CN conversion is that upgraded and not-yet-upgraded nodes (that is, nodes belonging to different upgrade domains) must be able to perform successful mutual authentication at any time during the upgrade. 实现此行为的建议方法是在初始升级时通过指纹声明目标证书。The recommended way to achieve this behavior is to declare the target or goal certificate by thumbprint in an initial upgrade. 然后,在后续升级中完成到 CN 的转换。Then complete the transition to CN in a subsequent one. 如果群集已处于建议的起始状态,你可以跳过此部分。If the cluster is already in a recommended starting state, you can skip this section.

一个转换有多个有效的起始状态。There are multiple valid starting states for a conversion. 不变的是,在开始升级到 CN 时,群集已经在使用目标证书(通过指纹声明的)。The invariant is that the cluster is already using the target certificate (declared by thumbprint) at the start of the upgrade to CN. 在本文中,我们会考虑 GoalCertOldCert1OldCert2We consider GoalCert, OldCert1, and OldCert2 in this article.

有效的起始状态Valid starting states

  • Thumbprint: GoalCert, ThumbprintSecondary: None
  • Thumbprint: GoalCert, ThumbprintSecondary: OldCert1,其中的 GoalCert 具有比 OldCert1 的日期更晚的 NotBefore 日期Thumbprint: GoalCert, ThumbprintSecondary: OldCert1, where GoalCert has a later NotBefore date than that of OldCert1
  • Thumbprint: OldCert1, ThumbprintSecondary: GoalCert,其中的 GoalCert 具有比 OldCert1 的日期更晚的 NotBefore 日期Thumbprint: OldCert1, ThumbprintSecondary: GoalCert, where GoalCert has a later NotBefore date than that of OldCert1

备注

在版本 7.2.445 (7.2 CU4) 之前,Service Fabric 选择了最后面的即将到期的证书(具有最远的“NotAfter”属性的证书),因此上述 7.2 CU4 之前的起始状态要求 GoalCert 的 NotAfter 日期晚于 OldCert1Prior to version 7.2.445 (7.2 CU4), Service Fabric selected the farthest expiring certificate (the certificate with the farthest 'NotAfter' property), so the above starting states prior to 7.2 CU4 require GoalCert to have a later NotAfter date than OldCert1

如果你的群集未处于前面所述的有效状态之一,请参阅本文末尾部分关于如何实现该状态的内容。If your cluster isn't in one of the valid states previously described, see information on achieving that state in the section at the end of this article.

选择所需的基于 CN 的证书验证方案Select the desired CN-based certificate validation scheme

如前文所述,Service Fabric 支持通过 CN 和隐式信任定位点来声明证书,或者通过 CN 和显式固定颁发者指纹来声明证书。As described previously, Service Fabric supports declaring certificates by CN with an implicit trust anchor or with explicitly pinning the issuer thumbprints. 有关详细信息,请参阅基于公用名的证书验证声明For more information, see Common-name-based certificate validation declarations.

请确保你很好地了解选择任一机制的差别和影响。Ensure you have a good understanding of the differences and the implications of choosing either mechanism. 从语法上讲,这种差异或选择取决于 certificateIssuerThumbprintList 参数的值。Syntactically, this difference or choice is determined by the value of the certificateIssuerThumbprintList parameter. 为空表示依赖于受信任的根 CA (信任定位点),而一组指纹会限制允许的群集证书直接颁发者。Empty means relying on a trusted root CA (trust anchor), whereas a set of thumbprints restricts the allowed direct issuers of cluster certificates.

> [!NOTE]
> The `certificateIssuerThumbprint` field allows you to specify the expected direct issuers of certificates declared by subject CN. Acceptable values are one or more comma-separated SHA1 thumbprints. This action strengthens the certificate validation.
>
> If no issuers are specified or the list is empty, the certificate will be accepted for authentication if its chain can be built. The certificate then ends up in a root trusted by the validator. If one or more issuer thumbprints are specified, the certificate will be accepted if the thumbprint of its direct issuer, as extracted from the chain, matches any of the values specified in this field. The certificate will be accepted whether the root is trusted or not.
>
> A PKI might use different certification authorities (also known as *issuers*) to sign certificates with a given subject. For this reason, it's important to specify all expected issuer thumbprints for that subject. In other words, the renewal of a certificate isn't guaranteed to be signed by the same issuer as the certificate being renewed.
>
> Specifying the issuer is considered a best practice. Omitting the issuer will continue to work for certificates chaining up to a trusted root, but this behavior has limitations and might be phased out in the near future. Clusters deployed in Azure, secured with X509 certificates issued by a private PKI, and declared by subject might not be able to be validated by Service Fabric (for cluster-to-service communication). Validation requires the PKI's certificate policy to be discoverable, available, and accessible.

更新群集的 Azure 资源管理器模板并进行部署Update the cluster's Azure Resource Manager template and deploy

使用 Azure 资源管理器 (ARM) 模板管理 Service Fabric 群集。Manage your Service Fabric clusters with Azure Resource Manager (ARM) templates. 另一种方法(也使用 JSON 项目)是 Azure 资源浏览器(预览版)An alternative, which also uses JSON artifacts, is the Azure Resource Explorer (preview). Azure 门户目前未提供等效的体验。An equivalent experience isn't available in the Azure portal at this time.

如果与现有群集相对应的原始模板不可用,则可以在 Azure 门户中获取等效模板。If the original template corresponding to an existing cluster isn't available, an equivalent template can be obtained in the Azure portal. 转到包含该群集的资源组,然后从左侧的“自动化”菜单中选择“导出模板”。Go to the resource group that contains the cluster, and select Export template from the Automation menu on the left. 然后选择所需的资源。Then select the resources you want. 至少应分别导出虚拟机规模集和群集资源。At a minimum, the virtual machine scale set and cluster resources, respectively, should be exported. 还可以下载生成的模板。The generated template can also be downloaded. 此模板可能需要更改才能完全部署。This template might require changes before it's fully deployable. 此模板也可能与原始模板不完全匹配。The template also might not match the original one exactly. 它反映群集资源的当前状态。It's a reflection of the current state of the cluster resource.

必要的更改如下所示:The necessary changes are as follows:

  • 更新 Service Fabric 节点扩展(在虚拟机资源下)的定义。Updating the definition of the Service Fabric node extension (under the virtual machine resource). 如果群集定义了多个节点类型,则需要更新每个相应虚拟机规模集的定义。If the cluster defines multiple node types, you'll need to update the definition of each corresponding virtual machine scale set.
  • 更新群集资源定义。Updating the cluster resource definition.

此处提供了详细的示例。Detailed examples are included here.

更新虚拟机规模集资源Update the virtual machine scale set resources

发件人:From:

"virtualMachineProfile": {
        "extensionProfile": {
            "extensions": [
                {
                    "name": "[concat('ServiceFabricNodeVmExt','_vmNodeType0Name')]",
                    "properties": {
                        "type": "ServiceFabricNode",
                        "autoUpgradeMinorVersion": true,
                        "protectedSettings": {
                            ...
                        },
                        "publisher": "Microsoft.Azure.ServiceFabric",
                        "settings": {
                            ...
                            "certificate": {
                                "thumbprint": "[parameters('certificateThumbprint')]",
                                "x509StoreName": "[parameters('certificateStoreValue')]"
                            }
                        },
                        ...
                    }
                },

到:To:

"virtualMachineProfile": {
        "extensionProfile": {
            "extensions": [
                {
                    "name": "[concat('ServiceFabricNodeVmExt','_vmNodeType0Name')]",
                    "properties": {
                        "type": "ServiceFabricNode",
                        "autoUpgradeMinorVersion": true,
                        "protectedSettings": {
                            ...
                        },
                        "publisher": "Microsoft.Azure.ServiceFabric",
                        "settings": {
                            ...
                            "certificate": {
                                "commonNames": [
                                    "[parameters('certificateCommonName')]"
                                ],
                                "x509StoreName": "[parameters('certificateStoreValue')]"
                            }
                        },
                        ...
                    }
                },

更新群集资源Update the cluster resource

Microsoft.ServiceFabric/clusters 资源中,添加一个具有 commonNames 设置的 certificateCommonNames 属性,然后删除 certificate 属性(及其所有设置)。In the Microsoft.ServiceFabric/clusters resource, add a certificateCommonNames property with a commonNames setting, and remove the certificate property altogether (all its settings).

发件人:From:

    {
        "apiVersion": "2018-02-01",
        "type": "Microsoft.ServiceFabric/clusters",
        "name": "[parameters('clusterName')]",
        "location": "[parameters('clusterLocation')]",
        "dependsOn": [
            ...
        ],
        "properties": {
            "addonFeatures": [
                ...
            ],
            "certificate": {
              "thumbprint": "[parameters('certificateThumbprint')]",
              "x509StoreName": "[parameters('certificateStoreValue')]"
            },
        ...

到:To:

    {
        "apiVersion": "2018-02-01",
        "type": "Microsoft.ServiceFabric/clusters",
        "name": "[parameters('clusterName')]",
        "location": "[parameters('clusterLocation')]",
        "dependsOn": [
            ...
        ],
        "properties": {
            "addonFeatures": [
                ...
            ],
            "certificateCommonNames": {
                "commonNames": [
                    {
                        "certificateCommonName": "[parameters('certificateCommonName')]",
                        "certificateIssuerThumbprint": "[parameters('certificateIssuerThumbprintList')]"
                    }
                ],
                "x509StoreName": "[parameters('certificateStoreValue')]"
            },
        ...

有关详细信息,请参阅部署使用证书公用名称而非指纹的 Service Fabric 群集For more information, see Deploy a Service Fabric cluster that uses certificate common name instead of thumbprint.

部署已更新的模板Deploy the updated template

在进行更改后,请重新部署已更新的模板。Redeploy the updated template after you make the changes.

$groupname = "sfclustertutorialgroup"

New-AzResourceGroupDeployment -ResourceGroupName $groupname -Verbose `
    -TemplateParameterFile "C:\temp\cluster\parameters.json" -TemplateFile "C:\temp\cluster\template.json" 

实现将群集转换为基于 CN 的证书声明的有效起始状态Achieve a valid starting state for converting a cluster to CN-based certificate declarations

开始状态Starting state 升级 1Upgrade 1 升级 2Upgrade 2
Thumbprint: OldCert1, ThumbprintSecondary: NoneGoalCert 具有比 OldCert1 晚的 NotBefore 日期Thumbprint: OldCert1, ThumbprintSecondary: None and GoalCert has a later NotBefore date than OldCert1 Thumbprint: OldCert1, ThumbprintSecondary: GoalCert -
Thumbprint: OldCert1, ThumbprintSecondary: NoneOldCert1 具有比 GoalCert 晚的 NotBefore 日期Thumbprint: OldCert1, ThumbprintSecondary: None and OldCert1 has a later NotBefore date than GoalCert Thumbprint: GoalCert, ThumbprintSecondary: OldCert1 Thumbprint: GoalCert, ThumbprintSecondary: None
Thumbprint: OldCert1, ThumbprintSecondary: GoalCert,其中的 OldCert1 具有比 GoalCert 晚的 NotBefore 日期Thumbprint: OldCert1, ThumbprintSecondary: GoalCert, where OldCert1 has a later NotBefore date than GoalCert 升级到 Thumbprint: GoalCert, ThumbprintSecondary: NoneUpgrade to Thumbprint: GoalCert, ThumbprintSecondary: None -
Thumbprint: GoalCert, ThumbprintSecondary: OldCert1,其中的 OldCert1 具有比 GoalCert 晚的 NotBefore 日期Thumbprint: GoalCert, ThumbprintSecondary: OldCert1, where OldCert1 has a later NotBefore date than GoalCert 升级到 Thumbprint: GoalCert, ThumbprintSecondary: NoneUpgrade to Thumbprint: GoalCert, ThumbprintSecondary: None -
Thumbprint: OldCert1, ThumbprintSecondary: OldCert2 删除 OldCert1OldCert2 以达到状态 Thumbprint: OldCertx, ThumbprintSecondary: NoneRemove one of OldCert1 or OldCert2 to get to state Thumbprint: OldCertx, ThumbprintSecondary: None 从新的起始状态继续Continue from the new starting state

备注

对于 7.2.445 (7.2 CU4) 之前版本上的群集,在上述状态下,将 NotBefore 替换为 NotAfterFor a cluster on a version prior to version 7.2.445 (7.2 CU4), replace NotBefore with NotAfter in the above states.

有关如何执行这些升级中的任一升级的说明,请参阅管理 Azure Service Fabric 群集中的证书For instructions on how to carry out any of these upgrades, see Manage certificates in an Azure Service Fabric cluster.

后续步骤Next steps