key-vault-expiry

Azure Key Vault expiries

Returns, for each enabled secret and certificate of an Azure Key Vault that has an expiry date, the days left before it, read from the vault's own API with a service principal that may only read metadata. The lists give the attributes of each item; no value of a secret is ever read, and the role this collector asks for cannot read one. Two watches are offered, each one set on the probe.

Versions

Generic: the API of Key Vault is the same for every vault. The collector asks for the API version 2025-07-01.

How it works

1. POST https://login.microsoftonline.com/<azure:tenant>/oauth2/v2.0/token, the form grant_type=client_credentials&client_id=…&client_secret=…&scope=https://vault.azure.net/.default: an access token for the vaults, kept thirty minutes in the probe's cache, encrypted on the poller. A token the vault no longer takes answers 401, and the collector logs in again, once.
2. GET https://<azure:vault>.vault.azure.net/secrets?api-version=2025-07-01&maxresults=25, the token as Authorization: Bearer, page after page by nextLink, null on the last page: the identifier and the attributes of each secret, never its value.

{"value": [{"id": "https://<vault>.vault.azure.net/secrets/db-password", "contentType": "…", "attributes": {"enabled": true, "exp": 1798761600, "created": 1482189047, "updated": 1482189047}}], "nextLink": "…"}

3. GET https://<azure:vault>.vault.azure.net/certificates?api-version=2025-07-01&maxresults=25, the same way.

{"value": [{"id": "https://<vault>.vault.azure.net/certificates/www", "x5t": "…", "attributes": {"enabled": true, "nbf": 1430344421, "exp": 2208988799}}], "nextLink": null}

• An item is named secret/<name> or certificate/<name>, its name the last part of its id.
• days-left is the time from now to exp, in days, to the tenth, against the poller's clock: negative once expired. exp is in seconds since 1970, UTC.
• An item disabled (enabled false), or without exp, has no days-left. A secret marked managed is the key of one of the vault's certificates, which the list of certificates already gives: it is left out.
• The name of the vault holds only letters, digits and hyphens; any other character stops the collector misconfigured before anything leaves. A next page is only followed on the vault itself, https://<vault>.vault.azure.net/, written with or without its port 443; any other address stops the collector unreachable.
• A code 400 or 401 on the login stops the collector misconfigured (the tenant, the client or its secret refused); a code 403 on a list (the role missing, or the vault's firewall) too; any other code but 200 stops it unreachable. A vault name that does not exist does not resolve, and stops the collector unreachable.

The client secret comes from protocol:http:password, a secret variable: it goes in the body of the login only, to https:// only. The token is a secret too, kept in the cache and sent in a header. The lists are not secret.

Prerequisites

• A service principal: an app registration in Microsoft Entra ID with a client secret. Its application (client) ID goes in protocol:http:user, its secret in protocol:http:password, its tenant in the variable azure:tenant.
• A vault in the permission model "Azure role-based access control": the role Key Vault Reader given to the service principal on the vault. It reads the metadata of the vault and of its secrets, keys and certificates, and cannot read a secret's value nor a key (its data actions are Microsoft.KeyVault/vaults/*/read and Microsoft.KeyVault/vaults/secrets/readMetadata/action). It also carries management actions beyond reading (classic alert rules, support tickets); narrower still is a custom role whose only data actions are Microsoft.KeyVault/vaults/secrets/readMetadata/action and Microsoft.KeyVault/vaults/certificates/read, and no action at all:

{
  "Name": "banshee Key Vault expiry reader",
  "Description": "Lists the secrets and certificates of a vault with their attributes, never a value.",
  "Actions": [],
  "DataActions": [
    "Microsoft.KeyVault/vaults/secrets/readMetadata/action",
    "Microsoft.KeyVault/vaults/certificates/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": ["/subscriptions/<subscription id>"]
}

• A vault in the permission model "Vault access policy": an access policy for the service principal with the secret permission List and the certificate permission List, and nothing else: never Get on the secrets, which reads their values.
• The firewall of the vault lets the poller in, when it is set.
• The poller reaches login.microsoftonline.com and <vault>.vault.azure.net in HTTPS. Their certificates are issued by public authorities: the profile "Standard" trusts them.

Variables

Outputs

Watches

Limits

• The keys of the vault are not read: their expiry is not in this collector.
• One vault per probe; the vaults of the public Azure cloud only (vault.azure.net).
• Not checked against an Azure subscription: the routes, parameters and fields are those of the Azure REST API reference (learn.microsoft.com: "Get Secrets" and "Get Certificates" in 2025-07-01, SecretAttributes, CertificateAttributes), the roles and data actions those of "Azure built-in roles" (Security) and "Azure permissions" (Security), the login that of the Microsoft identity platform ("OAuth 2.0 client credentials flow"). The access policy permissions List are not checked against a vault; the custom role is not checked either.