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

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

---

Requirements

• BoxLang 1.14+
• bx-plus module (BoxLang+ Subscription)
• Google Cloud project with Secret Manager enabled
• Google identity with secretmanager.versions.access permission

---

Installation

box install bx-google-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.

---

Configuration

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

1. Application.bx (Per-Application)

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

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

    this.google = {
        projectId       : "my-gcp-project",
        credentialsPath : "",   // optional service account JSON file path
        credentialsJson : "",   // optional raw service account JSON content
        cacheTTL        : 300   // seconds (default: 300)
    }
}

2. Module Settings (Global)

Configure in boxlang.json under the module settings:

{
    "modules": {
        "bxgoogle-secrets": {
            "settings": {
                "projectId": "my-gcp-project",
                "credentialsPath": "",
                "credentialsJson": "",
                "cacheTTL": 300
            }
        }
    }
}

3. Environment Variables / Application Default Credentials

If explicit credentials are not configured, the module uses Google Application Default Credentials, which supports service account credentials, attached workload identity, metadata server credentials, and local gcloud authentication.

Setting	Environment Variable
Project ID	GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT
Credentials file	GOOGLE_APPLICATION_CREDENTIALS
Credentials JSON	GOOGLE_CREDENTIALS_JSON

This is ideal for Google Cloud-hosted environments such as Cloud Run, Cloud Functions, GKE, Compute Engine, and App Engine where the runtime service account can provide credentials automatically.

Settings Summary

Setting	Type	Default	Description
projectId	string	""	Google Cloud project ID. Required from at least one source.
credentialsPath	string	""	Optional service account JSON file path.
credentialsJson	string	""	Optional raw service account JSON content. Prefer credentialsPath or ADC when possible.
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 google. prefix to resolve secrets:

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

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

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

How Resolution Works

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

1. The module checks for a cached value (within the configured TTL)
2. If not cached, it calls Google Secret Manager's accessSecretVersion() API for the latest version
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.google (Application.bx)  →  Module settings (boxlang.json)  →  Google environment variables / Application Default Credentials

This means you can set projectId in module settings while credentials come from a Cloud Run service account or GOOGLE_APPLICATION_CREDENTIALS.

---

Caching

Secrets are cached in-memory with a configurable TTL (default: 300 seconds / 5 minutes). This reduces Secret Manager API calls and latency. The cache key includes the project ID, so the same secret name in different projects is cached independently.

To disable practical cache reuse, 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.google gets its own SecretManagerServiceClient instance. When an application shuts down or times out, its client is closed.

Applications without this.google share a single global client built from module settings or environment variables/Application Default Credentials.

---

Local Development with gcloud

For local development, authenticate with the Google Cloud CLI and provide the project ID:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
gcloud secrets create DB_PASSWORD --replication-policy="automatic"
gcloud secrets versions add DB_PASSWORD --data-file=- <<< "my-local-password"

{
    "modules": {
        "bxgoogle-secrets": {
            "settings": {
                "projectId": "my-gcp-project"
            }
        }
    }
}

Google Secret Manager secret IDs can contain letters, numbers, hyphens, and underscores.

---

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