Azure Key Vault Sensor User Guide

The Azure Key Vault Sensor User Guide provides instructions for deploying and operating the Azure Key Vault Sensor within the Keyfactor AgileSec Platform. This guide covers supported authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, data flows, incremental scanning, and auto-resolution.

Overview

The Azure Key Vault Sensor integrates Azure Key Vault with Keyfactor's AgileSec Platform. This sensor allows you to discover, inventory, and analyze cryptographic keys, certificates, and secrets stored across one or more Azure Key Vaults within your Azure environment.

Key Features

• Flexible Scan Targets: Scan a single vault by URL, all vaults in a subscription, all vaults in a resource group, or all vaults across all accessible subscriptions.

• Multiple Authentication Methods: Supports client secret credentials, managed identity credentials, and default host credentials.

• Concurrent Processing: Configurable thread pools for vault enumeration (threads_per_target) and per-vault processing (threads_per_vault).

• Continuous Monitoring: Operates in a polling loop with a configurable interval, or runs as a one-shot scan with --no-interval.

• Incremental Scanning: Efficiently scans only new or modified assets in subsequent runs.

What Gets Scanned

The sensor connects to Azure Key Vault and inventories the following asset types:

• Cryptographic Keys: RSA, EC, and symmetric keys managed by Azure Key Vault, including key properties, versions, and rotation metadata.

• X.509 Certificates: TLS/SSL certificates, code signing certificates, and other X.509 certificates stored in Key Vault, including full certificate chains and expiration data.

• Secrets: Opaque secrets stored in Key Vault containing embedded certificates, keys, or other cryptographic material.

Prerequisites

Azure Requirements

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Supported Authentication Methods

The Azure Key Vault sensor supports three authentication methods, evaluated in the following order of precedence:

1. Client Secret Credentials

Use an Azure AD app registration with a client secret. This is the recommended method for platform and remote execution where managed identity is not available.

2. Managed Identity Credentials

Use an Azure managed identity (user-assigned). This is ideal when running the sensor on an Azure VM or Azure-hosted environment.

3. Default Credentials

If neither client_secret_credentials nor managed_credentials are specified, the sensor falls back to the default credentials available on the host (e.g., system-assigned managed identity, Azure CLI credentials, or environment variables recognized by the Azure SDK).

Required Access Rights

The credential used by the sensor must have the following permissions on each target Key Vault:

Tip: Assign the built-in Key Vault Reader role at the subscription level for vault enumeration, and configure a Key Vault Access Policy granting GET and LIST permissions for keys, certificates, and secrets on each target vault.

Running the Sensor

1. Platform Scan Execution: Configure and execute scans directly though the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. Using API: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.

3. Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Refer to Sensors Architecture and Overview: Running the Sensor for additional execution and flow details.

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

1.1 Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select Azure Key Vault Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for "Azure Key Vault".

2.3 Click on the Azure Key Vault sensor card.

This will open the sensor configuration interface.

Step 3: Configure Sensor Parameters

3.1 Fill in the required configuration parameters:

Platform Scan Configuration Fields

API Request Body

Scans may be programmatically triggered through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

Note: For complete API reference, see the API document.

API Access Token

1. Open your browser and navigate to the AgileSec Platform UI.

2. Log in with your Keyfactor credentials.

3. Click "Access Tokens" in the main navigation menu.

4. Click "Generate Token".

5. Set Token Type to API Token and provide the required details.

6. Click "Generate" and copy the generated token.

API Endpoint

POST https://<platform-url>/v3/scan/create

Request Format

Headers

Content-Type: application/json
isg-api-token: <your-api-token>

Request Body

The complete request body contains sensor configuration in the sensorConfig field, i.e:

  {
    "sensorName": "<sensor name>",
    "sensorType": "Azure Key Sensor",
    "sensorConfig": {
       "vault_url": "<vault url>",
       "tenant_id": "<azure ad tenant id>",
       "client_id": "<azure ad client id>",
       "client_secret": "<azure ad client secret>"
    },
    "callbackId": "<callback id>",
    "labels": [
        {
            "<label name>": "<label value>"
        }
    ],
    "priority": "<priority>",
    "incrementalScan": true,
    "autoResolutionInterval": 5
  }

API Field Descriptions

See Platform Scan Configuration Fields

Remote Scan Execution

Remote Execution Flow allows you to run the sensor on a host using the Unified Sensor binary.

Remote Scan Execution Configuration

Step 1: Download Unified Sensor

1.1 Navigate to AgileSec Platform UI → Sensors → Remote Scan.

1.2 Download the sensor binary for your operating system.

Step 2: Generate Remote Sensor Token

