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.exe on your Windows PATH. A Cygwin shell inherits that PATH.
  • Cygwin’s own bash, git, coreutils, sed, curl and jq packages. 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 .gitattributes turns line-ending conversion off, so a clone made with Git for Windows (whose default is core.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 with git 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.sh serves your aws login or 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 as AWS_ACCESS_KEY_ID and AWS_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.sh stops and tells you to run az 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 trying sudo. Files a container writes into your checkout are owned by you, so the --user and 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 a tls object with its own pair (an admin console page, so it needs a session; GET /admin-api/ldap/service is 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 …, or STS-CORE-0029 naming 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, to data/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, put STS_ADMIN_BOOTSTRAP_PASSWORD=... in .env before the first start; the log then names the account, and no file is written.

    docker compose exec sts cat data/bootstrap-admin-password
    

    Product 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/admin and accept the certificate.

  • /admin-api, the first time. The seeded client sts-api-client’s secret is generated by the seeder on the first start and kept in OpenBao at secret/sts-admin. The service reads it once at each up, 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/token
    

    Use that token once, to create an application of your own with the ADMIN_READ and ADMIN_WRITE roles 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, put ADMIN_API_CLIENT_SECRET=... in .env before 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-root needs it to make a root token again.
  • docker compose up, not restart. Every up runs the seeder, which gives the service a new single-use start-up token. docker compose restart sts does 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 sts container 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: the postgres-init container copies the new schema.sql on every up, but the database runs it by itself only on its first start, and the service refuses to start on an older schema (STS-STORE-0029 in docker 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 sts
    

    Every 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 postgres container is recreated, which up -d does.

  • Stopping it. docker compose down keeps everything in the named volumes, and the next up comes back with the same directory, signing keys and sessions. docker compose down -v deletes it all.
  • Which build. IYA_STS_TAG picks the image tag: latest is the newest build of main, the release’s M.N.O (1.0.0) is the newest build of main for that release, and the full M.N.O.<build> (1.0.0.0, or 1.0.0.20261104151200) names exactly one build. STS_PORT, PKI_PORT and KDC_PORT move 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 at https://localhost:8081, under a random key the service makes itself. Set KRB5_SERVICE_PRINCIPAL to HTTP/<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 example admin-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-password in 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:

  1. Go to https://localhost:8081/admin and enter the username and the password from the file.
  2. Change the password when asked. The new one must meet the password policy, which you can change later under Directory → Policies.
  3. 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.