Common key vault errors in Azure Application Gateway

Application Gateway enables customers to securely store TLS certificates in Azure Key Vault. When using a key vault resource, it's important that the gateway always has access to the linked key vault. If your Application Gateway is unable to fetch the certificate, the associated HTTPS listeners will be placed in a disabled state. Learn more.

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

Tip

Use a secret identifier that doesn't specify a version. This way, Azure Application Gateway will automatically rotate the certificate, if a newer version is available in Azure Key Vault. An example of a secret URI without a version is: https://myvault.vault.azure.net/secrets/mysecret/.

Azure Advisor error codes

The following sections describe the various errors you might encounter. You can verify if your gateway has any such problem by visiting Azure Advisor for your account, and use this troubleshooting article to fix the problem. We recommend configuring Azure Advisor alerts to stay informed when a key vault problem is detected for your gateway.

Note

Azure Application Gateway generates logs for key vault diagnostics every four hours. If the diagnostic continues to show the error after you have fixed the configuration, you might have to wait for the logs to be refreshed.

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 may do so in any of the following ways:

Vault access policy

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

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

Note

Portal support for adding a new key vault-based certificate is currently not available when using Azure role-based access control. You can accomplish it by using ARM template, CLI, or PowerShell. Visit this page for guidance.

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 was previously used, and under the same resource group. (TIP: Refer to resource Activity Logs for naming details).
2. Go to the desired key vault resource, and set its access policies to grant this new managed identity the required permission. You can follow the same steps as mentioned under UserAssignedIdentityDoesNotHaveGetPermissionOnKeyVault.

Error code: KeyVaultHasRestrictedAccess

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

Resolution: You'll 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, using Virtual Networks, add your Application Gateway's virtual network and subnet. During the process, also configure '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: Your Azure subscription can get disabled for various reasons. To take the necessary action to resolve, see Reactivating a disabled Azure subscription.

Application Gateway Error Codes

Error code: ApplicationGatewayCertificateDataOrKeyVaultSecretIdMustBeSpecified / ApplicationGatewaySslCertificateDataMustBeSpecified

Description: You may encounter this error when trying to update a listener certificate. When this error occurs, the change to update the certificate will be discarded, and the listener will continue to handle traffic with the previously defined configuration.

Resolution: To resolve this issue, please try uploading the certificate again. For example, the following PowerShell commands may be used 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