Configuring an Azure Key Vault Connection

OneSchema integrates with Azure Key Vault to retrieve secrets at runtime for use in Multi FileFeed workflows. This keeps sensitive material — such as PGP decryption keys and passphrases — in your own Azure tenant rather than in OneSchema.

This guide walks you through:

1. Preparing your Azure App Registration and Key Vault access
2. Creating an Azure Key Vault account (connection) in OneSchema
3. Adding managed secret references
4. Testing the connection

You can configure Key Vault connections via the OneSchema dashboard or via the API — this guide covers both.

How it works

sequenceDiagram
    participant Workflow as Multi FileFeed Workflow
    participant OS as OneSchema
    participant Entra as Microsoft Entra (Azure AD)
    participant KV as Azure Key Vault

    Note over Workflow,KV: Runtime secret retrieval (e.g. Decrypt Files node)

    Workflow->>OS: Trigger node that needs a secret
    OS->>Entra: POST /{tenant}/oauth2/v2.0/token<br/>(client credentials grant)
    Entra-->>OS: Bearer token
    OS->>KV: GET /secrets/{name}[/{version}]<br/>(Authorization: Bearer)
    KV-->>OS: Secret value (plaintext)
    OS->>Workflow: Secret used in execution of a single node in a single node run
    Note over OS,KV: Secret value is never stored in OneSchema

• Create an App Registration (service principal) in your Azure tenant and grant it read access to the Key Vault secrets you want to use in OneSchema
• Provide the App Registration's credentials (Tenant ID, Client ID, and Client Secret) to OneSchema via the dashboard

OneSchema authenticates directly with Azure using the OAuth 2.0 client credentials flow — there is no intermediate identity or role chaining.

If you already have an App Registration with Key Vault access configured, you can skip ahead to Step 2.

Prerequisites

• Admin role in your OneSchema organization (required to create and manage connections)
• The Azure Key Vault feature enabled for your organization (contact your OneSchema representative if you do not see the Azure Key Vault tab on the Connections page)
• An Azure subscription with permissions to create App Registrations and assign RBAC roles
• One or more secrets already stored in an Azure Key Vault
• The following Azure values on hand:

Step 1 — Prepare your Azure resources

OneSchema authenticates to Azure Key Vault using an App Registration (service principal) with the OAuth 2.0 client credentials flow.

1a. Create an App Registration

If you do not already have a dedicated App Registration for OneSchema, create one:

az ad app create --display-name OneSchemaKeyVaultReader

Note the appId (client ID) from the output, then create a service principal:

az ad sp create --id <APP_ID>

Generate a client secret:

az ad app credential reset \
  --id <APP_ID> \
  --display-name "OneSchema Key Vault access" \
  --years 2

This outputs the appId, password (client secret), and tenant. Record all three values.

Client secret expiry: Azure client secrets expire. Set a calendar reminder to rotate the secret before expiry. When you rotate, update the connection in OneSchema — no code changes are needed.

1b. Grant the App Registration access to Key Vault secrets

OneSchema requires the Key Vault Secrets User built-in role, which grants permission to read secret values and metadata.

Option A — Azure RBAC (recommended):

If your Key Vault uses the Azure role-based access control permission model, scope the role assignment to the individual secret (recommended):

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <APP_ID> \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<VAULT_NAME>/secrets/<SECRET_NAME>

If you need to grant access to all secrets in the vault:

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee <APP_ID> \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<VAULT_NAME>

Option B — Vault access policy (legacy):

If your Key Vault uses the vault access policy permission model:

az keyvault set-policy \
  --name <VAULT_NAME> \
  --spn <APP_ID> \
  --secret-permissions get

Which permission model? Check in the Azure portal: Key Vault → Settings → Access configuration. The Permission model field shows either "Azure role-based access control" or "Vault access policy".

Storing secrets correctly

OneSchema expects secret values to be stored as raw text in Azure Key Vault:

• PGP private key: Store the full ASCII-armored key block starting with -----BEGIN PGP PRIVATE KEY BLOCK----- and ending with -----END PGP PRIVATE KEY BLOCK-----. Do not strip line breaks, wrap in JSON, or add quotes. Use the --file flag on the CLI to read the key directly from the .asc file:

  Bash

  az keyvault secret set \
    --vault-name <VAULT_NAME> \
    --name <SECRET_NAME> \
    --file /path/to/secret-key.asc

• Symmetric passphrase: Store the passphrase as a plain string:

  Bash

  az keyvault secret set \
    --vault-name <VAULT_NAME> \
    --name <SECRET_NAME> \
    --value '<PASSPHRASE>'

