Common key vault errors in Azure Application Gateway

Summary

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.

This article helps you understand the details of the error codes and the steps to resolve key vault misconfigurations.

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 fix 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.

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

Vault access policy

1. Go to the linked key vault in the Azure portal.
2. Open Access policies.
3. For Permission model, select Vault access policy.
4. Under 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

1. Go to the linked key vault in the Azure portal.
2. Open 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 has been disabled in Key Vault.

Resolution: Re-enable the certificate version that is currently in use for Application Gateway.

1. Go to the linked key vault in the Azure portal.
2. Open the Certificates pane.
3. Select the required certificate name, 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 has been deleted from Key Vault.

Resolution: To recover a deleted certificate:

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

On the other hand, if a certificate object is permanently deleted, you'll need to create a new certificate and update Application Gateway with the new certificate details. When you're configuring through the 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 has been deleted.

Resolution: Create a new managed identity and use it with the key vault.

1. Re-create a managed identity with the same name that you used previously, and under the same resource group. (TIP: 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. You can follow the same steps as mentioned in Error code: UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault.

Error code: KeyVaultHasRestrictedAccess

Description: There's a restricted network setting for Key Vault.

Resolution: You encounter this error when you enable the Key Vault firewall for restricted access. You can still configure Application Gateway in a restricted network of Key Vault, by following these steps:

1. In Key Vault, open the Networking pane.
2. Select the Firewalls and virtual networks tab, and select Private endpoint and selected networks.
3. Then, by using Virtual Networks, add your Application Gateway's virtual network and subnet. During the process, also configure the 'Microsoft.KeyVault' service endpoint by selecting its checkbox.
4. Finally, select Yes to allow Trusted Services to bypass Key Vault's firewall.

Error code: KeyVaultSoftDeleted

Description: The associated key vault is in soft-delete state.

Resolution: In the Azure portal, search for key vault. Under Services, select Key vaults.

Select Managed deleted vaults. From here, you can find the deleted Key Vault resource and recover it.

Error code: CustomerKeyVaultSubscriptionDisabled

Description: The subscription for Key Vault is disabled.

Resolution: 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.

Resolution: 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 

Next steps

These troubleshooting articles might be helpful as you continue to use Application Gateway:

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