Environment Variables Reference

This document provides a comprehensive reference for all environment variables used to configure Sombra. Variables are organized by functional category to help you quickly find the settings you need.

These environment variables define the basic configuration of your Sombra cluster.

Environment Variable	Description	Default	Required
`ORGANIZATION_URI`	The unique identifier for your organization in Transcend	-	Yes
`SOMBRA_ID`	The unique identifier for this Sombra cluster	-	Yes
`TRANSCEND_URL`	The base URL for the Transcend API	`https://api.transcend.io` (EU) or `https://api.us.transcend.io` (US)	Yes
`DD_SERVICE_NAME`	The name for your Sombra service in logs and metrics	`transcend-hosted-sombra`	No

These variables control how Sombra communicates over the network.

Environment Variable	Description	Default	Required
`INTERNAL_PORT_HTTPS`	Port for the internal HTTPS server (faces inside firewall)	`5040`	No (unless `INTERNAL_PORT_HTTP` is undefined)
`INTERNAL_PORT_HTTP`	Port for the internal HTTP server (faces inside firewall)	`5039`	No (unless `INTERNAL_PORT_HTTPS` is undefined)
`EXTERNAL_PORT_HTTPS`	Port for the external HTTPS server (faces outside firewall)	`5041`	No (only for Direct Connection method)
`EXTERNAL_PORT_HTTP`	Port for the external HTTP server (faces outside firewall)	`5042`	No (only for Direct Connection method)
`LLM_CLASSIFIER_URL`	URL for the LLM Classifier service	-	No (only if using LLM Classifier)
`LLM_SERVER_PORT`	Port the LLM Classifier listens on	`6081`	No

These variables configure the Reverse Tunnel connection between Sombra and Transcend.

Environment Variable	Description	Default	Required
`SOMBRA_REVERSE_TUNNEL_API_KEY`	API key used to authenticate the Reverse Tunnel connection	-	Yes (for Reverse Tunnel method)

These variables configure TLS certificates for secure HTTPS connections.

Environment Variable	Description	Default	Required
`SOMBRA_TLS_CERT`	The Sombra TLS Certificate, base64 encoded	-	No (only for Direct Connection method with HTTPS)
`SOMBRA_TLS_KEY`	The TLS private key, base64 encoded in PEM format	-	No (only for Direct Connection method with HTTPS)
`SOMBRA_TLS_KEY_PASSPHRASE`	An optional passphrase for the TLS private key	-	No
`TRUSTED_CLIENT_CA_CERT_ENCODED`	Public CA certificate for mutual TLS authentication	-	No
`LLM_CERT_PATH`	Path to SSL certificate for LLM Classifier HTTPS	-	No
`LLM_KEY_PATH`	Path to SSL key file for LLM Classifier HTTPS	-	No

These variables configure how encryption keys are managed by Sombra.

Environment Variable	Description	Default	Required
`JWT_ECDSA_KEY`	JSON Web Token asymmetric key(s) for signing Sombra payloads	-	Yes
`INTERNAL_KEY_HASH`	Hash of the internal key used to authenticate internal API requests	-	No
`KMS_PROVIDER`	Key Management Service provider to use	`local`	No
`AWS_KMS_KEY_ARN`	Amazon Resource Name for AWS KMS	-	Yes (when `KMS_PROVIDER=AWS`)
`AWS_REGION`	AWS Region where AWS KMS is hosted	-	Yes (when `KMS_PROVIDER=AWS`)
`AWS_KMS_THROW_PERMISSIONS_ERRORS`	Flag to throw errors related to permissions in AWS KMS	`false`	No
`AWS_KMS_CUSTOM_KEY_STORE_ID`	ID of a Custom AWS CloudHSM key store	-	No

These variables configure authentication for employees (administrators).

Environment Variable	Description	Default	Required
`EMPLOYEE_AUTHENTICATION_METHODS`	Allowed authentication methods for employees	`session,transcend`	No
`EMPLOYEE_SESSION_EXPIRY_TIME`	Duration of employee session JWT	`3 hours`	No
`SAML_ENTRYPOINT`	Login endpoint where SAML assertion comes from	-	Yes (for SAML auth)
`SAML_CERT`	Public key to validate SAML assertion	-	Yes (for SAML auth)
`SAML_ISSUER`	Issuer of the SAML certificate	`transcend`	No
`SAML_AUDIENCE`	Audience of the SAML assertion	`transcend`	No
`ACCEPT_CLOCK_SKEWED_MS`	Artificially skew clock for validating assertion expiration	-	No

