Security in product mode
Product mode (global.mode=product) turns on the controls described here. They
line up with OWASP ASVS 5.0.0
Level 2, which includes Level 1. Development mode leaves most of them off so that clients can be
exercised against behaviour a production service would refuse.
/admin/mode shows what each mode does in the running service, and shows a row
as not met when a setting on this page weakens it. Read that page to see the
state of your own deployment.
Before people use a product deployment
- Give the main port a publicly trusted certificate. Set
tls.certificateFileandtls.keyFile. Browsers remember HSTS for a year, and then refuse an untrusted certificate with no way to click through. See TLS. - Find the administrator’s name and password at first start. Unless you
set
admin.bootstrapUsernameto a name of your own, the name is generated. Both are written tobootstrap-admin-passwordinpersistence.dataDir, readable only by the service, and the log says where. See The admin console. - Check that your clients can use the defaults. The settings below turn older behaviour back on where a client cannot manage without it.
Settings that weaken a default
Each of these is off by default, and each one moves the deployment away from Level 2. Turn one on only for the clients that need it.
| Setting | What turning it on allows | Who needs it |
|---|---|---|
krb5.allowSha1Enctypes |
Kerberos enctypes 17 and 18 (AES with HMAC-SHA1-96) | Kerberos clients that speak nothing newer |
scep.allowInProduct |
SCEP, which requires RSAES-PKCS1-v1.5 and AES-CBC | Devices that can only enroll over SCEP |
ldap.plainListener |
The plain LDAP listener on 389, where a password can cross in the clear even though the bind is refused | Directory clients that cannot use LDAPS on 636 |
federation.allowAssertionWithoutAudience |
A partner’s SAML 1.1 or WS-Federation assertion that names no audience | A partner that cannot send one |
oauth2.allowUndeclaredGrants |
Any grant for a client that lists none | Test stacks |
admin.allowDefaultUsername |
A bootstrap administrator named admin, root, sa or administrator |
Test stacks |
security.fileRoots |
Where a file an administrator names may be read from. Set only in the environment or appconfig file | Add the directory your certificates and tokens are mounted in |
security.allowUnscopedPeople |
Any authenticated person at SCIM and Shared Signals, by a scheme with no scope | Test stacks; use OAuth scopes for real provisioning clients |
authn.allowOptionalSecondFactor |
Signing in without a second factor where the authentication policy allows it | A deployment that accepts ASVS 6.3.3 not being met |
oauth2.allowConfidentialWithoutPkce |
A confidential client omitting PKCE | A client that cannot send it |
federation.allowUntypedLogoutToken |
A partner’s Logout Token typed jwt or carrying no type |
A partner that does not send logout+jwt |
admin.logBootstrapPassword |
The generated first administrator password in the service log | Never outside a test stack |
crypto.allowCbcJwe |
JWE’s CBC-HMAC content encryption | A partner that cannot read AES-GCM |
crypto.allowLegacyHashes |
OAEP over SHA-1 in XML encryption and JWE, the SHA-1 PKINIT key derivation, and S4U2Self’s HMAC-MD5 checksum | Partners and Kerberos clients that support nothing newer |
persistence.allowDefaultDatabasePassword |
Starting with a well-known database password, such as sts, sts_app or postgres, or one equal to the user name |
Test stacks |
audit.allowPlainSyslog |
A syslog audit destination over tcp or udp |
A collector on a network you trust that cannot accept TLS |
secrets.allowLocalSecrets |
A key-encryption key in a file, or a database password in a file or the connection string | A host whose only secret store is its own file system |
security.pbes2MinIterations |
Set below 600000, a password-encrypted JWE (PBES2) with fewer PBKDF2 iterations | A sender whose library uses a smaller count |
malwareScan.allowCleartext |
A plain icap:// malware scanner |
A scanner on a network you trust |
Two settings are on by default in product mode, and turning one off weakens it in the same way:
| Setting | Off means |
|---|---|
security.hstsIncludeSubDomains |
HSTS stops covering subdomains of the service’s host name |
security.requestsPerAddressPerMinute |
Set to 0, no ceiling on requests from one address (6000 a minute by default) |
Two switches exist to recover from a bad policy, and /admin/mode shows either
one when it is off:
| Setting | Off means |
|---|---|
xacml.enforceAccess |
The admin console, management API, portal, SCIM and SPIRE Server API stop asking the policy decision point |
roles.enforceIssuance |
Issuance stops checking roles |
Use them only to get back in after a policy has locked you out, and turn them back on afterwards.
Two more have a stricter default in product mode, and setting them back to the
development value weakens it: oauth2.refreshTokenMaxChainS (30 days; 0 is no
limit), oauth2.consentAlwaysForPublicClients (on), and the three
single sign-on consent switches saml2.ssoConsent, saml11.ssoConsent and
wsfed.ssoConsent (on).
Connections and browsers
- HTTPS. The main port is HTTPS, and a process with
global.httpsoff does not start. The plain-HTTP revocation and SCEP listener stays, because RFC 5280, RFC 5019 and RFC 8894 expect those services over HTTP. - HSTS. Every response over TLS carries
Strict-Transport-Security: max-age=31536000; includeSubDomains. Turn offsecurity.hstsIncludeSubDomainsif a subdomain of the host name must still answer over plain HTTP. See TLS. - Forwarded addresses. With
global.trustProxyon,X-Forwarded-For,X-Forwarded-ProtoandX-Forwarded-Hostare believed only from the proxies listed inglobal.trustedProxies. With no list, they are believed from nobody, so behind a proxy set both. See TLS. - Outbound requests. A request a partner, client or caller can influence
never reaches a loopback, private, link-local or reserved address. Set
security.outboundAllowedHoststo limit it to named hosts as well. See Communications. - Requests per address. One address may make 6000 requests a minute to one
process,
security.requestsPerAddressPerMinute. More are answered429. See Availability. - Cookie names. Over TLS, every cookie this service sets is prefixed:
__Host-, or__Secure-when it carries aDomain(seeauthn.cookieDomain) or a path narrower than/.sts_sessionarrives in a browser as__Host-sts_session, for example. An unprefixed cookie of the same name is ignored, so a client that reads or sends a cookie by name must use the prefixed one. - Character sets. Text and XML responses name
charset=utf-8.
Certificates
- Paranoid PKI mode is on.
pki.paranoidisauto, which is on in product mode: every certificate this service relies on, at a TLS handshake in either direction, under a signature, as an encryption recipient or in an attestation, needs a path to an anchor it was told about, validity now, revocation where a source is named, and the key usages its use case asks. See Paranoid PKI mode. - A partner’s CA goes in a truststore. A third party’s certificate that is not registered on the application or relationship it is used for must chain to an anchor this service holds: the client-certificate truststore at a TLS handshake, and the realm’s signer truststore for everything else. A server this service dials that presents a self-signed certificate is refused until it is accepted by name.
- One row per use case. If one kind of certificate cannot meet the checks,
turn off that use case’s
pki.paranoid<UseCase>row in the realm that needs it, not the whole mode. A row off in product is logged (STS-PKI-0239) and drawn red on/admin/pki/trust, which also lists every pinned certificate and its status. - A revoked certificate is never re-issued. Renewing, reissuing or importing an Issuing CA re-issues only the certificates that are still valid; a revoked or expired one keeps its serial and its revocation entry. Importing an Issuing CA puts the one it replaces on its Intermediate’s list. After replacing the Root, remove the old Root from every trust store: nothing can sign a revocation list for the old tree any more. See Editing it.
Passwords
- Any composition is accepted. A policy can set a minimum length and a history, but it cannot require symbols, upper-case letters or numbers.
- Words that identify you are refused: the service’s names, the realm’s name
and domain, and
security.passwordContextWords. See Words a password may not contain. - A generated password is temporary. One made by
reset-password, byset-passwordwithgenerate: true, or when a person is created, must be changed at the next sign-in, and Kerberos gives no ticket for it until it is. One an administrator types does not. - A password is changed where the current one is proved. A person cannot
replace their own
userPasswordover LDAP unless an operator adds it toldap.selfWritableAttributes, which would weaken this. - Stored passwords. A new password is scrypt at N=2^15, r=8, p=3 by default, one of OWASP’s pairs, in both modes. A pair below that table is refused, and one that reaches the writer another way is raised to the table. A stored hash keeps verifying. One in another algorithm, or in the same algorithm at a strictly lower cost, is hashed again at the person’s next successful sign-in. A same-algorithm hash already at least that cost is left. See How a password is stored.
- Repeated guesses are slowed, and no account is locked. See Authentication.
Signing in
- Second factor. Required of everybody who signs in with a browser,
administrators included, including with a certificate:
GET /tls/sign-instarts no session for a person who owes one, and the sign-in screen’s certificate button asks for it. A federation partner is the authentication, so federated sign-ins are not asked for one, and nor are programs that present a client certificate. The password-only doors (LDAP, WS-Trust, SCIM, Shared Signals and EST Basic) cannot ask for one, so a person uses an app password there, with no second factor. This is intentional: see Authentication and Authentication pathways. - A TOTP code is good for one time step.
totp.windowdefaults to 0. - Changing how somebody signs in needs a recent sign-in, within
account.recentAuthMinutes(15 minutes). On the portal that covers the second factors, recovery codes, passkeys, app passwords, certificates, signing keys, self-issued IDs, the email address and a wallet credential offer; the person is sent to sign in again and returned to the page. An administrator changing a person’s password, second factor, passkey, recovery codes, email address or app passwords, exporting or importing a person, or deleting one, through the console or/admin-apimust have signed in within the same time: the console asks them to sign in again and carries on, and the API answers RFC 9470’sinsufficient_user_authentication. A program using the API with its own credentials is not asked. - Clearing a lost factor needs a reason. An administrator removing a person’s authenticator app, passkeys, recovery codes or emailed factor must say how the person’s identity was verified. It is kept on the audit row.
Sessions
- An unused session ends after 30 minutes (
authn.sessionIdleTimeoutS), and every session after one hour (authn.sessionLifetimeS). - Ending a session revokes the access tokens issued on it, and its refresh
tokens other than
offline_accessones, and tells the browser to clear this site’s storage when no other account remains in it. Sessions says what cannot be recalled. - Ending your other sessions needs a recent sign-in; signing yourself out never does. See Signing out.
- An administrator can end every session in a realm at once, on
/admin/sessions. See Sessions.
Browser pages
Every page in the console, the portal, the report application and the sign-in screens is drawn through one renderer. It removes scripts, event handlers and unsafe addresses from the markup before it reaches the page, on top of each page’s Content Security Policy.
An unexpected failure is answered without its internal error text: at the management API, the OAuth and OpenID Connect endpoints (the sign-out page included), WS-Trust and the wallet sign-in. The text is in the log, under the failure’s error code.
Secrets in addresses
- The admin console, portal and report application receive their authorization
code in the URL fragment, which a browser does not send to any server. Other
registered clients may still use
response_mode=query, the OAuth 2.0 default. - Emailed links carry their token in the fragment too. A portal page sends it in
the
X-Link-Tokenheader, and the APIs refuse one in a query string. - A sign-in, password-change or consent step’s id travels in the URL fragment
and an
X-Step-Idheader, not in anything a server logs. Only the browser that first asked about a step can use it. - Two hops have no script to read a fragment: the SPNEGO exchange (RFC 4559)
and the start of a federated sign-in. Their step id travels in a short-lived
HttpOnlycookie instead, and the wallet’s return and wait addresses carry it in the fragment.
Access decisions
A decision the policy engine cannot make is a refusal: an error in the engine, an empty answer, or a check that names no resource or action. In development mode the same faults allow the request and are logged.
Issuing is held to the same rule. When the issuance decision cannot be made (the
engine throws or answers nothing), or the application register cannot be read
to judge a sign-in, no token is issued (STS-XACML-0183).
An administrator’s admin:read is permission to read every object in that
realm: a realm is the boundary between tenants. A realm’s own token is refused
at any other realm’s /admin-api; a default-realm token is the service’s and
reaches every realm. See Management API.
At SCIM and Shared Signals, a scheme that carries no scope (HTTP Basic, the session cookie) needs Admin Read to read and Admin Write to write.
Clients and grants
- A client gets only the code flow unless it declares more. One that declares
no grant types may use
authorization_codeandrefresh_tokenalone, and one that declares no response types (and not theimplicitgrant) may useresponse_type=codealone (unauthorized_client). List what else it needs inoauthGrantTypeandoauthResponseType. See Configuring OpenID Connect flows. - PKCE is required of every client, confidential ones included. An
authorization request with no
code_challengeis refusedinvalid_request. - A repeated parameter is refused at the authorization and token endpoints (RFC 6749 section 3.2), rather than the last value being taken.
- A public client is asked consent every time. Nothing proves which program
holds a public client’s
client_id, so an earlier answer does not cover it. This service’s own applications are not asked. See Consent. - Single sign-on asks before it signs a person in to a SAML 2.0 service
provider, a SAML 1.1 relying party or a WS-Federation relying party, once
per application, on the same consent screen (ASVS 5.0.0 7.6.2).
saml2.ssoConsent,saml11.ssoConsentandwsfed.ssoConsentturn it off, andsaml2SsoConsent,saml11SsoConsentandwsfedSsoConsenton an application’s entry turn it off or on for that application.
Tokens
- A chain of refresh tokens ends 30 days after its first token, however often it was renewed; the person then signs in again.
- A token whose
subno longer names a person is refused at/account-apiand/report-api(invalid_token), and holds no role at/admin-api, SCIM or any other door that asks a token’s roles. It is not matched by its username, which may now belong to somebody else. In every mode these doors find the person bysubfirst. - A partner’s Logout Token must be typed
logout+jwtunlessfederation.allowUntypedLogoutTokenis on. - A GNAP user assertion that has expired is refused unless an operator sets
gnap.assertionMaxAgeS.
Algorithms
- Kerberos uses enctypes 19 and 20 (RFC 8009).
- RSA keys this service generates are 3072 bits by default: RSA signing keys, certificate authorities, the self-signed listener certificate and the realms’ encryption keys. A setting that names a size still decides, and keys that already exist stay until they are rotated.
- Hashes. SHA-1 and MD5 are off for key transport, PKINIT key derivation and
S4U2Self unless
crypto.allowLegacyHashesis on. Two uses remain. TOTP defaults to HMAC-SHA-1 for compatibility with authenticator apps, many of which support nothing else. PKINIT checks the SHA-1paChecksumbecause RFC 4556 section 3.2.1 requires it and RFC 8636 section 9 leaves it fixed at SHA-1; the request’s security rests on a signature digest that is not SHA-1, a Diffie-Hellman reply key, and RFC 8636’s KDF over SHA-256 or better, which binds the request to the reply. - JWE offers and accepts AES-GCM only, and answers in A256GCM when a client
names an algorithm and no
enc, unlesscrypto.allowCbcJweis on. Kerberos (RFC 8009) and the TPM credential step use the only ciphers their specifications define. - XML encryption selects and accepts AES-GCM only. AES-CBC is refused when
decrypting, and cannot be chosen in
saml2.encryptionAlgorithm. - secp256k1. ES256K is not offered in discovery, its key is not in
/oauth2/jwks, and signing with it is refused (STS-KEYS-0166), unlesskeys.signingAlgorithmslists it. A signature in it from anybody else, a DPoP proof among them, is refused (STS-KEYS-0179) unlesskeys.acceptedSigningAlgorithmsorkeys.signingAlgorithmslists it, and the published*_alg_values_supportedlists leave it out. An XML signature on secp256k1 follows the same rule (STS-KEYS-0077), and a COSE one is accepted only wherecose.acceptedAlgorithmslists ES256K. See OAuth and OpenID Connect. - PBES2. A JWE whose
p2cis undersecurity.pbes2MinIterationsis refused before anything is derived: 600,000 in product mode, RFC 7518’s recommended 1000 in development. The key is derived on libuv’s thread pool, never on the event loop. A PKCS#12 export uses PBKDF2 with SHA-256 at 600,000 iterations, and so does a password-protected JWK export (a PBES2 JWE withp2c600,000), in either mode. - SCEP answers 503 until
scep.allowInProductis on. See SCEP.
Uploaded files
Malware scanning of uploaded images and risk datasets is optional and off by default. When it is on, product mode reaches the scanner over TLS only. See Malware scanning and File uploads.
Errors and logs
- An internal error’s text stays in the log. A WS-Trust fault, the JWKS
endpoint, a
500from/admin-apiand the OpenID Connect logout error page answer with a general message. - Request logs leave credentials out. At
debugandtrace, the logged request and response headers loseAuthorization,Cookie,Set-Cookie,DPoPandX-API-Key, and bodies are withheld. Tokens and assertions are still written before and after signing, so keep toinfoon a deployment with real data. See Logging inventory. - Audit log. Configure an audit export destination, so that
a copy of the log leaves this service as it is written and a compromise here
cannot alter it. Syslog destinations use TLS unless
audit.allowPlainSyslogis on. Each held row also carries a keyed checksum and the checksum of the row before it:GET /admin-api/audit/integritylists any row that no longer matches, any place a row is missing, and whether the newest rows are there. - Clocks. With a database store, a node whose clock differs from the
database’s by more than five seconds logs a warning (
STS-SCHED-0022), and a line when they agree again.
Dependencies
SECURITY.md sets how
quickly a vulnerable dependency is fixed and how to report a vulnerability. Images
install exactly what the lockfiles name, and a daily check covers the published
image as well as the lockfiles.
The image holds a CycloneDX inventory of its npm dependencies at
/usr/src/sts/sbom.cdx.json, one of the optional SDKs under /opt/sts-sdk at
/usr/src/sts/sbom-sdks.cdx.json, and a list of its operating-system packages
at /usr/src/sts/os-packages.txt. It holds no source control metadata.
Database
Product mode does not start with a well-known database password (sts,
sts_app, postgres and the like) or one equal to the user name, unless
persistence.allowDefaultDatabasePassword is on. The compose stack generates its
passwords at first start. See The compose stack.
Product mode also takes the database password from a secret store, and the
key-encryption key from a secret store or a key management service. A password
written into the connection string, the file provider, or a key-encryption key
in a file stops the service unless secrets.allowLocalSecrets is on. The compose
stack uses OpenBao for both. See Key management.
Related
- What is not checked, in development mode
- Input validation
- Departures from the specifications
- Security profiles