Troubleshoot common key vault errors in Azure Application Gateway

Summary

This article explains how to troubleshoot common key vault errors in Azure Application Gateway and resolve misconfigurations that can disrupt certificate management and secure HTTPS connections.

Application Gateway enables you to securely store TLS certificates in Azure Key Vault. When you use a key vault resource, it's important that the gateway always has access to the linked key vault. If your Application Gateway can't fetch the certificate, it disables the associated HTTPS listeners. For more information, see Understanding disabled listeners.

Azure Advisor error codes

The following sections describe the various errors you might encounter. To check if your gateway has any of these problems, visit Azure Advisor for your account. Use this troubleshooting article to resolve the problem. Configure Azure Advisor alerts to stay informed when a key vault problem is detected for your gateway.

Error code - "UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault"

Description

The associated user-assigned managed identity doesn't have the required permission.

Solution

Configure the access policies of your key vault to grant the user-assigned managed identity permission on secrets. You can do this in either of the following two ways:

Vault access policy

1. In the Azure portal, go to the linked key vault.
2. Select Access policies.
3. For Permission model, select Vault access policy.
4. In Secret Management Operations, select the Get permission.
5. Select Save.

For more information, see Assign a Key Vault access policy by using the Azure portal.

Azure role-based access control (RBAC)

1. In the Azure portal, go to the linked key vault.
2. Select Access policies.
3. For Permission model, select Azure role-based access control.
4. Go to Access Control (IAM) to configure permissions.
5. Add role assignment for your managed identity by choosing the following values: a. Role: Key Vault Secrets User b. Assign access to: Managed identity c. Members: select the user-assigned managed identity that you associated with your application gateway.
6. Select Review + assign.

For more information, see Azure role-based access control in Key Vault.

Error code - "SecretDisabled"

Description

The associated certificate is disabled in Azure Key Vault.

Solution

Enable the certificate version that Application Gateway uses. To do this, follow these steps:

1. In the Azure portal, go to the linked key vault.
2. Select Certificates.
3. Select the certificate name you want, and then select the disabled version.
4. On the management page, use the toggle to enable that certificate version.

Error code - "SecretDeletedFromKeyVault"

Description

The associated certificate is deleted from Key Vault.

Solution

To recover a deleted certificate, follow these steps:

1. In the Azure portal, go to the linked key vault.
2. Open the Certificates pane.
3. Use the Managed deleted certificates tab to recover a deleted certificate.

If you permanently delete a certificate object, create a new certificate and update Application Gateway with the new certificate details. When you configure through Azure CLI or Azure PowerShell, use a secret identifier URI without a version. This choice allows instances to retrieve a renewed version of the certificate, if it exists.

Error code - "UserAssignedManagedIdentityNotFound"

Description

The associated user-assigned managed identity is deleted.

Solution

Create a new managed identity and use it with the key vault. To do so, follow these steps:

1. Re-create a managed identity with the same name that you used previously, and under the same resource group. Refer to resource Activity Logs for naming details.
2. Go to the key vault resource that you want, and set its access policies to grant this new managed identity the required permission. For more information, see Error code: UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault.

Error code - "KeyVaultHasRestrictedAccess"

Description

Key Vault has a restricted network setting.

Solution

You encounter this error when you enable the Key Vault firewall for restricted access. Configure Application Gateway in a restricted network of Key Vault. To do so, follow these steps:

1. In Key Vault, select Networking.
2. Select the Firewalls and virtual networks tab, and then select Private endpoint and selected networks.
3. Use Azure Virtual Network to add your Application Gateway's virtual network and subnet.
4. Select the Microsoft.KeyVault checkbox.
5. Select Yes. This action allows trusted services to bypass the Key Vault firewall.

Error code - "KeyVaultSoftDeleted"

Description

The associated key vault is in soft-delete state.

Solution

Find the deleted key vault resource. To do so, follow these steps:

1. In the Azure portal, search for key vault.
2. In Services, select Key vaults.

1. Select Managed deleted vaults.
2. Find the deleted key vault resource and recover it.

Error code - "CustomerKeyVaultSubscriptionDisabled"

Description

The subscription for Key Vault is disabled.

Solution

Various reasons can cause Azure to disable your subscription. To take the necessary action to resolve this problem, see Reactivate a disabled Azure subscription.

Application Gateway error codes

Error code - "ApplicationGatewayCertificateDataOrKeyVaultSecretIdMustBeSpecified / ApplicationGatewaySslCertificateDataMustBeSpecified"

Description

You encounter this error when you try to update a listener certificate. When this error occurs, the change to update the certificate is discarded, and the listener continues to handle traffic with the previously defined configuration.

Solution

To resolve this issue, try uploading the certificate again. For example, use the following PowerShell commands to update certificates uploaded to Application Gateway or referenced via Azure Key Vault.

Update certificate uploaded directly to Application Gateway.

$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 

Update certificate referenced from 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 

References

• Understanding and fixing disabled listeners
• Azure Application Gateway Resource Health overview