These variables configure authentication for data subjects (end-users).

Environment Variable	Description	Default	Required
`DATA_SUBJECT_AUTHENTICATION_METHODS`	Allowed authentication methods for data subjects	-	Yes
`DATA_SUBJECT_SESSION_EXPIRY_TIME`	Duration of data subject session JWT	`5 days`	No
`JWT_AUTHENTICATION_PUBLIC_KEY`	Public key for verifying JWT magic links	-	Yes (for JWT auth)
`OAUTH_CLIENT_ID`	Client ID of Privacy Center's OAuth 2 application	-	Yes (for OAuth auth)
`OAUTH_CLIENT_SECRET`	Client Secret of Privacy Center's OAuth 2 application	-	Yes (for OAuth auth)
`OAUTH_GET_TOKEN_URL`	Endpoint to make Access Token Request	-	Yes (for OAuth auth)
`OAUTH_GET_TOKEN_BODY_GRANT_TYPE`	Grant type for OAuth token	-	No
`OAUTH_GET_TOKEN_BODY_REDIRECT_URI`	Redirect URI for successful response	-	Yes (for OAuth auth)
`OAUTH_GET_TOKEN_METHOD`	HTTP method for retrieving OAuth token	`POST`	No
`OAUTH_GET_TOKEN_HEADERS`	Headers for retrieving OAuth token	-	No
`OAUTH_GET_CORE_ID_DATA_SUBJECT_TYPE`	Type of Data Subject for OAuth	-	Yes (for OAuth auth)
`OAUTH_GET_CORE_ID_URL`	API endpoint to retrieve user ID	-	Yes (for OAuth auth)
`OAUTH_GET_CORE_ID_PATH`	JSON path to extract user ID	-	Yes (for OAuth auth)
`OAUTH_GET_EMAIL_URL`	API endpoint to find user email	-	Yes (for OAuth auth)
`OAUTH_GET_EMAIL_PATH`	JSON path to extract email	-	Yes (for OAuth auth)
`OAUTH_EMAIL_IS_VERIFIED`	Whether all emails have been verified previously	-	No
`OAUTH_EMAIL_IS_VERIFIED_PATH`	JSON path to extract email verification status	-	No
`OAUTH_GET_PROFILE_PICTURE_URL`	API endpoint for user profile picture	-	No
`OAUTH_GET_PROFILE_PICTURE_PATH`	JSON path to extract profile picture URL	-	No

These variables configure database connection pooling in Sombra.

Environment Variable	Description	Default	Required
`ODBC_POOL_CACHE_SIZE`	Maximum size of LRU cache for connection pools	-	Yes (for connection pooling)
`ODBC_QUERY_TIMEOUT_IN_SECONDS`	Maximum time to wait for ODBC queries	`60`	No
`ODBC_CONNECTION_TIMEOUT_IN_SECONDS`	Seconds to wait for connection requests	`0`	No
`ODBC_LOGIN_TIMEOUT_IN_SECONDS`	Seconds to wait for login requests	`10`	No
`ODBC_CONNECTION_MAX_POOL_SIZE`	Maximum open connections in the pool	`100`	No
`ODBC_CONNECTION_INITIAL_POOL_SIZE`	Initial connections created in the pool	`10`	No
`ODBC_CONNECTION_POOL_SIZE_INCREMENT`	Additional connections created when pool is full	`10`	No
`REUSE_ODBC_CONNECTIONS`	Whether to reuse existing connections	`true`	No
`ODBC_CONNECTION_POOL_SIZE_SHRINK`	Whether connections should shrink to initial size	`true`	No

These variables configure logging and monitoring for Sombra.