2.1 In the Remote Scan UI, click "Generate Token".

2.2 Copy the generated token.

2.3 Store the token securely in an environment variable or set it in the sensor config:

  export SENSOR_TOKEN="your-generated-token"

Step 3: Create Configuration File

Create a YAML configuration file (e.g., azure_key_vault-config.yml) with your scan settings. An example configuration can be found at config/sample-configs/azure_key_vault-config.yml.

Step 4: Run the Sensor

Execute the sensor with your configuration file:

• Linux/macOS

  BASH

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  
  # Run sensor
  ./unified_sensor_linux -c azure_key_vault-config.yml

• Windows (PowerShell)

  POWERSHELL

  # Set environment variables
  $env:SENSOR_TOKEN = "your-sensor-token"
  
  # Run sensor
  .\\unified_sensor_windows.exe -c .\\azure_key_vault-config.yml

Remote Scan Execution Configuration Examples

• Scan a Single Vault (Client Secret Auth)

  YAML

  scan_config:
    plugins:
      - azkeys
      - export
    config:
      azkeys:
        name: azkeys
        plugin_config:
          vault_url: "<https://my-vault.vault.azure.net/>"
          client_secret_credentials:
            tenant_id: "your-tenant-id"
            client_id: "your-client-id"
            client_secret: "${env:AZURE_CLIENT_SECRET}"

• Scan All Vaults in a Subscription

  YAML

  scan_config:
    plugins:
      - azkeys
      - export
    config:
      azkeys:
        name: azkeys
        plugin_config:
          subscription_ids: [ "your-subscription-id" ]
          client_secret_credentials:
            tenant_id: "your-tenant-id"
            client_id: "your-client-id"
            client_secret: "${env:AZURE_CLIENT_SECRET}"

• Scan All Accessible Vaults (Managed Identity)

  YAML

  scan_config:
    plugins:
      - azkeys
      - export
    config:
      azkeys:
        name: azkeys
        plugin_config:
          managed_credentials:
            client_id: "your-managed-identity-client-id"

• Tuning Concurrency

  YAML

  scan_config:
    plugins:
      - azkeys
      - export
    config:
      azkeys:
        name: azkeys
        plugin_config:
          threads_per_target: 10
          threads_per_vault: 4

Known Limitations

Scan Target Exclusivity

Only one scan target mode can be active at a time. Specify exactly one of: vault_url, subscription_id, or all: true. Configuring more than one will result in undefined behavior.

Throttling

Azure Key Vault enforces rate limits on API calls. When scanning a large number of vaults or vaults with many assets, the sensor may encounter HTTP 429 (Too Many Requests) responses. Reduce threads_per_target and threads_per_vault to mitigate throttling.

Private Endpoints

If Key Vaults are configured with private endpoints and no public access, the sensor must run on a machine with network access to those private endpoints (e.g., within the same VNet or via VPN/ExpressRoute).

Troubleshooting

Common Errors

• CONFIG-404 — Configuration file not found

  • Cause: The specified configuration file path does not exist.

  • Fix: Verify the path passed to -config flag. The default path is ../../etc/config/isg_azkeys.json.

• CONFIG-422 — Invalid configuration

  • Cause: A required configuration field is missing or has an invalid value (e.g., interval is zero or negative when running in polling mode).

  • Fix: Review the configuration file. Ensure interval is a positive integer if not using --no-interval. Ensure exactly one scan target is specified.

• CONFIG-500 — Internal configuration error

  • Cause: An unexpected error occurred while loading or parsing the configuration.

  • Fix: Check the configuration file for syntax errors (malformed JSON). Verify environment variables are set correctly if using envconfig overrides.

• Azure authentication failure (401 / 403)

  • Cause: Invalid or expired credentials or insufficient permissions.

  • Fix: Verify the tenant_id, client_id, and client_secret values. Ensure the app registration has not expired. Confirm the credential has the Required Access Rights on the target vaults.

• Vault not found or inaccessible (404)

  • Cause: The vault_url is incorrect, the vault has been deleted, or the vault is behind a private endpoint without network access.

  • Fix: Verify the vault URL. Check the sensor machine can reach the vault endpoint.

• Rate limited (429)

  • Cause: Too many concurrent requests to Azure Key Vault APIs.

  • Fix: Reduce threads_per_target and threads_per_vault values. The sensor will automatically retry with backoff in most cases.

Getting Support

Collect diagnostic information:

• Sensor version (-version flag)

• Configuration file (redact secrets and client credentials)

• Log output (run with -l debug for verbose logs)

• Azure details (subscription ID, vault URL, authentication method)

Contact Support:

• Portal: https://support.keyfactor.com