⚡︎ BoxLang+ Module: Azure Key Vault Secrets Module

|:------------------------------------------------------:  |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:  |

Copyright Since 2025 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

 

This module integrates Azure Key Vault with BoxLang's getSystemSetting() BIF by registering a system setting provider under the azure namespace. Secrets stored in Azure Key Vault become accessible via the standard getSystemSetting() function using dot-notation:

dbPassword = getSystemSetting( "azure.DB-PASSWORD" )
apiKey     = getSystemSetting( "azure.API-KEY", "default-value" )

---

Requirements

• BoxLang 1.14+
• bx-plus module (BoxLang+ Subscription)
• Azure identity with Key Vault secrets/get permission

---

Installation

box install bx-azure-secrets

Or use the module installer appropriate to your runtime as described in the Module Installation Guide.

A BoxLang+ Subscription is required for use. Without a subscription, the module operates in trial mode for 30 days.

---

Bug Reporting

Feature Requests and Bug Reports may be submitted via JIRA.

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files that we might need to replicate your issue. All issues that do not contain a way to replicate will not be addressed.

---

Support Questions

If you have any questions on usage, professional support or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

• Ortus Community Discourse: https://community.ortussolutions.com
• Box Slack Team: http://boxteam.ortussolutions.com/
• Professional Support: https://www.ortussolutions.com/services/support

---

Configuration

Credentials and settings can be provided via three sources, resolved in priority order:

1. Application.bx (Per-Application)

Define a this.azure struct in your Application.bx to provide per-application settings. These override module-level settings:

// Application.bx
class {
    this.name = "MyApp"

    this.azure = {
        vaultUrl     : "https://my-vault.vault.azure.net/",
        tenantId     : "",     // optional; required only for explicit client-secret auth
        clientId     : "",     // optional; app registration or user-assigned managed identity client id
        clientSecret : "",     // optional; only for explicit client-secret auth
        cacheTTL     : 300     // seconds (default: 300)
    }
}

2. Module Settings (Global)

Configure in boxlang.json under the module settings:

{
    "modules": {
        "bxazure-secrets": {
            "settings": {
                "vaultUrl": "https://my-vault.vault.azure.net/",
                "tenantId": "",
                "clientId": "",
                "clientSecret": "",
                "cacheTTL": 300
            }
        }
    }
}

3. Environment Variables (Zero-Config)

If no explicit credentials are configured, the module falls back to standard Azure environment variables and DefaultAzureCredential sources such as managed identity, workload identity, Azure CLI, and environment credentials:

Setting	Environment Variable
Vault URL	AZURE_KEY_VAULT_URL or AZURE_KEYVAULT_URL
Tenant ID	AZURE_TENANT_ID
Client ID	AZURE_CLIENT_ID
Client Secret	AZURE_CLIENT_SECRET

This is ideal for Azure-hosted environments (Azure Functions, App Service, Container Apps, AKS, Virtual Machines) where managed identity can provide credentials automatically.

Settings Summary

Setting	Type	Default	Description
vaultUrl	string	""	Azure Key Vault URL (e.g. https://my-vault.vault.azure.net/). Required from at least one source.
tenantId	string	""	Optional Azure tenant ID for explicit service-principal authentication
clientId	string	""	Optional application client ID or user-assigned managed identity client ID
clientSecret	string	""	Optional Azure client secret for service-principal authentication
cacheTTL	numeric	300	Secret cache TTL in seconds. Secrets are cached in-memory to reduce API calls.

---

Usage

Once installed and configured, use getSystemSetting() with the azure. prefix to resolve secrets:

// Basic usage
dbPassword = getSystemSetting( "azure.DB-PASSWORD" )

// With a default value (returned if the secret is not found)
apiKey = getSystemSetting( "azure.API-KEY", "default-key" )

// In datasource configuration
datasources = {
    "mydb": {
        "class": "org.postgresql.Driver",
        "connectionString": "jdbc:postgresql: //localhost:5432/mydb",
        "username": "app_user",
        "password": getSystemSetting( "azure.DB-PASSWORD" )
    }
}

How Resolution Works

When getSystemSetting("azure.SECRET-NAME") is called:

1. The module checks for a cached value (within the configured TTL)
2. If not cached, it calls Azure Key Vault's getSecret() API
3. The result is cached and returned
4. If the secret is not found or any error occurs, null is returned and BoxLang falls through to system properties and environment variables

Credential Resolution Order

Each setting is resolved independently through the 3-tier chain:

this.azure (Application.bx)  →  Module settings (boxlang.json)  →  Azure Environment Variables / DefaultAzureCredential

This means you can, for example, set vaultUrl in module settings while credentials come from managed identity or environment variables.

---

Caching

Secrets are cached in-memory with a configurable TTL (default: 300 seconds / 5 minutes). This reduces Key Vault API calls and latency. The cache key includes the vault URL, so the same secret name in different vaults is cached independently.

To disable caching, set cacheTTL to 0. To increase cache duration for rarely-changing secrets, set a higher value.

---

Per-Application Isolation

Each BoxLang application that defines this.azure gets its own SecretClient instance. When an application shuts down or times out, its client reference is released.

Applications without this.azure share a single global client built from module settings or environment variables/default credential sources.

---

Local Development with Azure CLI

For local development, authenticate with the Azure CLI and provide the vault URL:

az login
az keyvault secret set --vault-name my-vault --name DB-PASSWORD --value "my-local-password"

{
    "modules": {
        "bxazure-secrets": {
            "settings": {
                "vaultUrl": "https://my-vault.vault.azure.net/"
            }
        }
    }
}

Azure Key Vault secret names can contain only alphanumeric characters and hyphens.

---

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12