如何在 Azure Stack Hub 上为 IoT 中心轮换机密How to rotate secrets for IoT Hub on Azure Stack Hub

重要

Azure Stack Hub 上的 IoT 中心目前为预览版,在预览期间可免费使用。IoT Hub on Azure Stack Hub is currently in preview, and is provided free during the preview period.

本文将演示如何轮换 IoT 中心资源提供程序使用的机密。This article will show you how to rotate the secrets used by the IoT Hub resource provider.

概述与先决条件Overview and prerequisites

备注

当前仅通过 PowerShell 支持增值资源提供程序的机密轮换。Secret rotation for value-add resource providers is currently only supported via PowerShell.

与 Azure Stack Hub 基础结构一样,增值资源提供程序同时使用内部和外部机密。Like the Azure Stack Hub infrastructure, value-add resource providers use both internal and external secrets. 机密可以采取多种形式,包括密码和通过 X509 证书维护的加密密钥。Secrets can take multiple forms, including passwords and the encryption keys maintained by X509 certificates. 作为操作员,你负责:As an operator, you're responsible for:

  • 提供更新的外部机密,如用于保护资源提供程序终结点的新 TLS 证书。Providing updated external secrets, such as a new TLS certificate used to secure resource provider endpoints.
  • 定期管理资源提供程序机密轮换。Managing resource provider secret rotation on a regular basis.

在准备轮换的过程中:In preparation for the rotation process:

  1. 在获取/续订 X509 证书之前,请查看 Azure Stack Hub 公钥基础结构 (PKI) 证书要求以获取重要的先决条件信息,包括有关所需 PFX 格式的详细信息。Review Azure Stack Hub public key infrastructure (PKI) certificate requirements for important prerequisite information before acquiring/renewing your X509 certificate, including details on the required PFX format. 还要查看在“可选 PaaS 证书”部分中为你的特定增值资源提供程序指定的要求。Also review the requirements specified in the Optional PaaS certificates section, for your specific value-add resource provider.

  2. 在继续操作之前,请为 Azure Stack Hub 安装 PowerShell Az 模块(如果尚未这样做)。If you haven't already, Install PowerShell Az module for Azure Stack Hub before continuing. Azure Stack Hub 机密轮换需要 2.0.2-preview 或更高版本。Version 2.0.2-preview or later is required for Azure Stack Hub secret rotation. 有关详细信息,请参阅在 Azure Stack Hub 中从 AzureRM 迁移到 Azure PowerShell AzFor more information, see Migrate from AzureRM to Azure PowerShell Az in Azure Stack Hub.

准备新的 TLS 证书Prepare a new TLS certificate

接下来,创建或续订 TLS 证书,以保护增值资源提供程序终结点:Next, create or renew your TLS certificate for securing the value-add resource provider endpoints:

  1. 完成为资源提供程序的证书续订生成证书签名请求 (CSR) 中的步骤。Complete the steps in Generate certificate signing requests (CSRs) for certificate renewal for your resource provider. 在这里,可使用 Azure Stack Hub 就绪性检查器工具来创建 CSR。Here you use the Azure Stack Hub Readiness Checker tool to create the CSR. 请确保在“为其他 Azure Stack Hub 服务生成证书请求”步骤中为资源提供程序运行正确的 cmdlet。Be sure to run the correct cmdlet for your resource provider, in the step "Generate certificate requests for other Azure Stack Hub services". 例如,New-AzsHubEventHubsCertificateSigningRequest 用于事件中心。For example New-AzsHubEventHubsCertificateSigningRequest is used for Event Hubs. 完成后,将生成的 .REQ 文件提交到新证书的证书颁发机构 (CA)。When finished, you submit the generated .REQ file to your Certificate Authority (CA) for the new certificate.

  2. 收到来自 CA 的证书文件后,请完成为部署或轮换准备证书中的步骤。Once you've received your certificate file from the CA, complete the steps in Prepare certificates for deployment or rotation. 再次使用就绪性检查器工具处理从 CA 返回的文件。You use the Readiness Checker tool again, to process the file returned from the CA.

  3. 最后,完成验证 Azure Stack Hub PKI 证书中的步骤。Finally, complete the steps in Validate Azure Stack Hub PKI certificates. 再次使用就绪性检查器工具对新证书执行验证测试。You use the Readiness Checker tool once more, to perform validation tests on your new certificate.

轮换机密Rotate secrets

最后,确定资源提供程序的最新部署属性,并使用它们来完成机密轮换过程。Finally, determine the resource provider's latest deployment properties and use them to complete the secret rotation process.

确定部署属性Determine deployment properties

资源提供程序会作为已进行版本控制的产品包部署到 Azure Stack Hub 环境。Resource providers are deployed into your Azure Stack Hub environment as a versioned product package. 包会被分配一个唯一的包 ID(格式为 '<product-id>.<installed-version>')。Packages are assigned a unique package ID, in the format '<product-id>.<installed-version>'. 其中 <product-id> 是表示资源提供程序的唯一字符串,<installed-version> 表示特定版本。Where <product-id> is a unique string representing the resource provider, and <installed-version> represents a specific version. 与每个包相关联的机密存储在 Azure Stack Hub Key Vault 服务中。The secrets associated with each package are stored in the Azure Stack Hub Key Vault service.

