Configuration

There is exactly one place a setting is read, common/config.js, and one table inside it. That is not tidiness — it is what makes the next three sentences possible.

From one row in that table, a setting appears in the admin console — on the page for the protocol it configures — in GET /admin-api/config, in the management API’s OpenAPI document, and in the startup audit that logs what the appconfig file omitted and what key it carried that the table does not know. None of those four has a list of its own. A process.env read added anywhere else is invisible to all four, which is the state this arrangement exists to end.

How a value is resolved

Five levels, first match wins:

1. A runtime override — set on the console page for that setting’s protocol, or through POST /admin-api/config/set
2. The environment variable
3. A legacy environment variable — there is exactly one, STS_ISSUER
4. The appconfig file named by CONFIG_FILE
5. env/defaults.js — the default appconfig file that 4 is unioned on top of

Environment beating the file is deliberate: it is what keeps existing containers and test harnesses working when the shipped env/*.js files carry every key.

There is no sixth level. A setting with no value in 4 or 5 and no variable in 2 or 3 stops this service from starting, naming every such setting and both places its value could go. A value that arrives from a constant buried in a module is a value nobody can find, change or see on a page, which is the state this arrangement exists to end — so there is no silent fallback underneath the table to lead back into it. The refusal looks like this:

config: FATAL — 2 setting(s) have no value in the appconfig layer and no environment variable:

  global.domain       STS_DOMAIN
  spiffe.trustDomain  STS_SPIFFE_TRUST_DOMAIN

Each must be set in ./env/local.js, in ./env/defaults.js (the default appconfig
file every other one is unioned on top of), or as the environment variable
beside it.

Levels 4 and 5 are one layer, unioned. env/defaults.js carries a default for every setting; the file CONFIG_FILE names is merged over it key by key and the operator’s value wins wherever both carry a key. So a config file may carry as few keys as its author likes and still be complete — a file carrying only logLevel resolves everything else through the defaults, which is what lets the parent project’s in-process Kerberos jobs point CONFIG_FILE at their own test config and still load these modules — and a setting added to the table tomorrow does not break every config file in the world on the day it is added. What the refusal above actually catches is the one case left: a setting added to common/config.js’s table with no row in env/defaults.js, which is a setting somebody added and did not finish adding.

env/defaults.js is GENERATED from the table — node env/generate_defaults.js writes it from the dflt column, where each default is written down next to the paragraph explaining why it is the default — and is not the file to edit. Two copies of a default is one copy that will be wrong, and wrong in the quietest possible way: the service running on one value while the console, the OpenAPI document and the settings list all report the other. To configure a deployment, edit the file CONFIG_FILE names or set the environment variable.

CONFIG_FILE is the one environment variable with no appconfig key, and it cannot have one: it is what chooses the file. It names a JavaScript module, resolved against the package root and then against the working directory, so ./env/local.js works from wherever the process was started. It defaults to nothing: unset, every value comes from env/defaults.js or from the environment. A file that cannot be loaded is fatal and says so, because continuing would mean starting a service configured as nobody asked for.

Every setting has an environment variable, and four settings are exempt from the refusal above and from both files, marked (derived) in Every setting, because their default is DERIVED from a neighbour rather than written in a file: global.https from oauth2.rfc9700, oid4vp.walletUrl from oid4vci.walletUrl, krb5.serviceDomains from krb5.realm, and adminApi.audience — the base URL of the management API — from global.publicBaseUrl, or from the main port’s scheme, host and port where that is empty. A literal in a file would freeze the derivation at whatever it evaluated to the day the file was written. Each still has its own key and its own variable, and setting either replaces the derivation.

A DERIVED DEFAULT IS NOT THE SAME AS AN ABSENT VALUE, and global.https is the one where the difference is visible: the appconfig files in env/ all set it explicitly, so the derivation is what a service reading some OTHER file falls back to and not what any stack here runs on. See its own section below.

Every setting, below, lists every appconfig key, its environment variable, its default and whether it can be changed without a restart.

STS_ISSUER is the one legacy level because it used to be a single value serving as the SAML assertion issuer, the WS-Trust token issuer AND the WS-Federation entityID. Those are three different things that happened to share a default — an entityID names an identity provider, an Issuer names whoever signed an assertion — so they are now saml.issuer, wstrust.issuer and wsfed.entityId, all three still fed by STS_ISSUER when it is set. saml.issuer is the <saml:Issuer> of every SAML assertion (WS-Federation’s included, since the same two functions build them); wstrust.issuer is the iss of the JWT this STS returns; wsfed.entityId is the entityID in the federation metadata. All three default to urn:wstrust:mock:sts.

An environment variable is a string, and the table knows what to do with it

A bool takes 1/true/yes/on and 0/false/no/off in either case. A csv is a comma-separated list, trimmed, and may be written as a real array in an appconfig file; a list drawn from a closed set (csvValues) holds only its members. An enum holds one of its enumValues, spelt exactly. An int may narrow itself with a minimum, a maximum and a multiple-of — the four token lifetimes do.

These are one check, wherever the value is written. The console’s form, the management API, a realm’s override, the appconfig file and the environment are all held to it. A value typed into /admin/config that would be refused is refused the same way at startup: the service does not start (STS-CORE-0108), and it names every offending value, the file or variable it came from, and what the setting accepts. For example, LDAP_AUTOCREATE_USERS=treu, STS_PKI_KEY_ALGORITHM=RSA-2048 (the ids are lower case) or webauthn: { algorithms: 'ES256,NOSUCHALG' } all stop the start. Every layer that holds a value is checked, including one an environment variable currently shadows, because it becomes live when the variable is unset.

Runtime versus restart-only

Every row declares whether it can change while the service is running. A restart-only setting is REFUSED rather than accepted, with the reason, because an accepted change that does nothing reads as having worked.

Three kinds are restart-only and it is worth knowing which:

• A bound socket. Every port above, and the main port’s scheme — see global.https below.
• Material derived at startup. The TLS certificate is issued for tls.hostnames / tls.ips at boot; the Kerberos principal database and every long-term key in it come from the realm, the SIDs and the passwords at require time.
• The directory tree, which global.domain is the root of (the default realm’s; every other realm’s is its own domain, fixed when it is created).

Everything else is live. That is why so much of the code reads a setting through a function call rather than a module-level const — a const captured at require time is the one thing a runtime override cannot change, and it fails in the direction that looks like the console is broken.

The settings worth knowing about first

oauth2.rfc9700 — the compliance mode

Off by default. On, it turns the OAuth 2.0 / OIDC authorization flow into an RFC 9700-conforming one: registered redirect URIs, PKCE, no implicit grant, no password grant, refresh token rotation with replay detection, sender-constrained tokens, one-shot authorization codes.

Sender-constrained does not mean required. Section 2.2.1 makes it a SHOULD, and the mode honours a DPoP or RFC 8705 binding wherever a client offers one rather than refusing a client that offers none. The five settings under Sender constraints below are how an operator asks for more than that.

Off changes nothing. Every existing caller of this mock uses an unregistered redirect_uri, no PKCE, or the implicit grant, and both answers exercise a client — so the flag has to be able to be off and the mode has to be complete.

It is restart-only, and only because of a socket: global.https derives its default from it, so turning it on binds the main port as HTTPS. A flag that was runtime for its checks and restart-only for its socket would report the mode as on while every authorization response still went out over plain HTTP.

What it does and does not enforce is published at GET /oauth2/rfc9700, row by row, with enforced as yes, detected, always, deployment or no — two requirements are no because they are the client’s and nothing this server observes can tell a client that checks from one that does not.

oauth2.oauth21 — OAuth 2.1, and it turns the mode above on

Off by default. On, it enforces the OAuth 2.1 Authorization Framework (draft-ietf-oauth-v2-1-16, still a draft) — which means RFC 9700 mode plus what 2.1 adds: PKCE for confidential clients too, a client that registered its own redirect URI (oauth2.redirectUris is not read), a presented credential that must verify, a JWT client assertion addressed to the issuer alone, no SAML client authentication, no repeated parameters and a ten-minute code.

It is not RFC 9700 mode renamed. That mode requires redirect_uri at the token endpoint, which OAuth 2.1 removed, and requires it at the authorization endpoint even when the client registered one; a client written for 2.1 is refused there and answered here.

Restart-only and settable on a trust realm, for exactly the reason above. GET /oauth2/oauth21 lists every requirement it adds, which it inherits, and the grants it deliberately exempts.

oauth2.fapi — a FAPI security profile, and it turns RFC 9700 mode on

off by default. 1-baseline enforces FAPI 1.0 Part 1: Baseline (final): RFC 9700 mode, plus confidential clients authenticating by mutual TLS, private_key_jwt or client_secret_jwt, key sizes, PKCE with S256 for every client, an https redirect_uri always sent, nonce with openid and state without it, the person’s own consent, one client per request, and access tokens of at most ten minutes unless sender-constrained.

Restart-only and settable on a trust realm, for the reason above. A named authorization server may also carry its own value, or off to opt out of its realm’s (the fapi member on /admin/authorization-servers). GET /oauth2/fapi lists every requirement. See OAuth security.

1-advanced is FAPI 1.0 Part 2: Advanced (final) on top of all of that: a signed request object, code id_token or code with JARM, sender-constrained access tokens only (oauth2.fapiRequireMtls makes that mutual TLS only), private_key_jwt or mutual TLS client authentication, and PS256 or ES256 for every signature. See OAuth security.

2-security is the FAPI 2.0 Security Profile (final), a profile of its own: confidential clients only, PAR required, code only, PKCE S256, sender-constrained tokens by mutual TLS or DPoP, codes of 60 seconds, no refresh-token rotation, and PS256, ES256 or EdDSA. See OAuth security.

2-message-signing is FAPI 2.0 Message Signing on top of that: a signed request object at PAR, JARM required, and signed introspection responses. See OAuth security.

Sender constraints — five settings that ask for more than either mode

Neither OAuth 2.1 nor RFC 9700 requires DPoP, and that is worth saying once before the five rows below. OAuth 2.1 section 4.3.1 gives a public client’s refresh token a choice of two treatments — sender-constrained, or rotated with replay detection — and this service already takes the second. RFC 9700 section 2.2.1 makes a sender-constrained access token a SHOULD, and nothing anywhere makes it a MUST.

So none of these five is implied by either mode and every one of them defaults to off. They exist because a client under test should be able to meet a strict authorization server here before it meets one in production. All five are runtime settings and therefore per trust realm: one realm may demand a proof while the next does not.

Four of the five refuse. Everywhere else this service prefers to answer with something weaker rather than not answer at all; these do the opposite, and that is the point of them. The fifth, oauth2.refreshTokenRotation, changes what is issued rather than what is accepted.

oauth2.refreshTokenRotation

Off. On, every refresh issues a NEW refresh token, the one that was spent is refused, and a replay is treated as a compromise: the whole family descended from the original grant is revoked rather than only the token replayed (OAuth 2.1 section 4.3.1, RFC 9700 section 4.14.2).

RFC 9700 mode and OAuth 2.1 mode already do this for every client, so this setting is how to have it with both modes off. Turning it off while a mode is on changes nothing — the mode is the stricter answer and wins.

What it does not bring with it is the rest of RFC 9700 section 2.2.2. The idle timeout (oauth2.refreshIdleSeconds), the client binding and the scope subset check stay behind oauth2.rfc9700, because none of them is what asking for rotation asked for. What does come with it is replay detection, because rotation without it is bookkeeping nobody reads.

A refresh token minted before it was turned on carries no family and is rotated from its next use, so there is nothing to migrate.

oauth2.refreshTokenRequireDpop

Off. On, a token request that would mint a refresh token and carries no DPoP proof is refused, and the refresh grant is refused unless the presented refresh token is bound (cnf.jkt) to the key that proves this request (RFC 9449 section 5).

What it changes for a confidential client. With the setting off, RFC 9449 section 5 is followed as written: a refresh token issued to a public client is bound to its DPoP key, and one issued to a client that authenticated on the token request is not — “they are already sender-constrained with a different existing mechanism”, the client’s authentication — so that client may prove a new key at each refresh, and the access token it gets is bound to the new one. On, every refresh token is bound, a confidential client’s too. (Until 2026-09-24 a confidential client’s was bound either way, and the OpenID conformance suite’s FAPI 2.0 refresh module failed on it — #176.)

The whole token request is refused, access token included. Minting the access token and dropping the refresh token silently would leave a client that believes it has a durable grant and discovers otherwise an hour later, which is a worse failure than the error it gets instead.

An unbound refresh token is refused rather than bound on first use. Binding it would be the friendlier answer and the wrong one: the token was handed out with no constraint, anybody holding it could bind it to a key of their own, and the operator who turned this on would have been told the tokens were constrained at the moment a stolen one constrained itself. The message says to sign in again for a bound one.

Nothing is exempt from this setting, and nothing needs to be. /admin and /portal are OpenID Connect clients of this service, and they carry a DPoP key of their own and prove it on every back-channel token call — so turning this on does not lock an operator out of either. The two clients named under the next setting are exempt from that setting only.

oauth2.refreshTokenRequireMtls

Off. The same refusal for RFC 8705: no refresh token is issued over a connection carrying no verified client certificate, and the refresh grant requires the presented token’s cnf["x5t#S256"] to match the certificate on this connection.

RFC 8705 section 7.1 still passes a client that authenticated with tls_client_auth or self_signed_tls_client_auth on the same request and owns the token, whether or not the token carries a thumbprint. That client’s refresh token is bound to the CLIENT rather than to the certificate, which is exactly what the section is for: it may rotate its certificate without stranding the grant.

It needs global.https. A listener that cannot ask for a client certificate cannot be satisfied by one, so where the main port is plain HTTP every affected request is refused with STS-OAUTH-0527 rather than let through.

Two clients are exempt, and from this setting only. The seeded sts-admin-console and sts-user-portal clients — this service’s own relying parties — redeem their codes and refresh tokens over a loopback call from this process to itself, where there is no certificate to present and nobody on the other end who is not already this process. sts-debugger-ui is deliberately not exempt from anything: the embedded debugger is an ordinary client of this authorization server and is configured to meet whatever the realm it points at requires.

oauth2.accessTokenRequireDpop

Off. On, a request presenting an access token as anything other than a proved, DPoP-bound token is refused: the token must carry cnf.jkt and the request must carry a proof for that key.

It is a refusal at the RESOURCE and nowhere else. The token endpoint goes on minting Bearer tokens, which these surfaces then refuse — that is what lets a client be driven against the refusal rather than merely told about it, and it is why a 401 here is not a bug in the issuer.

What it covers is every surface that accepts a PRESENTED access token: UserInfo, the RFC 9470 step-up resource, the three OpenID4VCI endpoints, /scim/v2, the Shared Signals endpoints, /admin-api and the embedded debugger’s listener. What it does not cover is what is not an OAuth access token presented as a credential: GNAP’s own tokens, an RFC 7592 registration access token, and the endpoints that take a token as a parameter (introspection, revocation, token exchange).

A token this service did not issue is held to it too. The confirmation a token carries can be read without trusting the token, and one carrying none cannot satisfy a requirement that it be constrained — so unlike the binding checks that run in every mode, this one does not step aside for a token that cannot be verified.

/admin/api-explorer stops working while it is on, because its script sends a plain Bearer header. Use curl with a DPoP proof, or turn the setting off for that realm.

oauth2.accessTokenRequireMtls

Off. The RFC 8705 half of the setting above, at the same surfaces: a presented access token must carry cnf["x5t#S256"], and the connection must present that certificate.

It needs global.https, for the reason oauth2.refreshTokenRequireMtls does, and it is refused with the same STS-OAUTH-0527 where a certificate cannot be asked for.

The debugger’s listener asks for a client certificate so that a bound token can be presented there at all — requestCert with rejectUnauthorized: false, the posture the main port already takes, so the handshake succeeds either way and what a certificate is worth is decided per request. A listener that never asked would have made this setting an exemption dressed up as a refusal.

oauth2.delegatedPermissionsEnforced — the OTHER mode, and not part of the first

Off by default, runtime, and settable on a trust realm. It matters in development only: product mode refuses an ungranted permission whatever it says (#110).

It refuses an authorization or token request that asks for a delegated permission the client has not been granted. A resource application exposes an API — a base URI and a list of permission names, joined into https://example.com/write — and a client application is granted some of them; the shape is Microsoft Entra ID’s. /admin/delegation is where the RESOURCE half is typed — the base URI and the permission names — and the GRANT is typed on the client application’s own page under Directory › Applications, where the client half of the pair is the entry you are looking at rather than an option in a list of every application in the service.

It is deliberately NOT part of oauth2.rfc9700. Every check in that mode cites a section of a published Best Current Practice. A delegated permission cites nothing, because no RFC says an authorization server must have one — it is a product’s design rather than a standard — so folding it in would make GET /oauth2/rfc9700 advertise a requirement no document contains.

Off, in development, changes nothing about what is issued, which is what makes the register usable before anybody enforces anything: a permission scope still becomes the token’s audience and its scope claim, and the console still marks which requests were not backed by a grant. On, the same request is invalid_scope at the AUTHORIZATION endpoint — where the client can still be told — and at the token endpoint for the grants that never reach it.

It does not re-judge a grant already issued. An authorization code redeemed without a scope of its own carries what was authorized, and this service does not go back and ask whether that is still allowed — so turning it on refuses the next REQUEST rather than invalidating what is outstanding, which is what makes it safe to turn on while something is running.

oauth2.consentRequired — the one setting here that is ON by default

Runtime, settable on a trust realm, and on unless you turn it off, which no other policy in this service is.

The first time a given username signs in to a given client_id for a given scope, /oauth2/consent is drawn listing the scopes that are new. Nothing is issued until they press Allow; Deny returns access_denied to the client and records nothing at all.

Why on, when everything else here is off. Every other refusal is off by default because this service exists to exercise clients and a refusal that cannot be turned off removes a test case rather than adding one. Consent is not a refusal — it is the screen every real authorization server draws on a first sign-in, and a client that has never met one has never run the code that survives it: the extra redirect, the second visit to the authorization endpoint, the access_denied when somebody says no. Off by default would have meant the interesting behaviour was the one nobody saw.

OFF means what this service did before the screen existed — nothing asked, nothing recorded. It is not “everybody consented”: no agreement is written down, so turning it back on asks again.

Where the answer goes

oauthConsent on the person’s own entry under ou=users, one value per (person, application, scope):

oauthConsent: 20260901143000Z openid webapp1
oauthConsent: 20260901143000Z https://example.com/write webapp1

When it was agreed, the scope, and the application — the client_id last, because it is the only field with no rule about what it may contain, so it takes the remainder of the value. A delegated permission is recorded by its WHOLE identifier and never by the bare permission name, because two resources may each expose a read.

One value per triple and never one per request: a consent recorded against the whole scope string would make openid profile and profile openid two different agreements, and adding one scope would throw away the agreement to the other four. A second visit asks about the difference, with what was already agreed under a fold.

Consenting a scope for everybody

oauthGlobalConsent on the client application’s entry, one value per scope, typed at /admin/consent or through POST /admin-api/consent/grant-global-consent. A scope named there is never asked about and nothing is written about anybody.

Two things follow, and both are the difference between an override and a record:

• Removing one asks everybody again, including the people who would have said yes. Removing a person’s own answer asks one person.
• It is keyed on the pair, not on the scope. Consenting read consents it for that application; one registered five minutes later that spells the same word is still asked.

Both are ordinary attributes on ordinary directory entries, so an ldapmodify is a configuration change here exactly as it is for a redirect URI, and they persist wherever the directory does.

The two prompt values

prompt=consent asks again whatever is on the entry and takes nothing away. prompt=none with something outstanding is consent_required — OpenID Connect Core section 3.1.2.6’s own code rather than the general interaction_required, because a client that gets the general one cannot tell a missing session from a missing consent.

Withdrawing a consent ends what was issued under it (#172)

Revoking a consent — one scope, one application, a person’s whole list, or a global consent — revokes every access and refresh token issued under it, on every node, and writes the instant down: oauthConsentWithdrawn on the person’s entry, oauthGlobalConsentWithdrawn on the application’s. A refresh token carries when its grant was made, and the refresh grant refuses it when a consent it stood on was withdrawn at or after that — whatever the mode, and even after the person consents again. Withdrawing one scope revokes the whole refresh token. A person withdraws their own at /portal/consents.

oauth2.refreshRequiresConsent — a grant nobody agreed to is not renewed

Runtime, settable on a trust realm, on by default. While consent is required (oauth2.consentRequired, or a FAPI 1.0 profile), a refresh token issued at the authorization endpoint is renewed only if every scope it carries was covered, when it was granted, by the person’s own recorded consent or by the application’s global consent. Otherwise the refresh is invalid_grant (STS-OAUTH-0616). That is a token obtained while consent was off, or while the directory could not record the answer; turning consent on sends each such client back through the authorization endpoint once. A withdrawn consent is refused whatever this says, and refresh tokens from the grants that never ask anybody (the password grant, token exchange and the like) are held to withdrawals only.

Warning. Turning this off renews grants that nobody agreed to. A client that obtained a refresh token while consent was off keeps renewing it for the token’s whole lifetime — while the person is away, if it holds offline_access — although this service now requires their consent.

oauth2.tokenExchangeRefreshToken — three servers, one switch

Runtime, settable on a trust realm, and the only OAuth setting here whose value is a WORD rather than a number or a yes/no.

An RFC 8693 token exchange trades one token for another. Whether the response also carries a refresh_token is left to the authorization server by section 2.2.1, which names the case it is for: a client that must keep reaching a resource “even when the original credential is no longer valid” — the user-not-present case, where there is no session by design. Real authorization servers differ, so this one can be any of them:

Why three words and not a switch. false would have had to mean never, which leaves true meaning either of the other two and no way to reach the third — and always is the interesting one to point a client at, because a credential arrives that it never asked for and must not leak.

What comes back is an ordinary refresh token of this service, in every case and by construction: it is minted by the one function every grant here mints one through. It redeems at the refresh grant, reports at /oauth2/introspect, is revocable at /oauth2/revoke, lives for oauth2.refreshTokenTtlS, rotates wherever rotation is required (RFC 9700 mode, OAuth 2.1 mode or oauth2.refreshTokenRotation), and is bound to the DPoP key or client certificate the exchange was made with. It also remembers the RFC 8707 resources the exchange named, so a renewal cannot widen the audience the exchange narrowed.

issued_token_type says access_token throughout. It describes the token in the access_token member, and that member holds an access token whichever way this is set.

One client at a time

oauthTokenExchangeRefreshToken on the client application’s entry, holding one of the same three words, overrides this for that client alone — typed on /admin/applications, on /admin/applications/new, or through POST /admin-api/applications/set.

The CLIENT performing the exchange and not the audience, for two reasons that point the same way: the refresh token is handed to the client, so it is that party’s credential to hold and redeem; and in the interesting case the subject the exchange is about has no entry here at all, the whole point of an exchange being a subject_token from somewhere else.

It is the one attribute in this registry that is REFUSED on an application of the wrong kind. It applies to the OAuth 2.0 and OpenID Connect families, and writing it onto an entry declared for neither is turned away by the console and by /admin-api, naming the family to tick first. Every other per-application setting is a default something reads if it ever gets the chance, so writing one onto an application that never reaches that protocol costs nothing; this one decides what the token endpoint does for a client_id, so on an entry no token request could ever name it would sit there reading like a policy that was in force. Clearing it is never refused, and ldapmodify reaches it like every other attribute.

A value that is not one of the three words is not an error either: the log says which entry carries what, and the service-wide setting decides.

global.https — TLS on the main port

ON in every appconfig file this repository ships. That is a statement about env/local.js, env/test.js and env/docker-tests.js, which each carry global.https: true, and NOT about the setting’s own default — that still derives from oauth2.rfc9700 and is still false, which is what a service handed somebody else’s appconfig file (the parent project’s Kerberos jobs, say) gets. Both compose files here set STS_HTTPS to the same answer, so the container’s healthcheck probes the scheme its service is actually bound in.

Why it was turned on: 8443, 9443 and LDAPS 636 were TLS and the main port — the one every one of the seventeen protocol families actually answers on — was not, so a caller who had already trusted this service’s key for three sockets still met an unencrypted fourth. One certificate, one trust decision, every port. The first two of those listeners have since been deleted, which makes the argument shorter rather than weaker: the port every protocol answers on is also the port a client certificate is presented to, so it is the last place that should be in the clear.

STS_HTTPS=false is the way back to a plain listener, and it is a supported configuration rather than an escape hatch: a client that cannot be taught to trust a certificate regenerated on every start is exactly what this service exists to exercise.

When it is on there is no plain HTTP listener in this process, which costs one thing that is stated on the page rather than left to be met as a handshake failure: POST /tls/trust and GET /tls/server-certificate exist to be reachable before anything is trusted, so the first call to each has to be made with verification off:

curl -k https://localhost:8081/tls/server-certificate > /tmp/sts.pem
export NODE_EXTRA_CA_CERTS=/tmp/sts.pem      # node trusts it from here on

It uses the same per-start certificate as LDAPS 636 and the embedded debugger’s listener, so a caller trusts this service once per start rather than three times. NODE_EXTRA_CA_CERTS accepts it despite its basicConstraints CA:FALSE — OpenSSL takes a self-signed leaf found in the trust store as an anchor — and without it a node client fails with DEPTH_ZERO_SELF_SIGNED_CERT, or, through fetch(), with a bare TypeError: fetch failed that names nothing.

ldap.autocreateUsers

On. Every identity that authenticates through any of the sixteen families gets an entry under ou=users, seeded from a single funnel rather than sixteen call sites. Turning it off gives you a directory holding only what somebody explicitly wrote into it.

groups.claim — and the reason it is safe to have on

On by default. It puts a claim naming somebody’s group membership into every access token, ID Token and both SAML assertions.

That is only defensible as a default because the claim is omitted entirely for somebody in no group — absent, not an empty array. On a fresh start the only people in a group are the three the directory seeds, so a caller who never touched ou=groups gets exactly the tokens it got before the feature existed.

Nothing reads the claim back. No endpoint checks it and nothing decides anything on it: carrying a group is not granting one. Two groups are the exception and are not an exception to that sentence — admin.readGroup and admin.writeGroup below are read from the directory by /admin, never from this claim, so a token carrying admin-write still does nothing a token without it cannot.

global.mode — and the four gate settings it replaced

scim.authRequired, spiffe.authRequired, admin.authRequired and ssf.authRequired are gone. They were one question with four answers, and a deployment that required a credential at SCIM and not at the console was not partly secured — it was unsecured with a longer configuration file.

All four gates are now unconditional, in both modes: /scim/v2 takes a credential, the SPIRE Server API takes an X509-SVID over mutual TLS, /admin takes a session and a role, and the Shared Signals endpoints take a credential.

What global.mode decides is whether what they ask for is checked. development is the default and is every release of this service before that date: a presented password is not verified, anything named is created, and there are no public-client restrictions — which is what makes this a mock. product runs the same protocol implementations with that permissiveness taken out, and additionally gates /admin-api. It is settable per trust realm, so one process can serve a development realm and a product realm at once.

Switching a realm from development to product does not carry over the return addresses development learnt. A SAML ACS URL, a SAML 1.1 shire, a WS-Federation wreply or a console/portal callback that a development-mode request put on an application entry is marked observed, and product refuses it until somebody confirms it on that application’s page (or with POST /admin-api/applications/confirm-address). Confirm or discard them before the switch; addresses recorded before the marking existed carry no mark and need reviewing by hand. See what is not checked.

Each gate is explained under what is not checked.

admin.readGroup, admin.writeGroup, admin.openWhenEmpty and admin.bootstrapUsername

The console’s two roles are two ordinary groups in the embedded directory — cn=admin-read and cn=admin-write by default — so /admin/rbac, POST /admin-api/rbac/grant, an ldapmodify and a SCIM PATCH all write the same membership. Write implies read.

admin.bootstrapUsername (admin) names the default realm’s bootstrap administrator — and every trust realm’s, where the account and the two groups belong to that realm and administer it alone (see trust realms). Startup creates it if it is absent and makes it a member of both groups. A realm created at runtime gets one at once, and in product mode the realm’s password is shown once by the create. A newly created account must choose a new password at its first sign-in, and the account cannot be deleted or renamed. In development any password reaches that screen. In product mode the account gets the generated password that is logged once.

admin.openWhenEmpty is honoured in development mode only. There it is on and keeps the console open to anybody who signs in until that account first signs in to /admin; every page says so while it lasts. Off, only members of the two groups may use the console from the start. A process that never seeded the bootstrap administrator keeps the older rule: open while neither group has a member.

Product mode never opens the console to anybody, whatever this setting says: only the roster decides, which at first is the bootstrap administrator alone. Until that account has claimed the console, its roles are honoured only from a password sign-in through its own realm, and only such a sign-in claims it — a federation partner asserting admin, a certificate whose CN is admin, a wallet or a Kerberos ticket holds nothing. The embedded debugger waits for the claim too. A realm with no bootstrap administrator and nobody on its roster is closed, and says so in the log at startup (STS-ADMIN-0798).

If the console is ever closed to everybody, /admin-api is the way back out: it is gated by a credential of its own (adminApi.authRequired, an OAuth 2.0 access token rather than a console session), so getting back in means holding that token and calling POST /admin-api/rbac/grant. In development, turning that one setting off restores an open API; in product it gates /admin-api by the console’s own session and roles instead.

Renaming a role group does not move anybody: the members stay in the old group, which stops granting anything the moment the name changes.

All four are process-wide: a trust realm cannot carry its own value, because they decide who administers the service.

The federation settings, and the one that is stricter than a mock usually is

federation.enabled is ON, and that is safe in a way it would not be anywhere else here, because the endpoints do nothing without a relationship: a partner is created disabled, and one that is enabled and half-configured refuses rather than half-working. Turning it off makes every /federation route 404 without changing any relationship — the blunt instrument, for taking the feature away for one test run.

federation.usernamePrefix is empty by default, and that is a real decision rather than a default nobody thought about. Empty means a federated alice and the local alice are ONE directory entry, which is right for a mock being pointed at a partner to see what comes back — a prefixed name makes every downstream token and assertion look unfamiliar. Set it to something like fed- the moment the question is whether federated identities share a namespace with local ones, which is the question it exists for. It is applied after the username is chosen, so changing it cannot change which incoming value was used.

federation.outbound governs the only outbound HTTP request this service makes — a partner’s token endpoint, UserInfo or JWKS. Turn it off for a deployment with no egress: SAML, SAML 1.1 and WS-Federation need no back channel at all, and an OpenID Connect partner can still be used with fedResponseType: id_token and its keys pasted into fedJwks.

A partner’s certificate is always verified in product mode, and plain http is never used there (#171). What travels on those requests is a client secret and an authorization code, at somebody else’s service. Three settings govern it, all off or empty by default:

• federation.outboundAllowHttp accepts an http:// endpoint — in development mode only;
• federation.outboundSkipTlsVerification accepts a certificate nothing here trusts — in development mode only, which is what federating against another mock on localhost needs. Product ignores it and refuses to set it;
• federation.outboundCaFile names a PEM file of CA certificates a partner may chain to, beside node’s own store, which is how product reaches a partner certified by a private CA.

Every request made insecurely is logged as such, rather than the setting being logged once at startup and forgotten. GNAP push (gnap.push…), Shared Signals push (ssf.push…) and the XACML PEP nudge (xacml.pepNotify…) have the same three settings each. The old single …AllowInsecure switches were removed and a service whose configuration still names one refuses to start (STS-CORE-0105).

Everything else about a relationship is not a setting at all: it is an entry under ou=federations, configured at /admin/federation, through POST /admin-api/federation/*, or with an ldapmodify.

Persistence

Three things can survive a restart. Nothing this service mints ever does, in any mode, and that is deliberate rather than unfinished: the signing key is regenerated on every start, so a token or an assertion that outlived it would verify against nothing.

memory is the default, so a run that says nothing about persistence behaves exactly as every run before this existed — which is why no test in the suite had to be told about it.

All but writeDelay are restart-only, because the store is opened and read before the HTTP listener binds. That ordering is also what makes restoring settings safe: only a runtime-changeable setting can be overridden at all, and a runtime setting is by definition one that is read per call rather than captured at startup — so nothing in a saved override file can reach global.https, oauth2.rfc9700 or a bound port.

A failed write is logged and never thrown. If the database goes away, the operation that triggered the write still succeeds, this service keeps answering out of memory, and /admin/persistence and GET /admin/ldap/service both carry the error. The next change recomputes the same difference and tries again, so a failure loses nothing.

Processes against one Postgres store coordinate. Every change goes into a monotonic log inside the transaction that made it, and each process applies what the others committed; a LISTEN/NOTIFY nudge only makes that prompt, so a missed notification costs latency and never a change. persistence.coordinate turns it off and persistence.pollInterval sets the worst-case lag. It shares state and not sockets — the KDC, the LDAP listeners and SPIFFE’s four are per process — and the replay caches converge rather than synchronise, except the RFC 7523 / RFC 7522 used-assertion history, which is claimed atomically. See Persistence.

The TOTP settings, and the two that behave differently from the rest

Eight totp.* rows, drawn on /admin/totp under Protocols. Two things about them are unlike every other setting in this service.

Six of them affect NEW enrolments only. The digest, the digit count, the period and the secret length are all copied onto a person’s enrolment when they scan the QR code, because they are what the QR code TOLD the authenticator app — and this service cannot change what an app was told after the fact. So changing totp.digits from 6 to 8 does not invalidate anybody: the next person to enrol gets eight, and everybody already enrolled goes on typing six. A setting that silently locked out everybody who had already set an app up would be the worst kind of knob.

totp.window is the exception and applies to everybody. How much a deployment forgives a phone with a drifting clock is a policy rather than something an app was told, so it is read live. The default is 1 — RFC 6238 section 5.2’s recommended maximum, which makes a code good for about ninety seconds. 0 demands a perfectly synchronised clock and is the setting to reach for when demonstrating what happens without one.

Leave totp.algorithm at SHA1 unless that is exactly what you are testing. Several widely used authenticator apps — Google Authenticator among them — ignore the algorithm parameter in the QR code and always compute SHA-1, so any other value produces a code that scans perfectly and then generates codes this service refuses, with nothing anywhere saying why. SHA-1 is not a weakness here: what RFC 4226 uses it for is a keyed MAC over a counter, not a collision-resistant digest.

The authentication policy’s TOTP row off (it was totp.enabled=false until #64) does not disable an existing enrolment. It stops new ones. A person who enrolled while it was on still holds the second factor their account is configured for, and the sign-in screen still asks for the code — a switch that silently downgraded every one of those accounts to a password alone would be a security control whose off position does something other than what it says. Clearing an enrolment is on that person’s own row under /admin/users, or POST /admin-api/mfa/clear-totp.

The recovery code settings, and the mechanism no specification defines

Five backupCodes.* rows, drawn on /admin/backup-codes under Protocols. They configure the way back in when the second factor is not to hand — the phone is lost or flat, the security key is at home.

This is the only mechanism in this service with no document behind it. Everything else implements somebody’s specification; nobody ever wrote one for a recovery code. What every identity provider does converges anyway — a handful of random strings, each accepted once — so the decisions that are left are this service’s own and common/backup_codes.ts argues each.

A person generates their own set, on /portal/mfa — a set is not issued automatically when a second factor is enrolled. The set is shown ONCE, and stored only when the person confirms they have kept it. Until they do it waits apart from their entry for backupCodes.pendingTtlS, and one that expires changes nothing about a set they already held. A person who holds a second factor and no set is prompted to generate one.

Generating again REPLACES the set whole; a set is never topped up. When it runs low the person generates a new one. An operator’s Clear on that person’s row under /admin/users (or POST /admin-api/users/clear-backup-codes) deletes a set; no console or API operation creates one or shows a code.

The codes are HASHED, one scrypt hash per code, as userPassword is. A secret this service only VERIFIES is hashed, and since the set is shown exactly once and never again, nothing has to be able to present a code back — which is what the earlier design, sealing the codes so the portal could show them again, had to give up hashing for.

None of these rows invalidates a set that exists, which is the way the totp.* rows above differ: those carry a paragraph about NEW enrolments because their values were told to an app this service cannot reach. A stored code is compared against its hash, so shortening backupCodes.length changes what the next set looks like and leaves an existing one matching exactly as it did. The recovery-code row off (it was backupCodes.enabled=false) likewise stops a new set being generated and takes nothing away: a switch that removed the only way back into an account whose phone is lost would be the worst one here.

Nothing but the person sees them, and only once. The console reports counts, the management API reports counts, and neither has an operation that returns a code. Showing them to whoever holds Admin Read would be an administrative door handing out a working second factor — the same refusal this service already makes about enrolling an authenticator app from the console.

Authentication describes the sign-in side: where a code is typed, what the session records, and why a spend that cannot be written refuses the sign-in.

The WebAuthn settings, and the one of thirteen this service enforces

Thirteen webauthn.* rows, drawn on /admin/webauthn under Protocols. The specification and the browser decide the cryptography, not the ceremony: the RP name, the algorithms offered, the user verification requirement, the attestation conveyance and the timeout are this service’s choices, and these rows are how to ask for a ceremony shaped another way.

They are three kinds of thing and the page says which each is, because the kind decides what it means:

• THE CEREMONY — rpName, rpId, algorithms, userVerification, attestation, timeoutMs. Handed to the browser in the options and no more.
• CTAP2 — authenticatorAttachment, residentKey, credProps. Also handed to the browser, and translated by it into what it asks the AUTHENTICATOR for: which kind may answer, whether the credential is discoverable (a resident key, which is what a passkey is), and whether the browser is asked to report back which it made.
• POLICY — enabled, primaryAllowed, mfaAllowed, maxKeysPerPerson. Not WebAuthn at all: what THIS service will do with a key once the ceremony is over.

webauthn.userVerification IS THE ONE THIS SERVICE CHECKS. required is sent to the browser AND the UV flag in the signed authenticator data is verified when the ceremony comes back, so an authenticator that did not verify the person is refused rather than quietly accepted. The other ceremony rows cannot be checked at all: nothing signed says what the browser was asked for, so a check would be a comparison against a value this service itself supplied. What it does instead is RECORD what came back — the attachment the browser reported, and the credProps answer about whether the credential is really discoverable.

Raising it does not change what a session claims. A passwordless sign-in still records amr ["hwk"] and acr "1" under required. RFC 8176 has no value for the authenticator verified the user that this service could honestly assert, and claiming mfa because the ceremony was phishing-resistant would be exactly the kind of fake this service refuses everywhere else.

What is done with the attestation statement is webauthn.attestationPolicy (#105). by-mode, the default, verifies every statement in product mode (verify-if-present: all eight WebAuthn Level 3 section 8 formats, the chain against webauthn.attestationTrustAnchors and the FIDO Metadata Service’s roots, revocation, and MDS status reports) and nothing in development (off, which product refuses to hold). require-trusted accepts only a statement that chains to an anchor, which refuses every synced passkey. An AAGUID allow-list (webauthn.attestationAllowedAaguids), a least certification level (webauthn.attestationMinCertificationLevel) and FIPS (webauthn.attestationRequireFips) each demand a trusted statement; a realm that demands one asks the browser for direct whatever webauthn.attestation says. webauthn.attestationAllowSafetynet and webauthn.attestationAndroidSoftwareKeys are weaker options, off, each with a warning in its description. direct is the conveyance default because this is a debugging service and the object is worth looking at; a deployment with no use for the authenticator’s model sends none.

webauthn.rpId may only WIDEN the RP ID, to a registrable domain suffix of the host this service was reached on — example.com at sts.example.com. That is WebAuthn’s own rule and browsers enforce it. This service enforces it too and refuses anything else BY NAME in the log, because a browser refuses it with a SecurityError that a ceremony reports as one of its several indistinguishable failures — so a wrong value here would look like a broken authenticator.

The four policy rows refuse an ENROLMENT and never an authentication. A key already on somebody’s entry goes on working when the role that produced it is switched off — the same contract the authentication policy’s TOTP row keeps, and with a sharper edge for primaryAllowed, where the person’s ONLY credential would be the one being switched off. Removing a key is on that person’s own row under /admin/users, or POST /admin-api/users/clear-key.

A second factor required of everybody, and security.passwordResetTtlMinutes

The authentication policy’s requireSecondFactor: always (Directory → Policies, if-held by default, per realm, inherited from the default realm; it was the authn.mfaRequired setting until #64) requires a second factor of everybody who signs in at the realm’s sign-in screen. Somebody who holds none is sent to /authn/mfa-setup after their password is accepted and chooses an authenticator app (the page shows the QR code and asks for a code) or a security key; no session exists until one is enrolled. A passwordless security-key sign-in is refused while it is on. An administrator can place the same requirement on one person with Require MFA on their /admin/users page, which writes stsMfaRequired on the entry.

The sign-in screen is the one door that can ask for it. In product mode the five doors that take a password and nothing else — an LDAP bind, a WS-Trust UsernameToken, SCIM, Shared Signals and EST Basic — refuse the person’s own password instead, answered as a wrong password, and accept an app password scoped to the door. A federated assertion, a SPNEGO ticket or a Kerberos AS-REQ, and a TLS client certificate authenticate somebody without that screen, and a session that already exists is not ended. If both mechanisms are switched off (the authentication policy’s TOTP row, and webauthn.enabled or webauthn.mfaAllowed), the screen refuses the sign-in and names those settings rather than silently not asking.

authn.passwordAloneDoors (empty, runtime, per realm; product only) lists the password-only doors — ldap, wstrust, scim, ssf, est — that still accept such a person’s own password. Every door listed lowers every such person to one factor there (NIST SP 800-63B section 4.2); prefer app passwords. appPasswords.enabled (on) lets people make app passwords on /portal/app-passwords and administrators make them on /admin/users and /admin-api; turning it off stops new ones and leaves the made ones working. appPasswords.maxPerPerson (10, 1–50) caps how many one person holds.

security.passwordResetTtlMinutes (60) is how long a reset link issued with Send a reset link on a person’s /admin/users page stays usable at /portal/reset-password. Issuing the link removes the current password and signs the person out everywhere, so an expired link leaves nothing to sign in with until an administrator issues another or resets the password.

oauth2.breakIdTokenNonce

Off. On, it puts a deliberately wrong nonce in every ID Token and logs that it did. It is not part of RFC 9700 mode and must not be folded into it — a compliance flag that also breaks tokens is a flag nobody will turn on. It exists because “the client must validate the nonce” is a requirement no server can check, and a reachable negative is the only way to find out whether a client does.

It works in development mode only (#104). A realm in product mode ignores it where the ID Token is built — a value still stored from before the realm was switched is logged once (STS-CORE-0106) — and refuses turning it on (STS-CORE-0103). The same marker (onlyWhile on the row in common/config.js) makes ssf.breakSetSignature, ssf.legacySubClaim, spiffe.acceptAssertedSelectors and spiffe.attestWorkloads off development only, and the four …SkipTlsVerification settings before them (#171). On oid4vp.requireStatusReference it governs one value only: off is development only, while own-only may be set in product (#165).

The four token lifetimes

All four are runtime settings, read per token, and they are drawn twice: with the rest of the oauth2.* rows on /admin/oauth2, and on a page of their own at /admin/token-lifetimes that puts them beside a count of what has already expired. Both write through the same function — one store, two doors.

Set one low and the next token dies on cue, which is the reason to point a client at a mock at all:

curl -s -X POST localhost:8081/admin-api/token-lifetimes/set \
  -H 'content-type: application/json' \
  -d '{"oauth2.accessTokenTtlS": 60}'

A change reaches the next token and nothing already issued. A lifetime is stamped into a token as its exp when it is signed; to take one already in a client’s hands out of circulation, revoke it at /oauth2/revoke or on /admin/tokens.

Every lifetime is a whole number of thirty-second units, and that is a decision rather than a formatting rule: below half a minute a token expires between the response being written and the client reading it, and the hour that costs goes on debugging the wrong half of the exchange.

oauth2.clockSkewS is not a lifetime. It is the allowance applied to exp and nbf wherever this service reads back a token it signed — introspection, UserInfo, the refresh grant, token exchange, the DPoP-bound access token check — and to the state every console screen reports, so the console and the endpoints never disagree about what has expired. It never changes what goes into a token. It is a different setting from oauth2.clientAssertionSkewS, which is how far out a client’s assertion may be (RFC 7523): one is somebody else’s clock, the other is this service’s own.

oauth2.refreshTokenTtlS is twenty-four hours, not thirty days. Set it to 2592000 for thirty. It is not oauth2.refreshIdleSeconds, which is RFC 9700 mode’s inactivity timeout on a refresh chain and is measured from the last redemption rather than from issuance.

saml.clockSkewS — the skew added to what is issued

The one setting here that changes what goes INTO an assertion’s validity window rather than how long that window is. saml.clockSkewS is added to BOTH ENDS of every assertion this service issues — NotBefore backdated, NotOnOrAfter extended — which is the answer to a service provider whose clock is a few seconds behind refusing a perfectly good assertion as not-yet-valid.

It is deliberately not oauth2.clockSkewS: that one is a TOLERANCE applied wherever this service reads a document back, including an inbound federation partner’s assertion, and a deployment wanting a strict reading and a forgiving issuance has to be able to say so. How LONG an assertion is valid is still per profile — saml2.assertionLifetimeMin and saml11.assertionLifetimeMin — because the two profiles are separate implementations consumed differently. All three are drawn together on /admin/saml-assertions, which is the only page where both lifetimes are visible at once.

Reading the current configuration

curl -s localhost:8081/admin-api/config | jq

Every row, with its value, where the value came from, its type, its prose, and whether it can be set at runtime — the whole table, whichever page edits it. It also carries homes: which console page draws each group. GET /admin/config?format=json answers the same whole table.

In the console each group is on the page for the protocol it configures — /admin/kerberos, /admin/ldap, /admin/saml2, /admin/scim, and so on. /admin/config holds the five settings that belong to no protocol — the bind address, the port, the scheme, the proxy header and the log level — and is otherwise the INDEX: every group, its size, what is overridden right now, and the page that draws it. Every one of those forms posts to the same endpoint, so there is one store however many pages draw the door. The console shows each setting’s effective value and which of the five levels it came from — the question it exists to answer, since the five are indistinguishable once a value has been read. The startup log line reports how many settings there are; that count is the one to trust.

At log level debug the service logs every endpoint call — path, request and response headers and bodies, status, elapsed time — and every assertion, JWT and SD-JWT VC both before and after signing or encryption, which is the point of a mock. The shipped appconfig files set info; STS_LOG_LEVEL=debug asks for the whole record.

Changing one at runtime

curl -s -X POST localhost:8081/admin-api/config/set \
  -H 'content-type: application/json' \
  -d '{"key":"groups.claimName","value":"roles"}'

A restart-only key comes back refused, naming the reason. So does a value that does not fit the setting’s type.

The change applies to the next token, assertion, ticket or search; nothing already issued changes, because a token is a signed document.

Whether it survives a restart is persistence.appconfig. In the default persistence.mode=memory it does not — the override is in memory and is gone with the process. With a store turned on it is written down and applied again at the next start, through the same setOverride() a caller uses, so nothing about the layering changes: it is still a runtime override sitting above the environment and the appconfig file, and a reset is written down too.

Nothing writes to the appconfig FILE in either mode, deliberately, because a service that edited a file checked into a repository would leave a test’s forgotten change behind permanently. The durable copy goes to the persistent store instead, which is not a place anything is checked in from. See the persistence settings below.

So the file is what a person EDITS and the store is what the console WRITES, and neither overwrites the other.

POST /admin-api/config/set-many changes a whole section at once and is all-or-nothing: every value is checked before any is written, so a body with one bad field changes nothing and names it — a section’s Save on the console cannot half-apply. POST /admin-api/config/reset puts one setting back and POST /admin-api/config/reset-all puts them all back, which is what a test should call to leave the service as it found it; in memory mode a restart does the same thing.

Per-application configuration

/admin/applications/new is where an application’s own answers are typed, and these settings can be answered there for one application rather than only service-wide:

They are also written with POST /admin-api/applications/set or an ldapmodify. Where one is set, that answer wins for that application alone, and the service-wide setting is the answer for every application that has not been given one of its own. An absent attribute means inherit — there is no third state — and a value that will not parse is ignored, logged and the setting used instead. The defaults live on /admin/token-lifetimes and /admin/saml-assertions, and each page names the attribute that overrides each row; GET /admin-api/saml-assertions lists which setting each SAML attribute overrides. The globals each protocol keeps — its issuer identity, its sockets, its clock skews — stay on that protocol’s own page.

oauthTokenExchangeRefreshToken is the one attribute REFUSED rather than merely inert on an entry of the wrong family — see One client at a time above. The rule is declared on the schema row itself (families: ['oauth2', 'oidc']) rather than written into either door, so a second attribute that needs it costs a member and nothing else. ldapmodify reaches the attribute either way, as it reaches every attribute here: the refusal is the difference between offering an operation and merely not preventing it.

The New Application form shows a field only when its protocol is ticked, so an OAuth client is not asked for a SAML entityID. That is done in CSS with :has() and no script; a browser without :has() shows every field, which the page says on itself.

An application declared for SAML 2.0 or SAML 1.1 gets a samlEntityId — its own identifier, if none was given — so its per-service-provider metadata at /saml2/metadata/{sp} and /saml11/metadata/{rp} is publishable the moment the entry exists.

The scopes a client may be issued are declared here too (#110). oauthAllowedScope is RFC 7591 section 2’s scope — a registration writes it and returns it — and is edited like any other list attribute, on the console and through /admin-api/applications/add and remove. This service’s own protected scopes (admin:read, admin:write, the SCIM and Shared Signals scopes, the debugger permission) are issued only to a client that lists them, in both modes, and /admin-api, SCIM and Shared Signals ask again on every call; in product every other scope is held to the list, or, where there is none, to the default set of OpenID Connect’s six and the realm’s OpenID4VCI scopes. oauthScope beside it is only what the client has asked for.

Behind an L4 load balancer — the PROXY protocol

Put this service behind a Network Load Balancer, not an Application Load Balancer, and pass TLS through. An L7 balancer terminates TLS, and every feature here that reads the client’s certificate — RFC 8705 tls_client_auth and certificate-bound tokens, GET /tls/sign-in, the XACML certificate gates, the SPIRE Server API — needs the handshake to happen on the node; no forwarded certificate header is believed, in any mode. An L7 balancer also cannot carry LDAP, LDAPS or Kerberos at all.

At L4 the node sees the balancer as every connection’s peer. global.proxyProtocol set to v2 is how the client’s address still arrives: the balancer writes a binary header at the front of each TCP connection, and this service takes it off before TLS, LDAP or the KDC read a byte. For an AWS Network Load Balancer:

• TCP listeners (not TLS listeners) for 443→8081, 389, 636 and 88, each forwarding to a TCP target group on the node’s port. A client certificate arrives on 443. The KDC’s UDP 88 cannot carry a header; put Kerberos clients on TCP.
• proxy_protocol_v2.enabled = true on every one of those target groups. AWS documents that health checks then carry the header too, with no client information in it — they are accepted, and keep the balancer’s address.
• preserve_client_ip.enabled = false (the default for IP targets, not for instance targets), so connections come from the balancer’s own private addresses, and global.trustedProxies set to the CIDRs of the subnets the balancer is in. With client IP preservation on, the peer is the client and every connection is refused as untrusted.
• global.publicBaseUrl set to the name clients use, as for any deployment.

A connection from an address outside global.trustedProxies is closed, not served — a node reachable around the balancer is a network fault, and closing it makes the balancer the only way in. A trusted address that sends no header is closed too (STS-PROXY-0002). The one exception is this host: loopback, or a peer on the node’s own address, is served plain, because the console’s and the portal’s OpenID Connect back channel and the Shared Signals push dial the main port on loopback without a header. common/proxy_protocol.ts argues each of these; the refusals are STS-PROXY-0001–0009 in Error codes.

Every setting

Generated from common/config.js’s table — the same rows the console renders and GET /admin-api/config answers, so this list cannot describe a setting this service does not have or miss one it does. The Group each setting belongs to is also the console page that draws it: the Kerberos rows are on /admin/kerberos, the SCIM rows on /admin/scim, and /admin/config lists the mapping for every group.

How to read it. The appconfig key is the dot path in the file, so oid4vci.batchSize is oid4vci: { batchSize: … }; logLevel is the one key that sits at the top level rather than in a section, because it was there before this table existed and moving it would have broken every config file for no gain. Every setting has an environment variable and it beats the file. Change while running says whether the console and POST /admin-api/config/set will take it: restart means the value was consumed before the service was listening — a bound socket, the TLS certificate’s names, the Kerberos principal database and its long-term keys, the directory tree’s root — and the reason is on the row. (derived) marks the four whose default is computed from a neighbouring setting rather than written in a file (see How a value is resolved).

The What it does column is the first sentence or two of the setting’s own description. The full paragraph — with the reasoning, which is usually the record of something having gone wrong once — is in common/config.js beside the row, and beside the input on whichever console page draws it.

Four things about these settings do not fit in a cell and have cost real time:

• OID4VCI_WALLET_URL is the base URL the BROWSER uses, not one this service fetches. The Credential Offer pages and the verifier’s request pages hand the End-User back by appending /vc-issuance-1.html or /vc-presentation-1.html to it (oid4vci.walletIssuancePath and oid4vp.walletPresentationPath), so its default of http://localhost:3000 is right only when the browser and the wallet share a host. Get it wrong and the hand-off lands on an unreachable origin — and because the URL still contains the wallet page, a urlContains wait passes and the failure looks like an unrelated timeout.
• KRB5_KDC_PORT is the TCP and UDP port. Both transports are bound to the same number on purpose: a client that fails over from UDP after KRB_ERR_RESPONSE_TOO_BIG retries at the address it already had.
• LDAPS_PORT is bound by a second server object, not by an option on the first — ldapjs decides between a net.Server and a tls.Server at construction — so 389 and 636 fail independently and GET /admin/ldap/service reports each separately. There is no StartTLS to turn on instead: it is an extended operation, ldapjs implements none, and this repository does not patch that submodule. And each trust realm’s naming context is DERIVED from its DNS domain — the default realm’s from STS_DOMAIN (global.domain), example.com being dc=example,dc=com — with ou=users, ou=groups, ou=applications and ou=spiffe derived beneath it rather than configured, because two variables that could disagree with it would put entries in a tree nobody is searching.
• There is no separate TLS or mutual-TLS port. A client certificate is presented to the main port, which asks every connection for one and requires none — a server that required one could not also be the port every other protocol arrives at. A certificate that does not verify is refused where it is USED: RFC 8705 client authentication, /xacml, /scim/v2, GET /tls/sign-in and a GNAP key proved by mutual TLS under gnap.mtlsTrust=pki. STS_TLS_PORT and STS_MTLS_PORT are not settings, and a deployment that sets one gets an “unknown setting” warning at startup.

Trust realms

Neither of the first two can be set ON a realm. A realm that could switch realms off would be doing it from inside the request that found it, and a realm that could move its own prefix would change the prefix already used to find it. They are refused at both ends.

Global

GNAP

The Grant Negotiation and Authorization Protocol (RFC 9635) and its resource server connections (RFC 9767), drawn on /admin/gnap. Every row is settable per trust realm. GNAP says what each one changes on the wire.

ACME

Automatic Certificate Management Environment (RFC 8555), drawn on /admin/acme. Every row is settable per trust realm. ACME says what each one changes on the wire.

EST

Enrollment over Secure Transport (RFC 7030), drawn on /admin/est. Every row is settable per trust realm. EST says what each one changes on the wire.

SCEP

The Simple Certificate Enrolment Protocol (RFC 8894), drawn on /admin/scep. Every row is settable per trust realm. SCEP says what each one changes on the wire.

Web security

Sessions, the sign-in clocks, this service’s own OpenID Connect client, and passwords.

OAuth 2.0 / OIDC

Admin console

There is no setting that opens this console. Every page and every form under /admin needs a browser sign-on session and one of the two roles below, in BOTH modes, and mode.gatesConsole() is the one place that is decided. What the mode changes is whether the password typed at that screen is CHECKED — in development it is not, so the gate is a turnstile proving somebody typed a name that holds a role.

Protocol debugger

There is no setting that opens the debugger either. Every request to it needs an access token carrying urn:sts:debugger-api:debugger, which the authorization server issues to members of the two console role groups and leaves off for anybody else. These rows decide whether it is served, where, and what its api may dial.

Applications

Federation

SAML

SAML 2.0

These are their own group and saml.issuer above is deliberately not one of them: that setting names whoever SIGNED an assertion and is shared with WS-Trust and WS-Federation, while every row here governs how this service behaves as an identity provider in a browser profile.

SAML 1.1

These nine are a group of their own for the reason the SAML 2.0 nine are, and for one more besides. The shared reason: saml.issuer above names whoever SIGNED an assertion and is read by WS-Trust and WS-Federation, while every row here governs how this service behaves as an identity provider in a browser profile. The reason peculiar to this group: SAML 1.1 and SAML 2.0 are different specifications rather than two dialects, and a shared set of rows would make signResponse mean two things — over there it is an XML signature or a signed query string depending on the binding, and here there is no redirect binding for a response at all. A relying party that trusts this service for 1.1 and not for 2.0 is also the ordinary case, and one entityId between them would make that unexpressible.

WS-Trust

WS-Federation

TLS

OID4VCI

OID4VP

Kerberos

LDAP

SCIM

There is no setting that opens SCIM. Every endpoint under /scim/v2 requires a credential in BOTH modes — one of RFC 7644 section 2’s six schemes, with the OAuth ones needing scim:read or scim:write — because those endpoints create and DELETE accounts. global.mode decides whether the credential is CHECKED; mode.gatesScim() is the one place the gate is decided.

Roles

Who holds a role, and what requires one. A role is not a group: a group here grants nothing, and holding a role is what an ISSUANCE is decided on. It is also not the two Admin console roles, which are directory groups granting /admin and nothing else. Both halves of a role — who holds one, and which roles an application demands — are edited on /admin/roles and on the application’s own page rather than in a setting.

TOTP MFA

RFC 6238 one-time passwords — the second factor a person enrols from /portal/mfa or while spending an activation link, and the only credential this service checks besides a Kerberos ticket. Drawn on /admin/totp, under Protocols.

Which of these affect only NEW enrolments, why totp.window applies to everybody, why totp.algorithm should stay SHA1, and why switching TOTP off in the authentication policy leaves existing enrolments in place are under The TOTP settings above.

Backup codes

Recovery codes — the way back in when the second factor is not to hand. Drawn on /admin/backup-codes, under Protocols.

This is the only mechanism on that console that no specification defines. Everything else here implements somebody’s document and can be checked against it; there is no RFC for a recovery code. What every identity provider does converges anyway — a handful of random strings, each accepted once — so the decisions that are left are this service’s own, and common/backup_codes.ts argues each of them.

How a person generates a set, why it is shown once and stored hashed, and why none of these rows invalidates an existing set are under The recovery code settings above. Two more things do not fit in a cell.

• THE ALPHABET IS THE BASE32 CHARACTERS AND IS NOT SHARED WITH totp.*. That one is base32 because the otpauth URI says so — an interoperability requirement. This one is the same thirty-two characters because none of them is confusable with another: no 0 beside O, no 1 beside I. A recovery code is the one credential here that somebody writes on paper and types back months later.
• A CODE IS NEVER A FIRST FACTOR AND NEVER THE FACTOR A SIGN-IN ASKS FOR. The screen asks for whichever mechanism the person is CONFIGURED for, and /authn/backup-code is reachable only as a link out of one of those two screens. Holding a set does not make a second factor required of anybody.

WebAuthn

Security keys — W3C WebAuthn Level 3 over FIDO CTAP2 — as a second factor OR as the only credential on an account. Drawn on /admin/webauthn, under Protocols.

What a browser does with navigator.credentials.create() is decided almost entirely by the options the relying party hands it, so these rows are how a client author asks this service for a ceremony of a particular shape — with attestation: "none", say, or a discoverable credential.

Which of these is enforced and which are only requests to the browser, why the four policy rows refuse an enrolment and never an authentication, and how far the RP ID may be widened are under The WebAuthn settings above.

Group claim

Audit log

Delegation

SPIFFE

There is no setting that opens the SPIRE Server API. Its TCP port is bound as mutual TLS, always, because what comes out of that surface is a credential another service will believe. Every method is authorized against SPIRE’s own per-method table, which GET /spiffe publishes in full. The Workload API is deliberately not on that list and must never be: its specification says it MUST NOT authenticate a caller, because a workload has no root of trust until that call gives it one. What it lacks there is ATTESTATION, not authentication, and no mode changes it.