Environment Variable	Description	Default	Required
`RUN_DATADOG_APM`	Initialize Datadog tracing	`true`	No
`DD_APM_PORT`	Datadog Agent APM port for trace data	`8126`	No
`DD_HOST`	Datadog Agent host for metrics and traces	`localhost`	No
`DD_STATSD_PORT`	Datadog Agent metric port	`8125`	No
`DD_APM_BLOCKLIST`	Blocklist of routes to pass to trace	`[]`	No
`DD_APM_ANALYTICS`	Filter Analyzed Spans by user-defined tags	`true`	No
`DD_APM_LOG_INJECTION`	Enable injection of trace IDs in logs	`true`	No
`DD_APM_RUNTIME_METRICS`	Enable capturing runtime metrics	`true`	No
`DD_TRACE_DEBUG`	Enable debug logging in tracer	`false`	No
`LOG_HTTP_TRANSPORT_URL`	Transcend Collector's HTTPS ingress endpoint	-	Yes (for log forwarding)
`LOG_HTTP_TRANSPORT_BATCH_INTERVAL_MS`	Maximum time between batched logs	`5000`	No
`LOG_HTTP_TRANSPORT_BATCH_COUNT`	Maximum log lines per batch	`10`	No
`LOG_FORWARDING_TRANSCEND_API_KEY`	API key for forwarding LLM Classifier logs	-	Yes (for LLM log forwarding)

These variables configure integration with HashiCorp Vault for secrets management.

Environment Variable	Description	Default	Required
`ENABLE_VAULT_FETCHER`	Enable Vault integration	-	Yes (for Vault integration)
`VAULT_AGENT_URI`	URI of the Vault agent	-	Yes (for Vault integration)
`VAULT_PATH_SOMBRA_JWT_ECDSA_KEY`	Vault path for JWT_ECDSA_KEY	-	No
`VAULT_VERSION_SOMBRA_JWT_ECDSA_KEY`	Vault version for JWT_ECDSA_KEY	-	No
`VAULT_KEY_SOMBRA_JWT_ECDSA_KEY`	Vault key name for JWT_ECDSA_KEY	-	No
`VAULT_PATH_SOMBRA_TLS_KEY_PASSPHRASE`	Vault path for TLS_KEY_PASSPHRASE	-	No
`VAULT_VERSION_SOMBRA_TLS_KEY_PASSPHRASE`	Vault version for TLS_KEY_PASSPHRASE	-	No
`VAULT_KEY_SOMBRA_TLS_KEY_PASSPHRASE`	Vault key name for TLS_KEY_PASSPHRASE	-	No
`VAULT_PATH_SOMBRA_TLS_CERT`	Vault path for TLS_CERT	-	No
`VAULT_VERSION_SOMBRA_TLS_CERT`	Vault version for TLS_CERT	-	No
`VAULT_KEY_SOMBRA_TLS_CERT`	Vault key name for TLS_CERT	-	No
`VAULT_PATH_SOMBRA_TLS_KEY`	Vault path for TLS_KEY	-	No
`VAULT_VERSION_SOMBRA_TLS_KEY`	Vault version for TLS_KEY	-	No
`VAULT_KEY_SOMBRA_TLS_KEY`	Vault key name for TLS_KEY	-	No
`VAULT_PATH_TRUSTED_CLIENT_CA_CERT_ENCODED`	Vault path for CLIENT_CA_CERT	-	No
`VAULT_VERSION_TRUSTED_CLIENT_CA_CERT_ENCODED`	Vault version for CLIENT_CA_CERT	-	No
`VAULT_KEY_TRUSTED_CLIENT_CA_CERT_ENCODED`	Vault key name for CLIENT_CA_CERT	-	No

When configuring Sombra environment variables, keep these best practices in mind:

Security First: Keep your JWT_ECDSA_KEY and other security keys secure. Consider using a secrets management solution like HashiCorp Vault.
Key Rotation: Periodically rotate your encryption keys using the guidance in the Key Rotation documentation.
Minimal Permissions: When configuring authentication methods, start with the minimum necessary and add more as required.
Documentation: Keep track of your environment variable configurations, especially when managing multiple Sombra clusters.
Testing: Always test your configuration in a non-production environment before deploying to production.

Environment Variables Reference

Core Configuration

Networking

Reverse Tunnel Configuration

TLS Configuration

Key Management

Authentication - Employee

Authentication - Data Subject

Connection Pooling

Logging and Monitoring

HashiCorp Vault Integration

Best Practices

Environment Variables Reference

Core Configuration

Networking

Reverse Tunnel Configuration

TLS Configuration

Key Management

Authentication - Employee

Authentication - Data Subject

Connection Pooling

Logging and Monitoring

HashiCorp Vault Integration

Best Practices

Related Documentation