打开提升了权限的 PowerShell 控制台并完成以下步骤,以确定轮换资源提供程序的机密所需的属性:Open an elevated PowerShell console and complete the following steps to determine the properties required to rotate the resource provider's secrets:

  1. 使用操作员凭据登录到 Azure Stack Hub 环境。Sign in to your Azure Stack Hub environment using your operator credentials. 请参阅使用 PowerShell 连接到 Azure Stack Hub 以了解 PowerShell 登录脚本。See Connect to Azure Stack Hub with PowerShell for PowerShell sign-in script. 请确保使用 PowerShell Az cmdlet(而不是 AzureRM)并替换所有占位符值,例如终结点 URL 和目录租户名称。Be sure to use the PowerShell Az cmdlets (instead of AzureRM), and replace all placeholder values, such as endpoint URLs and directory tenant name.

  2. 运行 Get-AzsProductDeployment cmdlet 可检索最新资源提供程序部署的列表。Run the Get-AzsProductDeployment cmdlet to retrieve a list of the latest resource provider deployments. 对于每个已部署的资源提供程序,返回的 "value" 集合都包含一个对应的元素。The returned "value" collection contains an element for each deployed resource provider. 找到相关的资源提供程序,并且记下这些属性的值:Find the resource provider of interest and make note of the values for these properties:

    • "name" - 在值的第二个段中包含资源提供程序产品 ID。"name" - contains the resource provider product ID in the second segment of the value.
    • "properties"."deployment"."version" - 包含当前已部署的版本号。"properties"."deployment"."version" - contains the currently deployed version number.

    在下面的示例中,请注意集合中第一个元素的事件中心 RP 部署,其产品 ID 为 "microsoft.eventhub",版本为 "1.2003.0.0"In the following example, notice the Event Hubs RP deployment in the first element in the collection, which has a product ID of "microsoft.eventhub", and version "1.2003.0.0":

    PS C:\WINDOWS\system32> Get-AzsProductDeployment -AsJson
    VERBOSE: GET https://adminmanagement.myregion.mycompany.com/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/productDeployments?api-version=2019-01-01 with 0-char payload
    VERBOSE: Received 2656-char response, StatusCode = OK
    {
        "value":  [
                      {
                          "id":  "/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/productDeployments/microsoft.eventhub",
                          "name":  "global/microsoft.eventhub",
                          "type":  "Microsoft.Deployment.Admin/locations/productDeployments",
                          "properties":  {
                                             "status":  "DeploymentSucceeded",
                                             "subscriptionId":  "b37ae55a-a6c6-4474-ba97-81519412adf5",
                                             "deployment":  {
                                                                "version":  "1.2003.0.0",
                                                                "actionPlanInstanceResourceId":"/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/actionplans/abcdfcd3-fef0-z1a3-z85d-z6ceb0f31e36",
                                                                "parameters":  {
    
                                                                               }
                                                            },
                                             "lastSuccessfulDeployment":  {
                                                                              "version":  "1.2003.0.0",
                                                                              "actionPlanInstanceResourceId":"/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/actionplans/abcdfcd3-fef0-z1a3-z85d-z6ceb0f31e36",
                                                                              "parameters":  {
    
                                                                                             }
                                                                          },
                                             "provisioningState":  "Succeeded"
                                         }
                      },
                      {
                      ...
                      }
                  ]
    }
    
  3. 通过连接资源提供程序产品 ID 和版本来生成资源提供程序的包 ID。Build the resource provider's package ID, by concatenating the resource provider product ID and version. 例如,使用上一步中派生的值,则事件中心 RP 包 ID 为 microsoft.eventhub.1.2003.0.0For example, using the values derived in the previous step, the Event Hubs RP package ID is microsoft.eventhub.1.2003.0.0.

  4. 使用上一步中派生的包 ID,运行 Get-AzsProductSecret -PackageId 以检索资源提供程序所使用的机密类型的列表。Using the package ID derived in the previous step, run Get-AzsProductSecret -PackageId to retrieve the list of secret types being used by the resource provider. 在返回的 value 集合中,查找包含 "properties"."secretKind" 属性的值 "Certificate" 的元素。In the returned value collection, find the element containing a value of "Certificate" for the "properties"."secretKind" property. 此元素包含 RP 证书密钥的属性。This element contains properties for the RP's certificate secret. 记下分配给此证书机密的名称,该名称由 "name" 属性的最后一段标识,就在 "properties" 上方。Make note of the name assigned to this certificate secret, which is identified by the last segment of the "name" property, just above "properties".

    在以下示例中,为事件中心 RP 返回的机密集合包含名为 aseh-ssl-gateway-pfx"Certificate" 机密。In the following example, the secrets collection returned for the Event Hubs RP contains a "Certificate" secret named aseh-ssl-gateway-pfx.

    PS C:\WINDOWS\system32> Get-AzsProductSecret -PackageId 'microsoft.eventhub.1.2003.0.0' -AsJson
    VERBOSE: GET
    https://adminmanagement.myregion.mycompany.com/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/productPackages/microsoft.eventhub.1.2003.0.0/secrets?api-version=2019-01-01 with 0-char payload
    VERBOSE: Received 617-char response, StatusCode = OK
    {
        "value":  [
                      {
                          "id":  "/subscriptions/ze22ca96-z546-zbc6-z566-z35f68799816/providers/Microsoft.Deployment.Admin/locations/global/productPackages/microsoft.eventhub.1.2003.0.0/secrets/aseh-ssl-gateway-pfx",
                          "name":  "global/microsoft.eventhub.1.2003.0.0/aseh-ssl-gateway-pfx",
                          "type":  "Microsoft.Deployment.Admin/locations/productPackages/secrets",
                          "properties":  {
                                             "secretKind":  "Certificate",
                                             "description":  "Event Hubs gateway SSL certificate.",
                                             "expiresAfter":  "P730D",
                                             "secretDescriptor":  {
    
                                                                  },
                                             "secretState":  {
                                                                 "status":  "Deployed",
                                                                 "rotationStatus":  "None",
                                                                 "expirationDate":  "2022-03-31T00:16:05.3068718Z"
                                                             },
                                             "provisioningState":  "Succeeded"
                                         }
                      },
                      ...
                  ]
    }
    

