# Secrets Vaults

## Overview

This guide explains how to configure external secret vaults to securely store sensitive credentials for Veza integrations. Secret vaults enable customers to store sensitive information, such as usernames, passwords, authentication tokens, and certificates, in their private network environments rather than storing them in Veza.

When using secrets vaults, Veza stores only the secret identifiers (names or IDs) rather than the actual credential values. This approach ensures sensitive information never leaves your private network while allowing Veza's discovery and extraction processes to access required credentials dynamically.

## How it works

The Secrets Vaults feature follows a secure retrieval flow:

{% @mermaid/diagram content="sequenceDiagram
participant User as Security Admin
participant Veza as Veza Platform
participant IP as Insight Point
participant Vault as External Vault (Azure Key Vault)
participant Target as Target System (AD/Okta/LDAP)

```
User->>Veza: Configure integration with<br/>secret reference
Veza->>Veza: Store secret reference only
Note over Veza,IP: Discovery/Extraction starts
Veza->>IP: Request data using secret reference
IP->>Vault: Authenticate and retrieve secret
Vault->>IP: Return actual secret
IP->>Target: Authenticate using secret
Target->>IP: Return data
IP->>Veza: Return extracted data
Note over IP: Secret discarded from memory" %}
```

The integration works as follows:

1. Your organization's vault credentials are stored exclusively on the external Insight Point in your environment. Veza never has access to these credentials outside of the discovery/extractor processes that run in your environment.
2. Veza stores only the references (IDs/names) to the secrets in your vault, not the actual secret values themselves.
3. When an integration needs to authenticate during discovery or extraction, Veza uses the vault credentials to dynamically fetch the required secret from your external vault.
4. After the discovery or extraction process completes, all secrets are discarded from memory. Veza never stores the actual secret values in its database.

You can revoke Veza's access to your secrets at any time by disabling the Insight Point or cutting off its connection to Veza's network.

## Current limitations

In the current release, Secrets Vaults has the following limitations:

* Requires an external Insight Point
* Supports Azure Key Vault as the vault provider type
* Supported integrations:
  * Active Directory
  * Azure
  * LDAP
  * Okta
* Operates at the provider level only (datasource-level secrets are not yet supported)
* Requires all secret fields (username, password, etc.) to be stored as a single external secret in JSON format

## Before you start

Before you configure secrets vaults, ensure:

* You have an external insight point deployed and configured
* You have an Azure Key Vault instance accessible from your Insight Point
* You have appropriate permissions to create and manage secrets in Azure Key Vault
* The feature flag `INTEG_SECRETS_VAULT_EAC_47720` is enabled for your tenant
* Network connectivity exists between your Insight Point and Azure Key Vault

## Configure vault access on Insight Point

1. Create a secrets vault configuration file on your external insight point.

   The configuration file must be in YAML format and contain the Azure credentials needed to ACCESS your Key Vault. These credentials allow the Insight Point to authenticate with Azure Key Vault to retrieve the actual integration secrets.

   ```yaml
   vaults:
     - name: 'MyVault'
       vault_provider: 'azure_key_vault'
       auth_type: 'client_secret'
       auth_config:
         vault_uri: 'https://my-vault.vault.azure.net/'
         tenant_id: '11111111-2222-3333-4444-555555555555'
         client_id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
         client_secret: 'my-secret'
   ```
2. Set the environment variable for the configuration file path.

   Export the path to your secrets vault configuration file:

   ```bash
   export SECRETS_VAULTS_CONFIG_PATH="/dir1/dir2/dir3/secrets_vaults_config.yaml"
   ```

   The Insight Point will monitor the file for changes. The file can be updated without requiring an Insight Point restart.
3. Restart your external insight point.

   The insight point will read the vault configuration on startup and establish connectivity to your Azure Key Vault.

### Set up Azure AD application

To allow Veza's Insight Point to authenticate with Azure Key Vault, create an application registration in Azure Active Directory:

1. Navigate to **Azure Active Directory** > **App registrations** in the Azure portal.
2. Click **New registration**.
3. Name the application (e.g., "Veza Secrets Vault Access").
4. Select appropriate supported account types (usually single tenant).
5. Click **Register**.
6. Note the **Application (client) ID** and **Directory (tenant) ID** for your configuration.
7. Navigate to **Certificates & secrets**.
8. Create a new client secret and note the value.

   This value will only be shown once, so copy it immediately.
9. Navigate to your Azure Key Vault resource.
10. Under **Access policies**, add a policy for your new application with **Get** and **List** permissions for secrets.

## Create external secrets in Azure Key Vault

1. Navigate to your Azure Key Vault in the Azure portal.
2. Create a new secret for your integration credentials.

   Select **Secrets** from the left navigation, then click **Generate/Import**.
3. Enter the secret name and value.

   The secret name will serve as the identifier for the credentials in Veza. The secret value must be a JSON object containing all required credential fields for your integration type.
4. Format the secret value according to your integration type.

   **Active Directory:**

   ```json
   {
     "username": "domain\\serviceaccount",
     "password": "secretpassword",
     "ldaps_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
   }
   ```

   **Azure:**

   ```json
   {
     "client_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
     "client_secret": "secretclientvalue",
     "auth_certificate": "base64encodedcertificatedata",
     "auth_certificate_password": "certpassword"
   }
   ```

   Note: The `auth_certificate_password` field is optional if the certificate is not secured with a password.

   **Okta (OAuth):**

   ```json
   {
     "client_id": "0oa1a2b3c4d5e6f7g8h9",
     "private_key_id": "kid_value",
     "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----"
   }
   ```

   **Okta (API Token):**

   ```json
   {
     "token": "00A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8S9"
   }
   ```

   **LDAP:**

   ```json
   {
     "bind_dn_or_user": "cn=serviceaccount,ou=service,dc=example,dc=com",
     "bind_password": "secretpassword",
     "ca_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
   }
   ```
5. Save the secret.

   Azure Key Vault will generate a unique identifier for the secret that you'll reference when configuring your Veza integration.

## Configure provider with secrets vault

1. Navigate to the Veza integrations page.
2. Create a new integration for your supported provider type.

   Secrets vaults are currently supported for Active Directory, Azure, LDAP, and Okta integrations.
3. Select your external insight point.

   Choose the insight point where you configured the vault credentials.
4. Enable secrets vault authentication.

   When the Insight Point is configured with external secrets, you'll see a **Secrets Vault** selection. Select **External Secrets Vault** instead of **Veza Vault**.
5. Configure the vault settings.

   * **Vault Name:** Select your vault from the dropdown (e.g., "MyVault")
   * **Secret Name:** Enter the name of the secret you created in Azure Key Vault

   Standard credential fields (username, password, etc.) will be hidden when the secrets vault is enabled.
6. Complete the provider configuration and save.
7. Test the connection.

   Initiate a discovery and extraction run to verify that secrets are being fetched correctly from Azure Key Vault and that the provider connects successfully to the target system.

![Active Directory setup using external secrets vault](/files/c45KKEmo78WaRpNayKRp)

## Verification and troubleshooting

After configuring the provider with Secrets Vault:

1. Check the extraction logs to ensure the secrets are being fetched correctly from Azure Key Vault.
2. Verify that the provider connects successfully to the target system.
3. If connection fails, verify:
   * Azure Key Vault access policies are correctly configured
   * The secret JSON format matches the expected structure for your integration type
   * Network connectivity exists between the Insight Point and Azure Key Vault
   * The vault configuration file path is set correctly on the Insight Point

## See also

* [Azure Key Vault configuration reference](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/secrets-vaults/azure-key-vault.md)
* [Insight Point deployment guide](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md)
* [Active Directory integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/active-directory.md)
* [Azure integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/azure.md)
* [Okta integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/okta.md)
* [Azure Key Vault documentation](https://docs.microsoft.com/en-us/azure/key-vault/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/connectivity/secrets-vaults.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.