Skip to content
Star Fork

Variable Substitution Overview

keycloak-config-cli supports powerful variable substitution capabilities that allow you to create dynamic, environment-specific configurations.

Enabling Variable Substitution

Variable substitution is disabled by default and must be explicitly enabled:

Environment variable

export IMPORT_VAR_SUBSTITUTION_ENABLED=true
export IMPORT_VAR_SUBSTITUTION_JAVASCRIPT_ENABLED=true
export IMPORT_VAR_SUBSTITUTION_SCRIPT_EVALUATION_ENABLED=true

Command line argument

java -jar keycloak-config-cli.jar \
  --import.var-substitution.enabled=true \
  --import.var-substitution.javascript.enabled=true \
  --import.var-substitution.script-evaluation.enabled=true

Security Considerations

Environment Variables

  • Store sensitive data (passwords, secrets) in environment variables
  • Use .env files for development (never commit to version control)
  • Consider using secret management systems in production

JavaScript Substitution

  • JavaScript substitution has access to system properties
  • Use with caution in production environments
  • Validate JavaScript expressions before deployment

Best Practices

1. Use Descriptive Variable Names

Good

export KEYCLOAK_ADMIN_USER=admin
export KEYCLOAK_ADMIN_PASSWORD=secure-password
export APPLICATION_REALM_NAME=production

Avoid

export USER=admin
export PASS=123
export NAME=prod

2. Provide Default Values

{
  "realm": "$(javascript: env.REALM_NAME || 'development')",
  "enabled": "$(javascript: env.ENABLED === 'true')"
}

3. Separate Configuration by Environment

REALM_NAME=dev-realm
KEYCLOAK_URL=http://localhost:8080

REALM_NAME=prod-realm
KEYCLOAK_URL=https://keycloak.company.com

Available Variable Substitution Features

keycloak-config-cli supports the following variable substitution types:

Environment & System Access

  • Environment Variables - $(env:VARIABLE_NAME) - Access environment variables
  • System Properties - $(sys:PROPERTY_NAME) - Access Java system properties
  • Spring Boot Properties - ${spring.property.name} - Access Spring Boot configuration

File Operations

  • File Content - $(file:ENCODING:PATH) - Read entire file contents
  • Properties File - $(properties:FILE_PATH::KEY) - Extract values from Java properties files
  • Resource Bundle - $(resourceBundle:BUNDLE_NAME::KEY) - Access resource bundle values
  • XML XPath - $(xml:FILE_PATH:EXPRESSION) - Query XML documents using XPath

Encoding & Decoding

  • Base64 Encoder - $(base64Encoder:STRING) - Encode string to Base64
  • Base64 Decoder - $(base64Decoder:STRING) - Decode Base64 string
  • URL Encoder - $(urlEncoder:STRING) - URL-encode special characters
  • URL Decoder - $(urlDecoder:STRING) - Decode URL-encoded strings

Network Operations

  • DNS Lookup - $(dns:TYPE|DOMAIN) - Resolve domain names to IP addresses
  • URL Content (HTTP) - $(url:ENCODING:URL) - Retrieve content from HTTP URLs
  • URL Content (HTTPS) - $(url:ENCODING:HTTPS_URL) - Retrieve content from HTTPS URLs
  • URL Content (File) - $(url:ENCODING:file:///PATH) - Read content via file:// URL scheme

Java Integration

  • Java Constants - $(const:CLASS_NAME.FIELD_NAME) - Access Java static final fields
  • Java Version - $(java:version) - Retrieve Java runtime version information

System Information

  • Date Formatting - $(date:FORMAT_PATTERN) - Format current date and time
  • Localhost - $(localhost:PROPERTY) - Retrieve localhost information (hostname, IP)

JavaScript Substitution

  • JavaScript - $(javascript:EXPRESSION) - Evaluate JavaScript expressions for complex transformations

Quick Reference

Feature Syntax Documentation
Environment Variable $(env:USERNAME) Environment Variables
System Property $(sys:user.dir) Environment Variables
File Content $(file:UTF-8:path/to/file.txt) File Operations
Properties File $(properties:config.properties::key) File Operations
Resource Bundle $(resourceBundle:org.example.messages::key) File Operations
XML XPath $(xml:config.xml:/root/@attribute) File Operations
Base64 Encoder $(base64Encoder:HelloWorld!) Encoding & Decoding
Base64 Decoder $(base64Decoder:SGVsbG9Xb3JsZCE=) Encoding & Decoding
URL Encoder $(urlEncoder:Hello World!) Encoding & Decoding
URL Decoder $(urlDecoder:Hello%20World%21) Encoding & Decoding
Java Constant $(const:java.lang.Math.PI) Java Integration
Java Version $(java:version) Java Integration
JavaScript $(javascript:expression) JavaScript Substitution

Next Steps