轮转机密Rotate the secrets

  1. 使用 Set-AzsProductSecret cmdlet 将新证书导入到 Key Vault,该新证书将由轮换过程使用。Use the Set-AzsProductSecret cmdlet to import your new certificate to Key Vault, which will be used by the rotation process. 在运行脚本之前,请相应地替换变量占位符值:Replace the variable placeholder values accordingly before running the script:

    占位符Placeholder 说明Description 示例值Example value
    <product-id> 最新资源提供程序部署的产品 ID。The product ID of the latest resource provider deployment. microsoft.eventhub
    <installed-version> 最新资源提供程序部署的版本。The version of the latest resource provider deployment. 1.2003.0.0
    <cert-secret-name> 用于存储证书机密的名称。The name under which the certificate secret is stored. aseh-ssl-gateway-pfx
    <cert-pfx-file-path> 证书 PFX 文件的路径。The path to your certificate PFX file. C:\dir\eh-cert-file.pfx
    <pfx-password> 分配给证书 .PFX 文件的密码。The password assigned to your certificate .PFX file. strong@CertSecret6
    $productId = '<product-id>'
    $packageId = $productId + '.' + '<installed-version>'
    $certSecretName = '<cert-secret-name>' 
    $pfxFilePath = '<cert-pfx-file-path>'
    $pfxPassword = ConvertTo-SecureString '<pfx-password>' -AsPlainText -Force   
    Set-AzsProductSecret -PackageId $packageId -SecretName $certSecretName -PfxFileName $pfxFilePath -PfxPassword $pfxPassword -Force
    
  2. 最后,使用 Invoke-AzsProductRotateSecretsAction cmdlet 来轮换内部机密和外部机密:Finally, use the Invoke-AzsProductRotateSecretsAction cmdlet to rotate the internal and external secrets:

    备注

    完成轮换过程大约需要3.5 到 4 小时。It takes approximately 3.5 - 4 hours to complete the rotation process.

    Invoke-AzsProductRotateSecretsAction -ProductId $productId
    

    可以在 PowerShell 控制台中或在管理员门户中(通过在“市场”服务中选择资源提供程序)监视机密轮换进度:You can monitor secret rotation progress in either the PowerShell console, or in the administrator portal by selecting the resource provider in the Marketplace service:

    secret-rotation-progresssecret-rotation-progress

疑难解答Troubleshooting

机密轮换应成功完成,且不发生错误。Secret rotation should complete successfully without errors. 如果在管理员门户中遇到以下任何情况,可以提交支持请求获取帮助:If you experience any of the following conditions in the administrator portal, open a support request for assistance:

  • 身份验证问题,包括连接到 IoT 中心资源提供程序时出现的问题。Authentication issues, including problems connecting to the IoT Hub resource provider.
  • 无法升级资源提供程序或编辑配置参数。Unable to upgrade resource provider, or edit configuration parameters.
  • 未显示使用情况指标。Usage metrics aren't showing.
  • 未生成帐单。Bills aren't being generated.
  • 没有发生备份。Backups aren't occurring.

后续步骤Next steps

若要详细了解如何轮换 Azure Stack Hub 基础结构机密,请访问在 Azure Stack Hub 中轮换机密For details on rotating your Azure Stack Hub infrastructure secrets, visit Rotate secrets in Azure Stack Hub.