skip to content

What does WireMock's --admin-api-basic-auth protect on a shared CI instance, and what does it leave open?

level: seniorimportance: should knowfreq 46%

answer

  1. the control surface is open by default
  2. one flag, one server
  3. admin calls only, not stub traffic
  4. entry, not ownership
  5. every job holds the same credential

basics

~20 s

WireMock's --admin-api-basic-auth makes the whole /__admin surface demand credentials. Nothing on the network can then silently rewrite a shared instance's stubs. It partitions nothing, though: every job holding that one credential still shares a single mapping set.

solid answer

~50 s

On a shared instance WireMock's admin API under `/__admin` is a live, writable control surface reachable by anything that can reach the stub port, and by default it asks for nothing. `--admin-api-basic-auth` closes that: the instance then requires credentials on admin calls, so a stray script, a mis-pointed suite or a curious neighbour on the same network cannot quietly rewrite the bakery pre-order stubs everyone else is testing against. What it does **not** do is partition the instance. It is one credential for one server, every pipeline job that legitimately configures stubs has to hold it, and any holder can still change and break every other run's mappings. Authentication answers who may touch the control surface; it does not answer whose stubs these are, and on a shared instance the second question is the one that causes outages.

code

bash · 10 lines
bash
# The admin API of a long-lived shared instance, behind credentials
docker run -d --name bakery-preorder-stubs -p 8080:8080 \
  wiremock/wiremock \
  --admin-api-basic-auth ci-runner:rotate-me

# Admin calls carry the credential
curl -su ci-runner:rotate-me http://localhost:8080/__admin/health

# Stub traffic on the same port does not
curl -s http://localhost:8080/preorders/v1/orders/BP-4417

go deeper

for a junior

Be able to say that WireMock's admin API lives under /__admin, that it can change stubs while the server is running, and that --admin-api-basic-auth is what makes it ask for credentials.

for a middle

Explain the scope of the flag. It applies to admin calls and not to ordinary stub traffic on the same port, and it is chosen when the instance starts rather than per mapping.

for a senior

Show where authentication stops helping. Every job that configures stubs holds the same credential, so the shared mapping set is still one mutable thing any holder can break for everybody else.

for a principal

Own the policy: who may write to a shared instance at all, how the credential is rotated without stopping every pipeline, and whether a separate instance is cheaper than the governance it saves.

## The control surface a shared instance leaves open WireMock serves two different things on the same port: the stubs themselves, and an **admin API** under `/__admin` that can change the instance while it is running. That second surface is the reason a stub server is useful in a pipeline at all, because a run can configure the bakery pre-order behaviour it needs rather than shipping a frozen image. It is also, by default, unauthenticated. Anything that can reach the port can drive it. On an instance created for one run that is harmless, because the only thing that can reach it is the run. On a **shared CI instance**, one long-lived container serving every suite in the pipeline, the population that can reach the port is everybody on that network, and the admin API is a live, writable control plane sitting in the middle of them. ## What the flag does `--admin-api-basic-auth` is supplied when the instance starts and takes a user and a password. From that point the instance requires those credentials on calls to its admin API. Two consequences follow: - **Ordinary stub traffic is unaffected.** A client calling `GET /preorders/v1/orders/BP-4417` still receives its stubbed answer with no credentials at all. The flag scopes to the control surface, not to the thing being stubbed. - **The change is instance-wide and start-up-time.** There is no per-mapping or per-consumer variant. It is one credential for one server, chosen before the process starts. What that buys is real. The realistic threat on a shared instance is not an attacker; it is a mis-pointed suite, a leftover script, a developer's terminal still aimed at the shared address from last week, or a neighbouring team's automation that assumes it owns the server. Unauthenticated, every one of those silently rewrites the stubs everyone is testing against, and the resulting failures land on people who changed nothing. With a credential in place they fail immediately, loudly, and on the caller that made the mistake. ## What the flag does not do It does not partition the instance. This is the half that gets missed, and it is the half that causes outages. Every job that legitimately needs to configure stubs must hold the credential. Once it holds it, it has exactly the same authority as every other holder over exactly the same single mapping set. Authentication answers who may touch the control surface. It does not answer whose stubs these are, and on a shared instance that second question is the expensive one. | question | does `--admin-api-basic-auth` answer it? | |---|---| | can an unauthenticated caller change the stubs? | no, it stops that | | can a stray script on the network rewrite them? | no, it stops that | | can one job change another job's mappings? | yes, it still can | | does each pipeline get its own stub namespace? | no, there is one | | is ordinary stub traffic gated too? | no, only admin calls | ## Operating the credential 1. **Assume every consumer holds it.** Anything that configures stubs needs it, so the blast radius of any change to it is the whole population pointing at the instance. 2. **Plan rotation as a fleet change.** A new value means restarting the instance and updating every consumer. Do it when no pipeline is mid-run, and expect a missed consumer to fail at its first admin call rather than at start-up. 3. **Do not treat internal reachability as a substitute.** The set of things that can reach a CI-internal address is precisely the set of things that can accidentally rewrite your stubs. 4. **Record admin activity if the instance matters.** Knowing that mappings changed at a particular moment turns an unreproducible failure into a timeline somebody can read. ## Where authentication stops and hosting shape begins If the real requirement is that one run's stubs cannot be disturbed by another run, no credential delivers it, because the thing being shared is the mapping set rather than the door. The options at that point are structural: fewer consumers per instance, an instance per team or per pipeline, or an instance per run. Those are decisions about hosting shape and cost, and `--admin-api-basic-auth` is what you use before, during and after making them. It is a floor, not a solution. - **Use it on any instance more than one run can reach.** The cost is a flag and the saving is a class of unattributable failure. - **Never sell it as isolation.** A shared instance with a credential on its admin API is still a shared instance. - **Say out loud what it protects**: the instance from accidents, not runs from each other. - **Pair it with a named owner.** A control surface that everyone can drive and nobody owns degrades regardless of whether it asks for a password.

  • The admin credential has to change. How do you rotate it on a shared instance?
    Treat it as a fleet change rather than a flag edit. Every job that configures stubs holds it, so rotation means restarting the instance with the new value and updating all of them. Plan the window, do it when no pipeline is mid-run, and expect any consumer you missed to fail at its first admin call.
  • If the instance is only reachable inside CI, is authentication still worth it?
    Yes, because reachability inside CI describes exactly the population you should worry about. The realistic threat is not an outsider but a mis-pointed suite or a stray script from a neighbouring team writing to the wrong address, and a credential turns that from a silent stub rewrite into an immediate, attributable failure.

It is the lock on the bakery's back door, not a separate counter for each shift. Everyone who works there carries the same key, and once inside they are all writing on the same order board.

saying these in an interview costs you the question

  • Believes --admin-api-basic-auth gives each pipeline its own private stub namespace.
  • Thinks the flag also requires credentials on ordinary stub traffic.
  • Treats authentication on a shared instance as isolation between runs.
  • Assumes an internal CI network makes an unauthenticated admin API safe.
  • Plans to rotate the credential without noticing every job already holds it.