JAVA-280 · Lesson 5 of 12 · 25 min
Configuration and secrets
▶ Video coming soon A video version of this lesson is on the way.
On Thursday, February 17, the mood in the back room was quieter than usual. The evening before, in Ingrid's Wednesday session, Leif had found the database password for StockStore in Hamza's application.yml, pushed to the secondgear repository the week before. He had rotated it that night. "Ingrid showed you how Spring reads configuration," he said. "Tonight is the other half: where the values live on the way to production, who can see them, and how the pipeline stops this from happening again."
Configuration is everything that varies
The twelve-factor definition is useful: configuration is everything that is likely to vary between deployments, and nothing else. The database address, its user and password, the text-message provider's key, the log level and the number of connections in the pool are configuration. The rule that slots start every half hour from 9:00 to 15:00 is not; it is business logic and belongs in the code, where it is tested. A good test for the boundary is whether the code could be made public tomorrow without leaking anything. If it could not, something in it is configuration.
| Value | Configuration? | Where it belongs |
|---|---|---|
| spring.datasource.url | Yes, differs per environment | Environment variable or profile file |
| spring.datasource.password | Yes, and a secret | Secret store, injected at run time |
| shop.sms.api-key | Yes, and a secret | Secret store, injected at run time |
| logging.level.org.secondgear | Yes | Profile file, overridable by environment |
| Slots every 30 minutes, 9:00 to 15:00 | No, a business rule | The code, with tests |
| The server port | Yes, set by the platform | Environment variable |
Layers of configuration
Spring Boot reads properties from many property sources and lets later, more specific sources override earlier ones: defaults in application.yml inside the JAR, then profile files such as application-prod.yml, then operating system environment variables, then command-line arguments. JAVA-260 covered the full list. For deployment the consequence is simple: the JAR carries safe defaults and no secrets, and each environment adds its own values from outside. The example resolves a few keys through such layers and reports where each final value came from, which is what Spring Boot's Actuator env endpoint shows.
import java.util.*;
public class Main {
record Source(String name, Map<String, String> values) {}
public static void main(String[] args) {
List<Source> sources = List.of(
new Source("application.yml (in jar)", Map.of(
"server.port", "8080", "spring.datasource.url", "jdbc:postgresql://localhost:5432/stockstore",
"logging.level.org.secondgear", "INFO", "shop.booking.max-active-per-phone", "2")),
new Source("application-prod.yml (in jar)", Map.of(
"spring.datasource.url", "jdbc:postgresql://db:5432/stockstore", "logging.level.org.secondgear", "WARN")),
new Source("environment", Map.of(
"spring.datasource.password", "(from secret)", "logging.level.org.secondgear", "INFO")),
new Source("command line", Map.of("server.port", "8081")));
Map<String, String[]> resolved = new TreeMap<>();
for (Source s : sources)
s.values().forEach((k, v) -> resolved.put(k, new String[] {v, s.name()}));
resolved.forEach((k, v) -> System.out.printf("%-34s = %-45s <- %s%n", k, v[0], v[1]));
}
}logging.level.org.secondgear = INFO <- environment server.port = 8081 <- command line shop.booking.max-active-per-phone = 2 <- application.yml (in jar) spring.datasource.password = (from secret) <- environment spring.datasource.url = jdbc:postgresql://db:5432/stockstore <- application-prod.yml (in jar)
What this code does
Sources are applied from the least specific to the most specific, and each put replaces the value from an earlier source, so the last source to mention a key wins. The production profile sets the log level to WARN, but an environment variable puts it back to INFO, which is how Leif turns on more logging for one deployment without building a new JAR. The password appears only in the environment, never in a file inside the JAR.
Leif's rule for the booking API was to keep the outside layer small and explicit: a short list of environment variables, written down in the repository with no values, so that anyone deploying it knows exactly what it needs.
# Configuration the booking API reads from its environment in production.
# Values are set on the server by Leif; never commit real values.
SPRING_PROFILES_ACTIVE=prod
SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/stockstore
SPRING_DATASOURCE_USERNAME=booking_api
SPRING_DATASOURCE_PASSWORD= # secret: from /run/secrets in lesson 6
SHOP_SMS_API_KEY= # secret
MANAGEMENT_SERVER_PORT=9090
JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=75 -XX:+UseG1GCWhat this code does
The file lists every variable the service reads, with blanks for secrets, and is committed as documentation. The names follow Spring Boot's relaxed binding for environment variables: dots become underscores and the letters are upper case. The database user is booking_api, not the owner of the schema, so a leaked password could not drop tables.
Failing fast on missing configuration
A service that starts with a missing setting and fails on the first customer's request is worse than one that refuses to start. Spring Boot's validated @ConfigurationProperties records, from JAVA-260, do this for the shop's own settings, and a missing datasource URL stops the application context. The same idea in plain Java is a check at start-up that lists everything missing at once, so the person deploying fixes it in one go.
import java.util.*;
public class Main {
static final List<String> REQUIRED = List.of(
"SPRING_DATASOURCE_URL", "SPRING_DATASOURCE_USERNAME", "SPRING_DATASOURCE_PASSWORD", "SHOP_SMS_API_KEY");
static List<String> missing(Map<String, String> env) {
return REQUIRED.stream().filter(k -> env.getOrDefault(k, "").isBlank()).toList();
}
public static void main(String[] args) {
Map<String, String> staging = Map.of(
"SPRING_DATASOURCE_URL", "jdbc:postgresql://db:5432/stockstore",
"SPRING_DATASOURCE_USERNAME", "booking_api",
"SPRING_DATASOURCE_PASSWORD", " ");
List<String> m = missing(staging);
if (!m.isEmpty()) {
System.out.println("refusing to start; missing configuration:");
m.forEach(k -> System.out.println(" " + k));
} else {
System.out.println("configuration complete");
}
}
}refusing to start; missing configuration: SPRING_DATASOURCE_PASSWORD SHOP_SMS_API_KEY
What this code does
missing treats an absent variable and one that is only spaces in the same way, because an empty password is as useless as none. The check collects every missing name before reporting, rather than stopping at the first. In a real service the map would be System.getenv(), and the program would exit with a non-zero status so that the platform reports a failed start.
Secrets are different
A secret is configuration that grants access: passwords, API keys, private keys, tokens. Secrets need more care than other settings because a leaked one gives an attacker what the secret protects, and because they can leak through places that ordinary settings never matter in: the Git history, a container image's layers, a CI log, an error message, a heap dump, or the output of the env command on a shared server.
Environment variables are the twelve-factor answer, and they are much better than files in Git, but they have weaknesses. Any process started by the service inherits them, they show up in docker inspect and in crash reports, and a careless log line that prints the environment prints the secret. A step better is to deliver each secret as a file that only the service's user can read, which is how Docker and Kubernetes secrets work: the platform mounts a small in-memory file system at a path such as /run/secrets, with one file per secret.
Spring Boot reads such a folder directly with a configuration tree: the setting spring.config.import=optional:configtree:/run/secrets/ turns every file in the folder into a property whose name is the file name and whose value is the file's content. A file called spring.datasource.password becomes that property, with no environment variable in between. The example builds a small configuration tree in a temporary folder and reads it the same way.
import java.io.IOException;
import java.nio.file.*;
import java.util.*;
public class Main {
static Map<String, String> readTree(Path dir) throws IOException {
Map<String, String> props = new TreeMap<>();
try (var files = Files.list(dir)) {
for (Path f : files.toList()) {
props.put(f.getFileName().toString(), Files.readString(f).strip());
}
}
return props;
}
public static void main(String[] args) throws IOException {
Path secrets = Files.createTempDirectory("secrets");
Files.writeString(secrets.resolve("spring.datasource.password"), "k7-Rv2q-Lm9x-Tq4w\n");
Files.writeString(secrets.resolve("shop.sms.api-key"), "sms_live_51Hx2f9Q0aZk\n");
Map<String, String> props = readTree(secrets);
props.forEach((k, v) -> System.out.println(k + " = " + "*".repeat(4) + v.substring(v.length() - 2)
+ " (" + v.length() + " characters)"));
for (Path f : Files.list(secrets).toList()) Files.delete(f);
Files.delete(secrets);
}
}shop.sms.api-key = ****Zk (21 characters) spring.datasource.password = ****4w (17 characters)
What this code does
Each file name becomes a property name and the stripped content becomes its value, so the trailing newline that most editors add does not end up in the password. The program never prints a whole secret: it shows four stars, the last two characters and the length, enough to tell two values apart while debugging. The secrets here are invented, and the folder is deleted at the end.
Never print a secret
Logs are copied, shipped and kept, so a secret in a log line is a leak with a long life. Spring Boot's Actuator already masks values whose keys look secret, such as password, secret, key, token and credentials, when it shows the environment or configuration properties, and it shows nothing unless the endpoint is explicitly allowed to. Hamza's own code needed the same habit whenever it printed configuration, for example in a start-up summary.
import java.util.*;
import java.util.regex.Pattern;
public class Main {
static final Pattern SECRET_KEY = Pattern.compile("(?i).*(password|secret|key|token|credentials).*");
static String show(String key, String value) {
return SECRET_KEY.matcher(key).matches() ? "******" : value;
}
public static void main(String[] args) {
Map<String, String> cfg = new TreeMap<>(Map.of(
"spring.datasource.url", "jdbc:postgresql://db:5432/stockstore",
"spring.datasource.username", "booking_api",
"spring.datasource.password", "k7-Rv2q-Lm9x-Tq4w",
"shop.sms.api-key", "sms_live_51Hx2f9Q0aZk",
"shop.sms.sender", "SecondGear",
"management.server.port", "9090"));
System.out.println("booking API starting with:");
cfg.forEach((k, v) -> System.out.println(" " + k + " = " + show(k, v)));
}
}booking API starting with: management.server.port = 9090 shop.sms.api-key = ****** shop.sms.sender = SecondGear spring.datasource.password = ****** spring.datasource.url = jdbc:postgresql://db:5432/stockstore spring.datasource.username = booking_api
What this code does
The pattern looks at the key, not the value, and matches any key containing one of the secret words in any case. That is the same rule Actuator uses to sanitize values, and it errs on the safe side: a harmless key containing the word key would be masked too. The start-up summary is still useful, because it shows which database and user the service is about to use.
Finding secrets before they land
The leak on February 16 was found by a person reading a diff. Leif wanted a machine to find the next one, in the pull request, before review. Secret scanners such as gitleaks or GitHub's own secret scanning look for strings shaped like credentials: known prefixes of provider keys, private key headers, and assignments of long random-looking values to names like password. A scanner cannot know every format, so it is a net, not a guarantee, and it is combined with .gitignore entries for local files.
import java.util.*;
import java.util.regex.*;
public class Main {
record Rule(String name, Pattern pattern) {}
static final List<Rule> RULES = List.of(
new Rule("private key", Pattern.compile("-----BEGIN [A-Z ]*PRIVATE KEY-----")),
new Rule("sms provider key", Pattern.compile("sms_live_[A-Za-z0-9]{12,}")),
new Rule("password assignment", Pattern.compile("(?i)password\\s*[:=]\\s*[\"']?(?!\\$\\{)[^\\s\"']{8,}")));
public static void main(String[] args) {
List<String> diff = List.of(
"+spring:",
"+ datasource:",
"+ url: jdbc:postgresql://localhost:5432/stockstore",
"+ password: Spokes418!winter",
"+ other-password: ${STOCKSTORE_DB_PASSWORD}",
"+shop.sms.api-key=sms_live_51Hx2f9Q0aZk",
"+// password: see the runbook");
int found = 0;
for (int i = 0; i < diff.size(); i++) {
for (Rule r : RULES) {
if (r.pattern().matcher(diff.get(i)).find()) {
System.out.println("line " + (i + 1) + ": possible " + r.name());
found++;
}
}
}
System.out.println(found == 0 ? "no secrets found" : found + " finding(s); the check fails");
}
}line 4: possible password assignment line 6: possible sms provider key 2 finding(s); the check fails
What this code does
Each rule is a regular expression, and every added line of the diff is tested against every rule. The password rule skips values that start with a dollar sign and a brace, because a placeholder that refers to an environment variable is exactly what the file should contain, and it ignores short words like the one in the comment. The scanner flags the real password on line 4 and the provider key on line 6, and a non-zero count fails the pipeline job.
In the pipeline the scan became its own job, which Hamza finished during the week off. It uses gitleaks's published action, runs on every pull request and is one of the required checks on main.
secret-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}What this code does
fetch-depth: 0 checks out the whole history instead of only the last commit, so the scan sees every commit in the pull request. The action fails the job when it finds a likely secret, which blocks the merge through branch protection. The only secret it uses is the job's own token, which it needs to comment on the pull request.
Secrets in the pipeline
The pipeline itself needs some secrets, such as the key it will use in lesson 6 to deploy to the server. GitHub stores encrypted secrets at the repository or organization level and, better, per environment: a named target such as staging or production with its own secrets and its own protection rules, such as a required reviewer before a job may use it. A secret is passed to a step as an environment variable and GitHub masks its value if it appears in the log, but a step can still leak it in a transformed form, for instance encoded in Base64, so the habit of never printing secrets applies here too.
| Where a secret lives | Good for | Watch out for |
|---|---|---|
| Repository file (application.yml) | Nothing | Every clone, fork and backup keeps it forever |
| Environment variable on the server | Simple services | Inherited by child processes; shown by inspect commands |
| File in /run/secrets | Containers | File permissions; mount only into the service that needs it |
| GitHub environment secret | Pipeline steps | Leaks in transformed form; restrict with required reviewers |
| Secret manager (Vault, cloud secret stores) | Many services, automatic rotation | Another system to run, or another bill |
Rotation and least privilege
Any secret that might have been seen must be rotated: a new value issued, the service switched to it, and the old value revoked. Leif's rotation on February 16 took twenty minutes because he had to find every place the old password was used. The lessons he drew were to give each service its own database user, so that changing one password affects one service, and to give that user only the privileges it needs. The booking API's user can read and write the booking tables and read the parts table; it cannot change the schema, which Flyway does with a separate migration user at deployment.
CREATE ROLE booking_api LOGIN PASSWORD 'set-by-leif';
GRANT CONNECT ON DATABASE stockstore TO booking_api;
GRANT USAGE ON SCHEMA public TO booking_api;
GRANT SELECT ON parts TO booking_api;
GRANT SELECT, INSERT, UPDATE ON repair_bookings TO booking_api;
GRANT USAGE ON SEQUENCE repair_bookings_id_seq TO booking_api;What this code does
The role can log in and use the schema but owns nothing in it. It can read parts, to answer availability questions, and read, add and change bookings, but it cannot delete rows or alter tables. The password in the listing is a placeholder; Leif sets the real one in the database and in the secret file, nowhere else.
Exercises
Try it yourself
Mask a secret
Complete mask so that it returns a value safe to print: values of 8 characters or more show four stars followed by their last 4 characters; shorter values are shown as four stars only, because their last characters would give too much away; an empty value is shown as (empty).
public class Main {
static String mask(String value) {
return value;
}
public static void main(String[] args) {
System.out.println(mask("k7-Rv2q-Lm9x-Tq4w"));
System.out.println(mask("sms_live_51Hx2f9Q0aZk"));
System.out.println(mask("hunter2"));
System.out.println(mask(""));
}
}Try it yourself
Which value wins?
Property sources are listed from least to most specific. Complete resolve so that it returns the value of key from the most specific source that has it, followed by from and that source's name, or not set if none has it.
import java.util.*;
public class Main {
record Source(String name, Map<String, String> values) {}
static String resolve(List<Source> sources, String key) {
return sources.get(0).values().getOrDefault(key, "not set");
}
public static void main(String[] args) {
List<Source> s = List.of(
new Source("jar defaults", Map.of("pool.size", "5", "log.level", "INFO")),
new Source("prod profile", Map.of("pool.size", "10", "log.level", "WARN")),
new Source("environment", Map.of("log.level", "DEBUG")));
for (String k : List.of("pool.size", "log.level", "sms.sender"))
System.out.println(k + ": " + resolve(s, k));
}
}Before reading week began, Hamza deleted the password line from application.yml for good, added .env and application-local.yml to .gitignore, and wrote env.example. Leif created the booking_api role. Nobody could remove the old password from the history, but it no longer opened anything.
Common mistakes
MistakeCommitting a password and then deleting it in a later commit.
InsteadTreat it as leaked: rotate it, then make sure the new one never enters the repository.
MistakePrinting the whole environment or configuration at start-up.
InsteadPrint the keys that matter and mask any value whose key looks secret.
MistakeSharing one database user between several services.
InsteadGive each service its own user with only the privileges it needs.
MistakePutting secrets in Dockerfile ENV lines or build arguments.
InsteadInject them when the container starts, ideally as files under /run/secrets.
MistakeRelying on reviewers to spot secrets in diffs.
InsteadRun a secret scanner as a required check on every pull request.
Summary and key terms
- Configuration is everything that varies between deployments, and business rules stay in the code.
- Spring Boot layers property sources so that the JAR carries defaults and each environment overrides them from outside, and a service should refuse to start when required settings are missing, listing them all.
- Secrets need extra care because they leak through history, images, logs and error messages.
- Environment variables are acceptable, files mounted under /run/secrets and read through a configuration tree are better, and secret managers add rotation.
- Values whose keys look secret are always masked, secret scanners such as gitleaks run on every pull request, GitHub environment secrets serve the pipeline, and a leaked secret is rotated.
- Each service gets its own least-privilege database user.
- Configuration
- Values that vary between deployments, kept outside the code.
- Property source
- One place Spring Boot reads properties from, such as a file or the environment.
- Secret
- Configuration that grants access, such as a password or API key.
- Configuration tree
- A folder of files read as properties, one file per property, as in /run/secrets.
- Fail fast
- Refusing to start when configuration is missing or invalid.
- Masking
- Showing a value only partly, or not at all, when it is printed.
- Secret scanner
- A tool that searches code and history for strings shaped like credentials.
- Rotation
- Replacing a secret with a new value and revoking the old one.
- Least privilege
- Giving each user or service only the permissions it needs.
- Environment secret
- A GitHub secret tied to a deployment environment with its own protection rules.
Practice problems
Work each problem on paper first, then reveal the answer to check.
Is the half-hour slot rule configuration?
Show answer
No; it is a business rule and belongs in the tested code.
What does spring.config.import=optional:configtree:/run/secrets/ do?
Show answer
It turns each file in that folder into a property named after the file.
Why is deleting a committed password not enough?
Show answer
Clones, forks and backups keep the history; the password must be rotated.
Why does the booking API have its own database user?
Show answer
So that a leak or rotation affects only that service and its privileges stay small.
Why does the scanner skip a placeholder that names an environment variable?
Show answer
A placeholder is not a secret; referring to the environment is what the file should contain.
Lesson quiz · 5 questions
Score 60% or more to complete this lesson.
Create a free account to save your progress, take quizzes and earn a certificate.