This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Getting started
Clone it with --recursive
git clone --recursive https://github.com/rcbj/iya-sts.git
The LDAP directory is built on rcbj/node-ldapjs,
which is a git submodule pinned as "ldapjs": "file:node-ldapjs" in
package.json. Without --recursive the directory exists but is empty, npm
install installs a package with no main, and the failure arrives at startup as
Cannot find module 'ldapjs' — a message that names a package rather than a
submodule.
If you have already cloned:
git submodule update --init --recursive
--recursive rather than --init alone matters if you reached this repository
through the OAuth2/OIDC Debugger, where it is itself a
submodule: a plain --init there stops one level short of this one.
On Windows, under Cygwin
The scripts you run from a checkout work in a Cygwin
shell on Windows the same way they work on Linux. That covers
./run-tests.sh, ./run-coverage.sh, ./run-jsdoc.sh,
./docker-npm-test.sh, ./clean.sh, the deploy/*/terraform-local.sh and
deploy/*/bootstrap-state.sh launchers, and the scripts in utilities/.
Everything they build and run is still a Linux container. What you need:
- Docker Desktop, running, with
docker.exeon your WindowsPATH. A Cygwin shell inherits thatPATH. - Cygwin’s own
bash,git,coreutils,sed,curlandjqpackages. Install the Windows versions of node, the AWS CLI, gcloud and az, the ones each project ships for Windows. The scripts convert paths for them and remove the CRLF line endings they print. - A checkout with LF line endings. The repository’s
.gitattributesturns line-ending conversion off, so a clone made with Git for Windows (whose default iscore.autocrlf=true) still has the LF endings the scripts and images need. A checkout made before that file existed may have CRLF endings. Commit or stash your work, then refresh the checkout withgit rm -r --cached -q . && git reset --hard.
Three things behave differently on Windows:
- AWS sessions are passed as a snapshot. On Linux,
deploy/aws/terraform-local.shserves youraws loginor SSO session to the container as it refreshes. Docker Desktop’s containers cannot reach that endpoint, so on Windows the container gets the session as it stands when the run starts. An apply can outlive that session. For a long one, export the deployer user’s key asAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY. - The Azure CLI’s token cache must be plain JSON. On Windows the Azure
CLI encrypts its token cache for your account by default, and the
container cannot read it.
deploy/azure/terraform-local.shstops and tells you to runaz config set core.encrypt_token_cache=false && az login. - No
sudo, and no file ownership to fix. If Docker Desktop is not running, a script says so instead of tryingsudo. Files a container writes into your checkout are owned by you, so the--userand chown-back steps that Linux needs are skipped.
Git Bash (MSYS) is detected and handled the same way, but Cygwin is the supported shell.
Run it
docker-compose up
or
docker compose up
or
docker build -t iya-sts .
docker run --rm -p 8081:8081 -e CONFIG_FILE=./env/local.js iya-sts
From an image, not from a checkout. Part of the service
is written in TypeScript and is compiled only while the image is built, so
node server.js on a checkout stops and says so. Every setting below that is
shown as an environment variable is passed with -e.
CONFIG_FILE selects a file in env/ — local.js, test.js or
docker-tests.js. At the default debug level every endpoint call and every
artifact before and after signing is logged. That is the point of development mode, so
resist quietening it; env/test.js is the quiet one if you need it — and it is
what the three test launchers select for themselves, since a suite that passes
throws its log away and the level is about half of this service’s CPU. Ask any
of them for --sts-log-level=debug (or STS_LOG_LEVEL=debug) and the whole
record comes back, appconfig file and all.
The path is relative to the repository root, wherever you run node from and
whichever module reads it. That has been true since the modules moved into
subdirectories, and it is common/config_file.js that keeps it true.
The ports
Only the first is HTTP. The rest are separate listeners, and several of them will not bind on an ordinary user account.
| Port | What | Setting | Environment |
|---|---|---|---|
| 8081 | The main service — every protocol endpoint, the console, the API. HTTPS, since every appconfig file here sets global.https; STS_HTTPS=false makes it plain HTTP. It asks every connection for a client certificate and requires none, so it is also where mutual TLS happens |
global.port |
STS_PORT |
| 88 (TCP+UDP) | The Kerberos KDC | krb5.kdcPort |
KRB5_KDC_PORT |
| 389 | The LDAP directory | ldap.port |
LDAP_PORT |
| 636 | The same directory over TLS (LDAPS) | ldap.tlsPort |
LDAPS_PORT |
| 8092 | The SPIFFE Workload API over gRPC (product mode: only where spiffe.workloadTcpSourceAuthenticated is on) |
spiffe.workloadPort |
STS_SPIFFE_WORKLOAD_PORT |
| 8181 | The SPIRE Server API over gRPC | spiffe.serverPort |
STS_SPIFFE_SERVER_PORT |
| — | The Workload API’s Unix socket, at /tmp/spire-agent/public/api.sock |
spiffe.workloadSocket |
STS_SPIFFE_WORKLOAD_SOCKET |
A port that will not bind does not stop the service. 88, 389 and 636 all need
root, and a host run is usually not root. The failure is RECORDED rather than
thrown — a require that throws would take the whole service down where a route
cannot — and each listener publishes its own result, because “389 is up and 636
is not” is the ordinary outcome and one flag could only report one of them:
GET /admin/ldap/service—listening/listenError, and atlsobject with its own pair (an admin console page, so it needs a session;GET /admin-api/ldap/serviceis the same object and is not gated)GET /spiffe— all four SPIFFE sockets, separately- the KDC — its startup log line (
krb5: the KDC is reachable on TCP and UDP …, orSTS-CORE-0029naming why it could not bind)
So a page answering 200 is not evidence that the listener behind it came up. Read the flag.
Two TLS ports have left this table. 8443 (tls.port) asked for a
client certificate and never required one; 9443 (tls.mutualPort) required one
at the handshake. Both listeners and both settings were deleted, and neither
setting has a replacement — a deployment that still sets one gets an “unknown
setting” warning at startup. The main port already asked for a client
certificate and required none, so that half moved nowhere; GET /tls/sign-in
signs the holder of a verified one in. Nothing requires a certificate at the
handshake any more, deliberately: the port that would have to do it carries
every other protocol, so a certificate that does not verify is refused where it
is USED — at the token endpoint under RFC 8705, at /xacml, at /scim/v2 and
at /tls/sign-in.
Running two copies
Everything is in memory and nothing is shared, so a second instance is just a second process — but every default port collides. Give the second one its own:
docker run --rm -p 8091:8091 \
-e CONFIG_FILE=./env/local.js \
-e STS_PORT=8091 -e LDAP_PORT=3891 -e LDAPS_PORT=6391 \
-e KRB5_KDC_PORT=8891 \
-e STS_SPIFFE_WORKLOAD_PORT=8093 -e STS_SPIFFE_SERVER_PORT=8182 \
-e STS_SPIFFE_WORKLOAD_SOCKET=/tmp/spire-agent-2/public/api.sock \
iya-sts
In separate containers the default ports no longer collide inside them; the
different values matter for what you publish with -p.
The SPIFFE Unix socket is the one thing this service puts on a filesystem, and two instances sharing a path is the one collision that is not a bind error: the second unlinks the first’s socket as “stale” and takes it over. It says so in the log when it does.
In a container
docker build -t iya-sts .
docker run --rm -p 8081:8081 iya-sts
The image copies the whole build context (.dockerignore decides what is in it)
so that adding a protocol directory cannot be forgotten, installs with
--omit=dev, and defaults CONFIG_FILE to ./env/local.js. EXPOSE documents
every port above; publishing them is the caller’s decision.
The service runs as sts, uid and gid 10001, not as root. It still binds
88, 389 and 636 inside the container, because Docker sets
net.ipv4.ip_unprivileged_port_start=0 in every container’s network
namespace; a runtime that does not set it needs
--sysctl net.ipv4.ip_unprivileged_port_start=0. The one directory the
service writes under its tree, /usr/src/sts/data, belongs to that user, so
a volume mounted there must be writable by uid 10001. A file you mount for
the service to read, such as a key-encryption key file, must be readable by
uid 10001.
The image’s JavaScript carries no comments. The build takes them out of
every .js it ships, compiled from TypeScript or not, because Node keeps the
source text of every module in memory for as long as the process runs, and
this repository’s comments were about 80 MB of every process’s heap. Nothing
else is changed: no name is shortened and no module is bundled. Every line
break is kept, so a line number in a stack trace from the image is the line
number in the repository — read the comments there. A column number can
differ on a line that had a comment in the middle of it. The copyright and
licence headers go with the other comments; LICENSES/ and REUSE.toml are
still in the image. The build also writes characters such as — in string
literals as \u2014 escapes, which gives the same strings and halves the
memory Node needs for each file’s source; a line in the image can therefore
read differently from the repository while meaning the same.
The Workload API’s Unix socket is inside the container. To reach it from the host
or another container, mount its directory as a volume — publishing 8092 is the
alternative on a network that authenticates source addresses, and needs the
client pointed at tcp://host:8092 explicitly. An AWS product cluster does not
publish 8092. A workload there runs spiffe/workload_agent.js beside it and
points SPIFFE_ENDPOINT_SOCKET at that agent’s Unix socket
(SPIFFE).
With PostgreSQL and OpenBao, from published images
docker compose up in a checkout builds the image and starts the service the
way a deployment runs it: product mode, its store in PostgreSQL, and
its key-encryption key and database password in an OpenBao secret store.
The compose stack describes that file: its services,
ports, volumes and variables. The same stack can be run from published images
alone, with no checkout and nothing built:
| Image | From |
|---|---|
iyasec/iya-sts |
Docker Hub; the same image is ghcr.io/rcbj/iya-sts |
postgres:18 |
Docker Hub (official) |
openbao/openbao |
Docker Hub |
The database’s TLS and schema scripts and OpenBao’s configuration and seeder
are in the iya-sts image, so two one-shot containers of that image copy them
into volumes before anything else starts.
Put this in a directory of its own as docker-compose.yml:
name: iya-sts
services:
postgres-init:
image: iyasec/iya-sts:${IYA_STS_TAG:-latest}
restart: "no"
user: "0"
volumes:
- db-initdb:/out/initdb
- db-share:/out/share
command:
- sh
- -c
- |
cp postgres/require-tls.sh /out/initdb/00-require-tls.sh
cp postgres/apply-schema.sh /out/initdb/10-apply-schema.sh
cp postgres/generate-tls.sh postgres/schema.sql /out/share/
chmod 755 /out/initdb/*.sh /out/share/generate-tls.sh
chmod 644 /out/share/schema.sql
postgres:
image: postgres:18
depends_on:
postgres-init:
condition: service_completed_successfully
environment:
POSTGRES_USER: sts
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_DB: sts
STS_DB_APP_USER: sts_app
STS_DB_APP_PASSWORD: ${STS_DB_APP_PASSWORD:?set STS_DB_APP_PASSWORD in .env}
POSTGRES_TLS_PUBLIC_DIR: /run/sts-db-ca
volumes:
- db-data:/var/lib/postgresql
- db-ca:/run/sts-db-ca
- db-initdb:/docker-entrypoint-initdb.d:ro
- db-share:/usr/local/share/sts:ro
command:
- bash
- -c
- >-
/usr/local/share/sts/generate-tls.sh &&
exec docker-entrypoint.sh postgres
-c max_connections=200
-c shared_buffers=${STS_POSTGRES_SHARED_BUFFERS:-2GB}
-c max_wal_size=8GB
-c checkpoint_timeout=15min
-c wal_compression=lz4
-c max_parallel_workers_per_gather=0
-c track_io_timing=on
-c shared_preload_libraries=pg_stat_statements,auto_explain
-c pg_stat_statements.track=all
-c pg_stat_statements.max=10000
-c auto_explain.log_min_duration=200ms
-c auto_explain.log_analyze=on
-c auto_explain.log_timing=off
-c auto_explain.log_buffers=on
-c auto_explain.log_nested_statements=on
-c log_lock_waits=on
-c ssl=on
-c ssl_cert_file=/var/lib/postgresql/tls/server.crt
-c ssl_key_file=/var/lib/postgresql/tls/server.key
healthcheck:
test: ["CMD-SHELL", "pg_isready -U sts -d sts"]
interval: 5s
timeout: 5s
retries: 10
openbao-tls:
image: iyasec/iya-sts:${IYA_STS_TAG:-latest}
restart: "no"
user: "0"
environment:
STS_BAO_TLS_DIR: /openbao/file/tls
STS_BAO_TLS_NAMES: openbao,localhost
STS_BAO_TLS_IPS: 127.0.0.1
volumes:
- bao-file:/openbao/file
command:
- sh
- -c
- |
node openbao/generate-tls.js
mkdir -p /openbao/file/config
cp openbao/bao.hcl /openbao/file/config/bao.hcl
chown -R 100:1000 /openbao/file
openbao:
image: openbao/openbao:latest
hostname: openbao
depends_on:
openbao-tls:
condition: service_completed_successfully
cap_add:
- IPC_LOCK
environment:
BAO_STATIC_SEAL_CURRENT_KEY_ID: sts
BAO_STATIC_SEAL_CURRENT_KEY: ${STS_BAO_SEAL_KEY:?set STS_BAO_SEAL_KEY in .env}
volumes:
- bao-file:/openbao/file
command: ["server", "-config=/openbao/file/config/bao.hcl"]
openbao-seed:
image: iyasec/iya-sts:${IYA_STS_TAG:-latest}
restart: "no"
user: "0"
depends_on:
openbao:
condition: service_started
environment:
STS_BAO_ADDR: https://openbao:8200
STS_BAO_CA_FILE: /openbao/file/tls/server.crt
STS_BAO_POLICY_FILE: /usr/src/sts/openbao/read-only.hcl
STS_BAO_CLIENT_CN: sts
STS_DB_APP_PASSWORD: ${STS_DB_APP_PASSWORD:?set STS_DB_APP_PASSWORD in .env}
STS_ADMIN_API_CLIENT_SECRET: ${ADMIN_API_CLIENT_SECRET:-}
STS_BAO_STARTUP_NODES: sts
STS_BAO_STARTUP_DIR: /openbao/startup
STS_BAO_PRINT_CREDENTIALS: "true"
volumes:
- bao-file:/openbao/file
- bao-client:/openbao/client
- bao-startup:/openbao/startup
command: ["node", "openbao/seed.js"]
sts:
image: iyasec/iya-sts:${IYA_STS_TAG:-latest}
hostname: sts
user: "0"
sysctls:
- net.ipv4.ip_unprivileged_port_start=0
depends_on:
postgres:
condition: service_healthy
openbao-seed:
condition: service_completed_successfully
ports:
- "${STS_PORT:-8081}:8081"
- "${PKI_PORT:-8082}:8082"
- "${KDC_PORT:-88}:88"
- "${KDC_PORT:-88}:88/udp"
environment:
STS_MODE: product
KRB5_SERVICE_PRINCIPAL: ${KRB5_SERVICE_PRINCIPAL:-HTTP/localhost}
STS_PERSISTENCE_MODE: postgres
STS_DATABASE_URL: postgres://sts_app@postgres:5432/sts?sslmode=verify-full
STS_DATABASE_TLS_CA_FILE: /run/secrets/database-ca/postgres.crt
STS_DATABASE_PASSWORD_PROVIDER: vault
STS_DATABASE_PASSWORD_REF: secret/data/sts
STS_DATABASE_PASSWORD_FIELD: databasePassword
STS_KEYS_KEK_PROVIDER: vault-transit
STS_KEYS_KEK_VAULT: https://openbao:8200
STS_KEYS_KEK_REF: sts-kek
STS_KEYS_VAULT_CLIENT_CERT: /run/secrets/openbao/client.crt
STS_KEYS_VAULT_CLIENT_KEY: /run/secrets/openbao/client.key
STS_KEYS_VAULT_CA_CERT: /run/secrets/openbao/bao-ca.crt
PKI_DISTRIBUTION_PORT: "${PKI_PORT:-8082}"
STS_ADMIN_BOOTSTRAP_PASSWORD: ${STS_ADMIN_BOOTSTRAP_PASSWORD:-}
volumes:
- bao-client:/run/secrets/openbao:ro
- bao-startup:/run/secrets/openbao-startup
- db-ca:/run/secrets/database-ca:ro
- sts-data:/usr/src/sts/data
tmpfs:
- /run/sts-startup:mode=0700,uid=10001,gid=10001
command:
- sh
- -c
- |
find /usr/src/sts/data ! -user 10001 -exec chown 10001:10001 {} +
STARTUP="$$(node openbao/startup-secrets.js)" || exit 1
eval "$$STARTUP"
exec setpriv --reuid=10001 --regid=10001 --clear-groups \
--inh-caps=-all --bounding-set=-all --no-new-privs node server.js
healthcheck:
test: ["CMD-SHELL", "node -e \"require('https').get({host:'localhost',port:8081,path:'/healthcheck',rejectUnauthorized:false},r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))\""]
interval: 10s
timeout: 5s
retries: 6
start_period: 20s
volumes:
db-data:
db-ca:
db-initdb:
db-share:
bao-file:
bao-client:
bao-startup:
sts-data:
Beside it, a .env file with three secrets of your own. The seal key unseals
OpenBao at every start: lose it and nothing sealed under it can be read again.
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')
STS_DB_APP_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')
STS_BAO_SEAL_KEY=$(openssl rand -base64 32)
EOF
chmod 600 .env
docker compose up -d --wait
--wait returns once sts is healthy, a minute or two on a first start.
-
Signing in. The console’s first account has a generated name and a password generated on the first start. Both are written, as
name:password, todata/bootstrap-admin-password, which only the service can read; the log names the account and says where. The password has to be changed at the first sign-in. To choose the password instead, putSTS_ADMIN_BOOTSTRAP_PASSWORD=...in.envbefore the first start; the log then names the account, and no file is written.docker compose exec sts cat data/bootstrap-admin-passwordProduct mode requires a second factor, so you enrol one at that first sign-in. To script a sign-in with an authenticator app’s secret, generate the code with
oathtool:oathtool --totp -b "$TOTP_SECRET"Then open
https://localhost:8081/adminand accept the certificate. -
/admin-api, the first time. The seeded clientsts-api-client’s secret is generated by the seeder on the first start and kept in OpenBao atsecret/sts-admin. The service reads it once at eachup, and its own OpenBao identity cannot read it at all. To read it yourself, take the operator token the seeder prints (read-only on that one path, for 24 hours):docker compose logs --no-log-prefix openbao-seed \ | grep 'OPERATOR TOKEN' | tail -1 | jq -r .msg # the token ends the line BAO_OPERATOR_TOKEN='<token>' SECRET=$(docker compose exec -T -e BAO_TOKEN="$BAO_OPERATOR_TOKEN" openbao \ bao kv get -address=https://127.0.0.1:8200 \ -ca-cert=/openbao/file/tls/server.crt \ -field=adminApiClientSecret secret/sts-admin) curl -sk -u "sts-api-client:$SECRET" \ --data-urlencode grant_type=client_credentials \ --data-urlencode 'scope=admin:read admin:write' \ --data-urlencode resource=https://localhost:8081/admin-api \ https://localhost:8081/oauth2/tokenUse that token once, to create an application of your own with the
ADMIN_READandADMIN_WRITEroles and a client secret, and get every later token as that application with the client credentials grant. Management API → An application of your own has the steps. To choose the management API secret instead of having it generated, putADMIN_API_CLIENT_SECRET=...in.envbefore the first start; it goes to the seeder, not to the service. - The OpenBao recovery key. On the first start the seeder prints the
store’s recovery key, once (
docker compose logs openbao-seed | grep 'RECOVERY KEY'), and then revokes the root token. Nothing on disk keeps either one. Keep the recovery key:bao operator generate-rootneeds it to make a root token again. docker compose up, notrestart. Everyupruns the seeder, which gives the service a new single-use start-up token.docker compose restart stsdoes not run the seeder, so the service starts without the pinned management API secret and mints one that nobody can read.- The service runs as uid 10001, not root. The
stscontainer starts as root only to take the start-up secret, then drops to uid 10001 with every capability removed before the service starts. A shell as that user can read the service’s own OpenBao client credential (mode 0600), and no other secret on disk or in its environment. -
Upgrading to a newer image. Pull it and
docker compose up -d, then bring the database’s schema up to the image’s: thepostgres-initcontainer copies the newschema.sqlon everyup, but the database runs it by itself only on its first start, and the service refuses to start on an older schema (STS-STORE-0029indocker compose logs sts). Run it once as the owner, then start the service again:docker compose exec postgres bash -c 'psql -v ON_ERROR_STOP=1 -U sts -d sts \ -v sts_schema=sts -v sts_app_role="$STS_DB_APP_USER" \ -v sts_app_password="$STS_DB_APP_PASSWORD" \ -f /usr/local/share/sts/schema.sql' docker compose up -d stsEvery statement in it can be run again, so running it when nothing changed does no harm. A change to the database’s server settings in this file takes effect when the
postgrescontainer is recreated, whichup -ddoes. - Stopping it.
docker compose downkeeps everything in the named volumes, and the nextupcomes back with the same directory, signing keys and sessions.docker compose down -vdeletes it all. - Which build.
IYA_STS_TAGpicks the image tag:latestis the newest build ofmain, the release’sM.N.O(1.0.0) is the newest build ofmainfor that release, and the fullM.N.O.<build>(1.0.0.0, or1.0.0.20261104151200) names exactly one build.STS_PORT,PKI_PORTandKDC_PORTmove the published ports. - Kerberos works from the start. The KDC is published on 88 (TCP and
UDP), and the SPNEGO acceptor holds
HTTP/localhost, the name a browser asks for athttps://localhost:8081, under a random key the service makes itself. SetKRB5_SERVICE_PRINCIPALtoHTTP/<host>when you reach the service by another name. The client side is in Kerberos: signing in from a browser.
What the checkout’s own docker-compose.yml has and this does not: the optional
remote XACML PEP (the xacml profile), and the extra addresses a realm’s own
SPIFFE listeners bind. LDAP is running but not published; add 389 or 636
to ports to reach it from the host.
Configuration covers every setting the environment block
can take.
Confirming it works
curl -sk https://localhost:8081/healthcheck
curl -sk -L https://localhost:8081/admin/sts-metadata | head -40
The -k is the bootstrap and not a shrug. The main port is TLS on a
self-signed certificate this service generates at every start, so nothing that
existed before this process can verify it — and with global.https on there is
no plain listener left to fetch it from either. One unverified call gets it, and
everything after that can be verified:
curl -k https://localhost:8081/tls/server-certificate > /tmp/sts.pem
curl --cacert /tmp/sts.pem https://localhost:8081/healthcheck
export NODE_EXTRA_CA_CERTS=/tmp/sts.pem # for a node client
It is the same certificate LDAPS 636 and the embedded debugger’s listener serve, so that is one trust decision for the whole service rather than three.
The second one is behind the console gate, which is unconditional: with no
session it answers a 302 to the sign-in screen, which is why the -L is there
and why what comes back is that screen rather than the page. Open it in a
browser and sign in — any username, since this service checks no password in
its default development mode. There is no setting that opens the console;
admin.authRequired is gone; global.mode answers that question. /admin-api reads the same service for a program, and takes an OAuth
2.0 access token of its own.
SAML 2.0 needs a service provider of your own to drive end to end — there
is no built-in one in the service (#592); the test suite’s is the test peer
(tests/peer/). https://localhost:8081/saml2/metadata is the identity provider
metadata; https://localhost:8081/saml2/metadata/anything-you-like is a document of its
own for a service provider by that name, minted on the spot — in development mode
only. In product mode that is a 404 until the service provider is registered.
/admin/sts-metadata is the sharper of the two. It reads the endpoint list off the
live Express router, so it answers only once every protocol module has registered
its routes — a module that loaded but registered nothing shows up there and not
in the liveness probe. Add ?format=json and look at undocumentedPaths,
stalePaths and unknownSpecIds: all three empty is the service agreeing with
its own description of itself.
Which build am I running?
Every page says so, and so does the log. The version is M.N.O.build:
the release, exactly as the repo-root VERSION file says it (1.0.0),
followed by a build number. An ordinary build is numbered by the UTC
instant the image was built, YYYYMMDDHHMMSS; a release build names its
own number, so the 1.0.0 release is 1.0.0.0. The commit it was built from
and the build instant are reported beside it.
1.0.0.20261104120000 an ordinary build of release 1.0.0
1.0.0.0 the 1.0.0 release build
Build 20261104120000 — Built 2026-11-04T12:00:00Z — commit 0123456789ab
The quickest ways to read it:
curl -sk https://localhost:8081/admin-api | head -10 # version, build, release, commit, builtAt, stamped
curl -sk https://localhost:8081/home-api/front # the front page's version
node common/version.js # from a checkout, without running it
It is also in the foot of every admin console page and every user portal page
(the build in the tooltip), in the first paragraph of /admin/sts-metadata
(whose JSON carries build.number, build.release, build.commit and
build.at), and in the first line the
service logs when it starts.
The remote XACML PEP reports one too, if you are running it
(docker compose --profile xacml up). It is on that container’s own GET /
and in the Version column of /admin/xacml/peps on this service’s console:
curl -s http://localhost:9090/ | head -20 # the PEP's own page
Its release always matches this service’s — both images are built from
one tree and one VERSION file — while an ordinary build’s build number is
its own (its build.number and build.at), because they are two images
built at two instants. Built as the same release, both are the same version
(1.0.0.0). So a different release on that row is a PEP left behind across an
upgrade, and a different build number is just two artifacts.
stamped is the field worth knowing about. A container reports a build
that was fixed when the image was built, so restarting it reports the same
one. A checkout run with node server.js was never built at all — it records
the instant the process started and reports stamped: false, and every page
says so in as many words. Two instances of the same release with different
build times mean nothing if neither was ever built.
To name the commit an image was built from:
GIT_COMMIT=$(git rev-parse HEAD) docker compose build sts
The commit is a build argument rather than something the image works out,
because the build context deliberately carries no .git.
Building a release
A release build is flagged and names its build number. Pass both build arguments, to both images:
docker build --build-arg STS_RELEASE=true --build-arg BUILD_NUMBER=0 .
docker build --build-arg STS_RELEASE=true --build-arg BUILD_NUMBER=0 \
-f xacml-pep/Dockerfile .
# or, both at once:
STS_RELEASE=true BUILD_NUMBER=0 docker compose --profile xacml build
That is 1.0.0.0. The build number is a non-negative integer with no leading
zero. STS_RELEASE=true with no valid BUILD_NUMBER fails the build
(STS-CORE-0164) rather than making a release with a date in it. Without
STS_RELEASE=true, BUILD_NUMBER is ignored and the build is numbered by its
build instant, so a CI system’s own BUILD_NUMBER cannot make an ordinary
build look like a release.
First-Time Admin Login
The console is at https://localhost:8081/admin. Who signs in first depends
on the mode the service is running in.
In development mode
A plain docker run (In a container, above) starts in development mode. The
first account is admin, and development mode checks no password, so any
password signs it in.
In product mode
The compose stack (With PostgreSQL and OpenBao, above) starts in product
mode, where a default account name such as admin is not allowed (ASVS 5.0.0
6.3.2). On the first start, with nobody in the directory holding a credential,
the service makes the first administrator with:
- A generated username,
admin-followed by 16 hexadecimal characters, for exampleadmin-3f9c2a71d04e8b65. It is derived from the cluster’s shared key, so every node and every restart arrives at the same name. - A generated password, written to the file
bootstrap-admin-passwordin the data directory, readable only by the service. It is not written to the log.
The file holds both, as username:password. Read it with:
docker compose exec sts cat data/bootstrap-admin-password
Everything after the first colon is the password. The startup log names the account and the file, once:
PRODUCT MODE BOOTSTRAP — THIS IS SHOWN ONCE AND NEVER AGAIN.
username: admin-3f9c2a71d04e8b65
password: in the file /usr/src/sts/data/bootstrap-admin-password
Then:
- Go to
https://localhost:8081/adminand enter the username and the password from the file. - Change the password when asked. The new one must meet the password policy, which you can change later under Directory → Policies.
- Enrol a second factor when asked: product mode requires one.
The file is written once and never updated, so it holds the generated password even after you change it. Delete it once you have signed in.
Four settings change this, and each must be set before the first start:
| Setting | Environment variable | Effect |
|---|---|---|
admin.bootstrapUsername |
STS_ADMIN_BOOTSTRAP_USERNAME |
A name that is not a default one (admin, root, sa, administrator) is used as given. |
admin.allowDefaultUsername |
STS_ADMIN_ALLOW_DEFAULT_USERNAME |
On, a default name is used as given instead of a generated one. |
admin.bootstrapPassword |
STS_ADMIN_BOOTSTRAP_PASSWORD |
The password is yours instead of generated; no file is written and the log does not print it. |
admin.logBootstrapPassword |
STS_ADMIN_LOG_BOOTSTRAP_PASSWORD |
On, the generated password is printed in the log instead of written to the file. |