⚡︎ BoxLang+ Module: AWS Integration 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 AWS Secrets Manager with BoxLang's getSystemSetting() BIF by registering a system setting provider under the aws namespace. Secrets stored in AWS Secrets Manager become accessible via the standard getSystemSetting() function using dot-notation:

dbPassword = getSystemSetting( "aws.DB_PASSWORD" )
apiKey     = getSystemSetting( "aws.API_KEY", "default-value" )

---

Requirements

• BoxLang 1.14+
• bx-plus module (BoxLang+ Subscription)
• AWS credentials with secretsmanager:GetSecretValue permission

---

Installation

box install bx-aws-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.aws struct in your Application.bx to provide per-application credentials. These override module-level settings:

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

    this.aws = {
        region          : "us-east-2",
        accessKeyId     : "AKIA...",
        secretAccessKey : "wJalr...",
        sessionToken    : "",           // optional
        cacheTTL        : 300,          // seconds (default: 300)
        endpointOverride : ""           // optional (for LocalStack)
    }
}

2. Module Settings (Global)

Configure in boxlang.json under the module settings:

{
    "modules": {
        "bxaws-secrets": {
            "settings": {
                "region": "us-east-2",
                "accessKeyId": "AKIA...",
                "secretAccessKey": "wJalr...",
                "sessionToken": "",
                "cacheTTL": 300,
                "endpointOverride": ""
            }
        }
    }
}

3. Environment Variables (Zero-Config)

If no explicit credentials are configured, the module falls back to standard AWS environment variables:

Setting	Environment Variable
Region	AWS_REGION or AWS_DEFAULT_REGION
Access Key ID	AWS_ACCESS_KEY_ID
Secret Access Key	AWS_SECRET_ACCESS_KEY
Session Token	AWS_SESSION_TOKEN

This is ideal for AWS-hosted environments (EC2, ECS, Lambda) where IAM roles provide credentials automatically.

Settings Summary

Setting	Type	Default	Description
region	string	""	AWS region (e.g. us-east-2). Required from at least one source.
accessKeyId	string	""	AWS access key ID
secretAccessKey	string	""	AWS secret access key
sessionToken	string	""	Optional AWS session token for temporary credentials
cacheTTL	numeric	300	Secret cache TTL in seconds. Secrets are cached in-memory to reduce API calls.
endpointOverride	string	""	Custom endpoint URL (useful for LocalStack testing)

---

Usage

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

// Basic usage
dbPassword = getSystemSetting( "aws.DB_PASSWORD" )

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

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

How Resolution Works

When getSystemSetting("aws.SECRET_NAME") is called:

1. The module checks for a cached value (within the configured TTL)
2. If not cached, it calls AWS Secrets Manager's GetSecretValue 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.aws (Application.bx)  →  Module settings (boxlang.json)  →  AWS Environment Variables

This means you can, for example, set region in module settings while accessKeyId comes from environment variables.

---

Caching

Secrets are cached in-memory with a configurable TTL (default: 300 seconds / 5 minutes). This reduces AWS API calls and latency. The cache key includes the region, so the same secret name in different regions 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.aws gets its own SecretsManagerClient instance. When an application shuts down or times out, its client is automatically closed to prevent connection leaks.

Applications without this.aws share a single global client built from module settings or environment variables.

---

Local Development with LocalStack

For local development, point the module at a LocalStack instance:

{
    "modules": {
        "bxaws-secrets": {
            "settings": {
                "region": "us-east-1",
                "accessKeyId": "test",
                "secretAccessKey": "test",
                "endpointOverride": "http://localhost:4566"
            }
        }
    }
}

Then create secrets in LocalStack:

aws --endpoint-url=http://localhost:4566 secretsmanager create-secret \
    --name DB_PASSWORD \
    --secret-string "my-local-password"

---

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