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.

Sorting values into configuration and code.
ValueConfiguration?Where it belongs
spring.datasource.urlYes, differs per environmentEnvironment variable or profile file
spring.datasource.passwordYes, and a secretSecret store, injected at run time
shop.sms.api-keyYes, and a secretSecret store, injected at run time
logging.level.org.secondgearYesProfile file, overridable by environment
Slots every 30 minutes, 9:00 to 15:00No, a business ruleThe code, with tests
The server portYes, set by the platformEnvironment 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.

Java Example
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]));
    }
}
Output
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.

booking-api/deploy/env.example
# 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:+UseG1GC

What 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.

Java Example
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");
        }
    }
}
Output
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.

Java Example
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);
    }
}
Output
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.

Java Example
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)));
    }
}
Output
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.

Java Example
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");
    }
}
Output
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.

The secret-scan job
  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.

Places to keep secrets, from worst to most capable.
Where a secret livesGood forWatch out for
Repository file (application.yml)NothingEvery clone, fork and backup keeps it forever
Environment variable on the serverSimple servicesInherited by child processes; shown by inspect commands
File in /run/secretsContainersFile permissions; mount only into the service that needs it
GitHub environment secretPipeline stepsLeaks in transformed form; restrict with required reviewers
Secret manager (Vault, cloud secret stores)Many services, automatic rotationAnother 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.

Least-privilege role for the booking API (PostgreSQL)
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.

  1. Is the half-hour slot rule configuration?

    Show answer

    No; it is a business rule and belongs in the tested code.

  2. 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.

  3. Why is deleting a committed password not enough?

    Show answer

    Clones, forks and backups keep the history; the password must be rotated.

  4. 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.

  5. 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.

Take the quiz