Configure a secret store that is backed by Azure Key Vault. Cribl authenticates to Microsoft Entra ID as a service principal to retrieve global secrets.

1. In Global Settings > Security > Secret Stores, select Add Secret Store.

2. In the New Secret Store modal, configure the store using the following fields:

   • Secret store: Select Azure Key Vault.

   • Store name: Unique identifier for the secret store.

   • Description: Brief description of the secret store (optional).

   • Key Vault URI: HTTPS URI of the Azure Key Vault to retrieve global secrets from. Cribl determines the Azure cloud from the URI. Cribl does not support managed Hardware Security Module (HSM) URIs. Supported URI suffixes are:

     • Azure Public Cloud: .vault.azure.net (for example, https://my-vault.vault.azure.net)
     • Azure Government: .vault.usgovcloudapi.net

   • Authentication > Authentication method: Method to use for authenticating to Microsoft Entra ID as a service principal. Enter credentials from the Microsoft Entra app registration that you created for the service principal.

     • Client secret: Authenticate with a client secret.

       • Tenant ID: Directory (tenant) ID of the Microsoft Entra tenant that owns the app registration.
       • Client ID: Application (client) ID of the app registration.
       • Client secret: Client secret generated for the app registration in the Azure portal.

     • Client certificate: Authenticate with a stored certificate.

       • Tenant ID: Directory (tenant) ID of the Microsoft Entra tenant that owns the app registration.
       • Client ID: Application (client) ID of the app registration.
       • Certificate: PEM certificate stored in Cribl that you registered as credentials for the app registration.

       Azure Key Vault secret stores support only PEM certificates. PKCS#12 (.pfx) certificates are not supported. Add the public certificate to the app registration, and import the PEM certificate and corresponding private key on the Leader.

3. Select Test and Save.

The Test and Save check and health checks confirm that the Leader can reach the vault and that Microsoft Entra ID accepts the credentials. They do not confirm that Cribl can retrieve secret values or resolve secrets at runtime.

To retrieve secret values and resolve secrets at runtime, you must assign the Key Vault Secrets User Azure role to the service principal on the Azure Key Vault resource. Secret-level assignment alone is insufficient.

Reference Azure Key Vault Secrets ​

When you add a global secret in a secret folder that is backed by an Azure Key Vault secret store, enter the name of the secret in Azure Key Vault in the External secret reference, Secret key reference, or Password reference field, depending on the secret type. The name must have between 1 and 127 characters and can contain only letters, digits, and hyphens. Do not enter a path: the name cannot contain /.

Leave Response field empty to use the entire Azure secret value. For a JSON secret, enter a key (for example token) to extract that field.

Cribl retrieves the current versions of secrets from Azure Key Vault and does not support referencing a specific version of a secret.

Adding or updating a secret reference fails if the Azure secret is disabled, past its expiration date, or not yet past its activation date. If a referenced secret becomes disabled, expires, or is not yet active, Cribl continues to serve the secret and writes this warning to the Leader logs: Azure Key Vault secret is outside its validity window; serving anyway.

Health Check Error Messages ​

After five consecutive failed health checks for an Azure Key Vault-backed secret store, Cribl displays a system bulletin message. Health checks run every 30 seconds, so a single transient failure can clear on its own. For details about health checks and reload, deploy, and recovery, see Secret Store Health Check Failures.

Health check errors that mention List or Get are referring to connectivity checks that Cribl runs, not the Azure role to assign. Assign the Key Vault Secrets User Azure role (Get) to the service principal on the Azure Key Vault resource (not on individual secrets).

Do not assign only the Key Vault Reader (List) Azure role. Key Vault Reader can pass Test and Save and health checks, but Cribl cannot retrieve secret values without Key Vault Secrets User.

If an error tells you to grant Key Vault Reader or Get on cribl-gsm-connectivity-probe, grant Key Vault Secrets User on the vault resource instead.

If you revoke or rotate the Microsoft Entra credentials for a secret store that is already healthy, health checks can continue to succeed for up to one hour. Cribl reuses a Microsoft Entra token it already obtained and does not detect that the credentials are no longer valid until the token expires or the secret store reinitializes (for example, due to a Leader restart).

Azure Key Vault Firewalls and IP Allowlists ​

When the Leader resolves global secrets from Azure Key Vault, it connects to the Key Vault URI that you configured. Cribl.Cloud Leaders must be able to reach the vault’s public endpoint. On-prem Leaders can use an Azure private endpoint if they can reach the vault on your network.

Cribl.Cloud ​

Cribl.Cloud Leaders are not on your Azure virtual network. They can reach Azure Key Vault only at the vault’s public endpoint. A vault that you can reach only over an Azure private endpoint is not reachable from Cribl.Cloud.

Cribl.Cloud Workspaces use public egress by default, and the Leader’s egress IP is ephemeral. When Cribl replaces the Leader during upgrades or maintenance, the egress IP changes. If you configure the Azure Key Vault firewall to allow selected networks, you must use a stable Leader egress IP and add it to the vault’s IP allowlist.

To enable static egress for a Workspace, contact Cribl Support. With static egress enabled, Cribl provisions one stable egress IP per Availability Zone. Add every egress IP to your Azure Key Vault allowlist.

Static egress is irreversible. You cannot disable static egress after it is enabled for a Workspace or return to public egress.

On-Prem Deployments ​

In on-prem Cribl deployments, the Leader Node typically has a stable egress IP that you control. If the Leader reaches the vault over the public internet and you configure the Azure Key Vault firewall to allow selected networks, add that IP address (or the IP addresses for all Leaders that resolve Azure Key Vault secrets, such as in a Leader HA pair) to your Azure Key Vault allowlist.