Important: Do not paste multi-line values using --value — the Azure CLI and portal text field may strip newlines or introduce encoding issues. Always use --file for multi-line content such as PGP keys.

Step 2 — Create an Azure Key Vault account

An "account" represents the App Registration credentials that OneSchema uses to authenticate to your Azure tenant. You can create one via the dashboard or the API.

Option A — Dashboard

Navigate to Settings → Connections in the OneSchema dashboard, then select the Azure Key Vault tab.

Click Create Azure Key Vault connection. In the dialog, fill in:

Click Create connection. The new connection appears in the table showing the Client ID.

Option B — API

curl -X POST "https://api.oneschema.co/v0/azure-key-vault/accounts" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Decryption Keys",
    "tenant_id": "<TENANT_ID>",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>"
  }'

Save the returned id — this is the account_id used when creating managed secrets and testing the connection.

Response:

{
  "id": 1,
  "name": "Production Decryption Keys",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "has_client_secret": true,
  "created_at": "2026-04-30T12:00:00Z",
  "updated_at": "2026-04-30T12:00:00Z"
}

The client_secret value is never returned in API responses — only a has_client_secret boolean.

Only Admin users can create, edit, or delete connections. Developer-role users can view connections and manage managed secrets.

Step 3 — Add managed secrets

Managed secrets are references to specific secrets in Azure Key Vault. They do not store the secret value in OneSchema — only the identifier needed to fetch it at runtime.

Option A — Dashboard

1. In the connections table, click the expand arrow (▶) next to your connection to reveal the Managed Secrets panel.

2. Click Add secret.

3. Fill in the following fields:

4. Click Create secret.

The managed secret now appears in the panel table with its identifier, vault, and version information.

Option B — API

curl -X POST "https://api.oneschema.co/v0/azure-key-vault/accounts/1/secrets" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PGP Decryption Key - Vendor A",
    "secret_identifier": "my-gpg-key",
    "vault": "https://myvault.vault.azure.net"
  }'

Replace 1 in the URL with the account_id returned in Step 2.

Response:

{
  "id": 10,
  "name": "PGP Decryption Key - Vendor A",
  "account_id": 1,
  "secret_identifier": "my-gpg-key",
  "vault": "https://myvault.vault.azure.net",
  "secret_version": null,
  "created_at": "2026-04-30T12:00:00Z",
  "updated_at": "2026-04-30T12:00:00Z"
}

Step 4 — Test the connection

Before using the secret in a workflow, verify that OneSchema can successfully authenticate and retrieve it.

Option A — Dashboard

1. In the connections table, click the ⋮ (actions) menu on your connection row and select Test connection.

2. In the test dialog, select a managed secret from the dropdown and click Test.

If successful, you will see a green confirmation message.

Option B — API

curl -X POST "https://api.oneschema.co/v0/azure-key-vault/accounts/1/test" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret_identifier": "my-gpg-key",
    "vault": "https://myvault.vault.azure.net"
  }'

A successful response:

{
  "success": true,
  "request_id": "abc-123",
  "transaction_id": "txn-456"
}

A failed response includes an error_category to help diagnose the issue:

{
  "success": false,
  "error_code": "AUTH_FAILED",
  "error_category": "account",
  "error_message": "Authentication failed",
  "request_id": "abc-123",
  "transaction_id": "txn-456"
}

Error reference

If the test fails, the dialog displays a categorized error:

Next steps

With your account and managed secrets configured, you can use them in the Decrypt Files node to decrypt GPG/PGP-encrypted files in your Multi FileFeed workflows.

Editing and deleting

• Edit an account: Click the ⋮ menu on the connection row and select Edit. You can update the name, description, Tenant ID, Client ID, and Client Secret. Existing managed secrets are preserved. Via the API: PATCH /v0/azure-key-vault/accounts/{id}.
• Edit a managed secret: Expand the connection's managed secrets panel, click the ⋮ menu on the secret row, and select Edit. Via the API: PATCH /v0/azure-key-vault/secrets/{id}.
• Delete: Connections and managed secrets can be deleted via their ⋮ menus. A connection cannot be deleted while it has managed secrets attached. Via the API: DELETE /v0/azure-key-vault/accounts/{id} or DELETE /v0/azure-key-vault/secrets/{id}.

Security recommendations

1. Scope RBAC assignments narrowly. Assign Key Vault Secrets User at the individual-secret level when possible, rather than the vault level.
2. Use a dedicated App Registration. Do not reuse an App Registration that has permissions to other Azure resources.
3. Rotate client secrets before expiry. Set a rotation reminder and use az ad app credential reset to generate a new secret, then update the OneSchema connection.
4. Enable Key Vault audit logging. Send audit logs to a Log Analytics workspace to monitor secret access.