Azure 应用程序网关中的常见密钥保管库错误

应用程序网关使客户能够在 Azure Key Vault 中安全地存储 TLS 证书。 使用密钥保管库资源时,网关必须始终有权访问链接的密钥保管库。 如果应用程序网关无法提取证书,关联的 HTTPS 侦听器将处于禁用状态。 了解详细信息

本文可帮助你了解错误代码的详细信息以及解决此类密钥保管库配置错误的步骤。

提示

使用不指定版本的机密标识符。 这样,如果 Azure 密钥保管库中有更新的版本可用,Azure 应用程序网关将自动轮换证书。 不包含版本的机密 URI 的示例:https://myvault.vault.azure.cn/secrets/mysecret/

Azure 顾问错误代码

以下部分介绍了你可能会遇到的各种错误。 可以通过访问帐户的 Azure 顾问 来验证你的网关是否存在任何此类问题,并使用此故障排除文章来解决问题。 建议配置 Azure 顾问警报,以便在网关检测到密钥保管库问题时随时掌握情况。

注意

Azure 应用程序网关每隔四小时生成密钥保管库诊断日志。 如果在修复配置后诊断仍显示错误,你可能需要等待日志刷新。

错误代码:UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault

说明:关联的用户分配的托管标识没有所需权限。

解决方法:配置密钥保管库的访问策略,向用户分配的托管标识授予对机密的权限。 可通过以下任一方式执行此操作:

保管库访问策略

  1. 在 Azure 门户中转到链接的密钥保管库。
  2. 打开“访问策略”边栏选项卡。
  3. 对于“权限模型”,请选择“保管库访问策略” 。
  4. 在“机密管理操作”下,选择“Get”权限 。
  5. 选择“保存”。

显示如何解决“Get”权限错误的屏幕截图。

有关详细信息,请参阅使用 Azure 门户分配密钥保管库访问策略

Azure 基于角色的访问控制

  1. 在 Azure 门户中转到链接的密钥保管库。
  2. 打开“访问策略”边栏选项卡。
  3. 对于“权限模型”,选择“Azure 基于角色的访问控制”。
  4. 导航到“访问控制(IAM)”边栏选项卡以配置权限。
  5. 通过选择以下选项为托管标识添加角色分配
    a. 角色:密钥保管库机密用户
    b. 将访问权限分配给:托管标识
    c. 成员:选择已与应用程序网关相关联的用户分配的托管标识。
  6. 选择“查看 + 分配”。

有关详细信息,请参阅 Key Vault 中 Azure 基于角色的访问控制

注意

使用 Azure 基于角色的访问控制时,门户目前不支持添加新的基于密钥保管库的证书。 可以使用 ARM 模板、CLI 或 PowerShell 来完成此操作。 请访问此页面以获取指导。

错误代码:SecretDisabled

说明:已在密钥保管库中禁用关联的证书。

解决方法: 重新启用当前用于应用程序网关的证书版本。

  1. 在 Azure 门户中转到链接的密钥保管库。
  2. 打开“证书”窗格。
  3. 选择所需的证书名称,然后选择已禁用的版本。
  4. 在管理页上,使用切换开关启用该证书版本。

显示如何重新启用机密的屏幕截图。

错误代码:SecretDeletedFromKeyVault

说明:已从密钥保管库中删除关联的证书。

解决方法:若要恢复已删除的证书,请执行以下操作:

  1. 在 Azure 门户中转到链接的密钥保管库。
  2. 打开“证书”窗格。
  3. 使用“托管的已删除证书”选项卡恢复已删除的证书。

但如果证书对象已永久删除,则需要创建新证书,并使用新的证书详细信息更新应用程序网关。 通过 Azure CLI 或 Azure PowerShell 进行配置时,请使用不包含版本的机密标识符 URI。 此选项允许实例检索证书的续订版本(如果存在)。

显示如何恢复密钥保管库中已删除的证书的屏幕截图。

错误代码:UserAssignedManagedIdentityNotFound

说明:已删除关联的用户分配的托管标识。

解决方法:创建一个新的托管标识并将其用于密钥保管库。

  1. 在同一资源组下重新创建与之前同名的托管标识。 (提示:有关命名详细信息,请参阅资源活动日志)。
  2. 转到所需的密钥保管库资源,并设置其访问策略以授予此新托管标识所需的权限。 可以按照 UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault 中提到的相同步骤进行操作。

错误代码:KeyVaultHasRestrictedAccess

说明:密钥保管库存在受限网络设置。

解决方法:启用密钥保管库防火墙以限制访问时,你将遇到此错误。 仍可执行以下步骤,在密钥保管库的受限网络中配置应用程序网关:

  1. 在密钥保管库中打开“网络”窗格。
  2. 选择“防火墙和虚拟网络”选项卡,然后选择“专用终结点和选定网络” 。
  3. 然后使用“虚拟网络”添加应用程序网关的虚拟网络和子网。 在此过程中,还可以通过选中“Microsoft.KeyVault”服务终结点复选框来对其进行配置。
  4. 最后,选择“是”以允许受信任的服务绕过 Key Vault 的防火墙。

显示如何解决受限网络错误的屏幕截图。

错误代码:KeyVaultSoftDeleted

说明:关联的密钥保管库处于软删除状态。

解决方法:在 Azure 门户中搜索“密钥保管库”。 在“服务”下,选择“密钥保管库” 。

显示如何搜索密钥保管库服务的屏幕截图。

选择“托管的已删除保管库”。 在此处可以查找并恢复已删除的密钥保管库资源。 显示如何恢复已删除的密钥保管库的屏幕截图。

错误代码:CustomerKeyVaultSubscriptionDisabled

说明:已禁用密钥保管库的订阅。

解决方法:你的 Azure 订阅可能出于各种原因而被禁用。 若要采取必要的措施来解决此问题,请参阅重新激活已禁用的 Azure 订阅

应用程序网关错误代码

错误代码:ApplicationGatewayCertificateDataOrKeyVaultSecretIdMustBeSpecified / ApplicationGatewaySslCertificateDataMustBeSpecified

说明:尝试更新侦听器证书时可能会遇到此错误。 出现此错误时,将放弃更新证书的更改,侦听器将继续使用先前定义的配置处理流量。

解决方法:若要解决此问题,请尝试再次上传证书。 例如,以下 PowerShell 命令可用于更新上传到应用程序网关或通过 Azure Key Vault 引用的证书。

更新直接上传到应用程序网关的证书:

$appgw = Get-AzApplicationGateway -ResourceGroupName "<ResourceGroup>" -Name "<AppGatewayName>"

$password = ConvertTo-SecureString -String "<password>" -Force -AsPlainText

Set-AzApplicationGatewaySSLCertificate -Name "<oldcertname>" -ApplicationGateway $appgw -CertificateFile "<newcertPath>" -Password $password

Set-AzApplicationGateway -ApplicationGateway $appgw 

更新从 Azure Key Vault 引用的证书:

$appgw = Get-AzApplicationGateway -ResourceGroupName "<ResourceGroup>" -Name "<AppGatewayName>"

$secret = Get-AzKeyVaultSecret -VaultName "<KeyVaultName>" -Name "<CertificateName>" 
$secretId = $secret.Id.Replace($secret.Version, "") 
$cert = Set-AzApplicationGatewaySslCertificate -ApplicationGateway $AppGW -Name "<CertificateName>" -KeyVaultSecretId $secretId 

Set-AzApplicationGateway -ApplicationGateway $appgw 

后续步骤

在你继续使用应用程序网关的过程中,以下故障排除文章可能有所帮助: