AWS Secrets +

AWS Secrets Manager integration for BoxLang system settings via the aws. namespace in getSystemSetting().

This module is only available to +/++ subscribers only, and requires a valid bx-plus license.

The bx-aws-secrets module registers an aws system setting provider so BoxLang can resolve secrets directly from AWS Secrets Manager using getSystemSetting().

✨ Features

• Resolve secrets with getSystemSetting( "aws.SECRET_NAME" )
• 3-tier configuration resolution per setting: this.aws in Application.bx, module settings, then AWS environment variables
• In-memory TTL caching to reduce Secrets Manager API calls
• Per-application SecretsManagerClient isolation when this.aws is defined
• Automatic client cleanup on application shutdown
• Graceful fallback behavior: returns null on provider errors so normal getSystemSetting() fallback continues

📦 Requirements

• BoxLang 1.14+
• bx-plus module
• AWS IAM permissions to read secrets (secretsmanager:GetSecretValue)

🚀 Installation

Via CommandBox

box install bx-plus,bx-aws-secrets

Via BoxLang OS Binary

install-bx-module bx-plus bx-aws-secrets

⚡ Quick Start

1. Install and activate bx-plus and bx-aws-secrets
2. Configure credentials through this.aws, module settings, or AWS environment variables
3. Resolve secrets with aws. namespaced keys

dbPassword = getSystemSetting( "aws.DB_PASSWORD" )
apiKey = getSystemSetting( "aws.API_KEY", "fallback-key" )

⚙️ Basic Configuration

Use module settings in boxlang.json when you want global defaults:

{
  "modules": {
    "bxaws-secrets": {
      "settings": {
        "region": "us-east-2",
        "accessKeyId": "${AWS_ACCESS_KEY_ID}",
        "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}",
        "sessionToken": "",
        "cacheTTL": 300,
        "endpointOverride": ""
      }
    }
  }
}

The module id for installation is bx-aws-secrets, while module settings are keyed under bxaws-secrets.

For per-app overrides and LocalStack examples, see Configuration & Usage.

🔍 How Secret Resolution Works

For getSystemSetting( "aws.MY_SECRET" ), the provider:

1. Resolves effective AWS settings (3-tier lookup)
2. Checks in-memory cache using region:secretName
3. Calls AWS Secrets Manager when cache is stale/missing
4. Caches and returns the secret value
5. Returns null on lookup failure, allowing standard BoxLang fallback behavior

🔗 Related Documentation

Configuration & UsageModulesPlus Core