Release notes
1.1.0
1.1.0 upgrades a deployment that is already running 1.0.0. Keep the database volume. The 1.0.0 service can keep answering while the database is upgraded. Start the 1.1.0 image after the upgrade script exits 0.
A store that is only in memory has nothing to upgrade. A database whose schema version is below 31 is a pre-release build, and the script refuses it. Those builds are covered under Not backwards compatible with earlier builds.
PostgreSQL
Release 1.0.0’s database is schema version 31. 1.1.0 adds two indexes on
sts_sessions and records schema version 32 beside it:
sts_sessions_started, so the console’s session pages can list sessions newest first without sorting the whole table.sts_sessions_subject_band, used by the per-subject session sweep.
The script also stores xacml.pepAuthentication = either in every realm
that has a registered remote PEP and no value of its own, so PEPs that
authenticate by client certificate keep working on 1.1.0’s new default,
token (The remote PEP authenticates with its key).
It prints what it stored. That step needs the directory and the settings
in the same database; in a cell or tier database that lacks either, it
writes nothing and says so.
Run the script as the table owner, from a checkout of 1.1.0. On the
compose stack the owner is sts. The application role sts_app cannot
create an index.
docker compose exec -T postgres \
psql -U sts -d sts -v ON_ERROR_STOP=1 \
-f - < postgres/upgrade-1.0.0.sql
Against a database you reach directly:
psql -v ON_ERROR_STOP=1 -f postgres/upgrade-1.0.0.sql \
"postgres://owner@host:5432/sts"
Do not pass --single-transaction. The indexes are built with
CREATE INDEX CONCURRENTLY, which PostgreSQL refuses inside a
transaction. For a large sts_sessions table,
-v sts_maintenance_work_mem=1GB gives this session more memory for the
build and does not change the server. -v sts_schema=sts selects the
schema and is the default.
Then start the 1.1.0 image. If it starts before the script has run, it still starts and answers every request; the session pages and the per-person session sweep are slower until the indexes exist:
- As the application role (
sts_app, the normal case), which cannot create an index, it logsSTS-STORE-0172once, naming the two indexes and this script. Run the script; nothing needs restarting afterwards. - As a role that owns
sts_sessions, it builds the missing indexes itself, in the background, withCREATE INDEX CONCURRENTLY, without holding up writes or its own start. A build that fails logsSTS-STORE-0173and is tried again at the next start.
Replacing the image before the script does not damage the volume.
Leave the volume in place. docker compose down -v deletes the
directory, the realm registry and the setting overrides, and in product
mode the sealed signing keys and everything minted under them.
Do not run postgres/schema.sql again for this upgrade. On a 1.0.0
database that script rebuilds sts_ldap_entries_asked_names, which
version 31 already has, and sets the application role’s password again.
postgres/upgrade-1.0.0.sql does neither.
A second run finds the indexes already valid and changes nothing else. If the script stops because an index of one of those names has the wrong definition, drop that index and run the script again. An index left invalid by an interrupted build is dropped and built again by the script.
Returning to the 1.0.0 image ignores both indexes. Leave them.
PostgreSQL schema records what version 32 adds.
MariaDB
MariaDB is the second engine.
Its upgrade adds sts_sessions_started, records schema version 32, and
stores xacml.pepAuthentication = either in each realm with a registered
remote PEP, as the PostgreSQL script does.
sts_sessions_subject_band is PostgreSQL only. The build does not block
writers. Run it as an account that can ALTER the table,
in the service’s database, and pass --abort-source-on-error:
mariadb --abort-source-on-error -u root -p sts \
< mariadb/upgrade-1.0.0.sql
sts is that database’s name. Use the name from the connection string
when it differs (sts_store in the MariaDB example). The same cautions
apply: leave the database in place, and do not run mariadb/schema.sql
again, which sets the application account’s password on every run. A
second run inserts nothing. A valid index of the wrong shape is left as
it is; drop it and run the script again, then start the 1.1.0 image.
A 1.1.0 image started first still starts: an account that may not alter
the table logs STS-STORE-0172, and one that may builds the index in
place in the background (STS-STORE-0173 if that fails).
Behaviour changes: a deleted object leaves nothing behind
1.1.0 makes a delete complete. An application, person or group created again under a deleted one’s identifier, username or DN inherits nothing from it. Each of these changes what 1.0.0 did:
- Over LDAP, a group may not list a member that does not exist. An
add or modify that names a
member,uniqueMemberormemberUidwith no entry behind it is refused with result code 19 (constraintViolation). 1.0.0 accepted it. A script that adds a group’s members before their entries must create the entries first. A dangling member that a 1.0.0 directory already holds is kept, and the console still reports it. - A delete takes the deleted entry’s references with it. A deleted person, group or application is taken out of every group that listed it and every role it was a member of. A deleted application no longer confers any role, and a deleted person or group is no longer an owner of any role, group, application or service account. 1.0.0 left these references in place, so whatever was next created under the same name or DN got them. Each removal is written to the audit log.
- Deleting an application deletes the roles it owns. A role made for
one application (
<role>@<application>, itsroleApplicationnaming that application) is deleted with it, as the console’s Delete role deletes one, with aroles.deleteaudit row for each. Its members and permissions go with it. A role owned by another application, and a realm-wide role, are not touched. In 1.0.0 these roles stayed, and an application registered again under the same identifier found them waiting, members included. If you still need such a role, create it again once the new application exists.
None of these changes the stored data or needs a migration step. They
apply to deletes made after the 1.1.0 image starts. References a 1.0.0
service left behind before the upgrade stay until you remove them on the
console or through /admin-api.
Behaviour changes: a service account is for good
1.1.0 holds three rules about service accounts
at every door: the console, /admin-api and an LDAP modify. Each changes
what 1.0.0 did:
- A service account cannot be made an ordinary person again.
POST /admin-api/users/set-service-accountwithserviceAccount: falseon a service account is answered 400 (STS-SVCACCT-0060), and an LDAP modify that deletes or replacesstsServiceAccountis refused with result code 19 (STS-SVCACCT-0064). 1.0.0 cleared the flag, the owners, the destination and the rotation state. The console’s Make them an ordinary person button is gone, and its Make them a service account button now asks you to confirm that it cannot be undone. Deleting the entry is still allowed. - A service account that has an owner always keeps one, whatever the
policy’s
requireOwnersays. Removing the last owner, sendingowners: [], or an LDAP modify deleting the laststsServiceAccountOwneris refused (STS-SVCACCT-0061,STS-SVCACCT-0065). In 1.0.0 this was allowed whilerequireOwnerwas off. An account made with no owner underrequireOwneroff can still be edited without naming one. - An owner cannot remove themselves. Taking your own DN off an
account’s owners, or the group that is your only way of owning it, is
refused (
STS-SVCACCT-0062,STS-SVCACCT-0063; over LDAP, for the bound DN,STS-SVCACCT-0066,STS-SVCACCT-0067). Another administrator may remove you. - Deleting an account’s last owner makes the realm’s administrator the
owner. When the person or group that is a service account’s only owner
is deleted (SCIM
DELETE, an LDAP delete), the realm’s Admin Write group becomes its owner, or the realm’s bootstrap administrator if there is no such group. Anadmin.service-account.owner-addedrow bysystemsays so. In 1.0.0 the account was left with no owner. If the realm has neither, it still is, andSTS-SVCACCT-0068is logged.
Existing service accounts are unchanged, and nothing needs a migration step. A script that un-made a service account, or emptied its owners, gets the refusal instead.
AuthZEN ignores members it does not define
In 1.0.0, an AuthZEN request carrying a member that AuthZEN
1.0 does not define was refused with 400. In 1.1.0 it is accepted, and the
member is ignored, as AuthZEN 1.0 section 10.1.1 requires (“receivers MUST
ignore unknown fields”). This covers every request under /access/v1:
an evaluation, an evaluations batch, the three searches and an access
request. It applies at the top level and inside subject, action,
resource, page and options. An Action Search’s action, which the
search does not define, is ignored too.
Nothing else about a request changes. A defined member is still checked
for type and presence. A property inside properties or context still
needs a conversion rule. BULK’s items on an access request is still
refused. A request that worked in 1.0.0 gets the same answer.
STS-AUTHZEN-0009 is retired. Other APIs still refuse members they do not
declare. The remote PEP’s AuthZEN endpoint in the xacml-pep container
follows the same rule.
AuthZEN requires Content-Type: application/json
AuthZEN 1.0 section 10.1 says a request MUST carry Content-Type:
application/json. In 1.0.0 the evaluation, the evaluations batch and the
three searches read any body as JSON, whatever it was labelled. In 1.1.0
a request labelled anything else, or not labelled at all, is answered
415 Unsupported Media Type (STS-AUTHZEN-0117) once the caller is
admitted. A charset parameter is accepted. A caller that sent JSON as
text/plain, or with no Content-Type, has to send the header. The
remote PEP’s AuthZEN endpoint is unchanged.
An AuthZEN resource search names the policy’s resource ids
In 1.0.0 a Resource Search for a resource type
this service has no objects of (anything but application, api and
delegation) answered no results, whatever the policy permitted. In
1.1.0 its candidates are the resource ids the realm’s policies compare
resource-id with, and each is a result only where the policy permits
it as that type. Section 8.5 asks for every resource of the type the
subject may act on. The three types this service has objects of answer as
before.
Policies can be exported and imported, whole or one at a time
New in 1.1.0: Directory → Policies has an Export and import tab, and
/admin-api has POST /admin-api/policies/transfer/export, inspect and
import with GET /admin-api/policies/transfer beside them. An export is a
JSON document signed under the realm’s new Policy Export Signing CA, with the
signer’s whole chain inside it. An import from another realm asks whether to
trust that realm’s signer first. An export may carry every policy the realm
stores or only the ones named, each by its kind and name, and every stored
policy has an Export button of its own. An import may write every policy in
the document or only the ones ticked. Policies
has the details.
A federated OpenID Provider may leave out its issuer
This applies to a federation relationship that finds its OpenID Provider
through an OpenID Federation Trust Anchor
(fedTrustAnchor). In 1.0.0, the sign-in was refused with STS-FED-0149
when the provider’s resolved openid_provider metadata had no issuer.
In 1.1.0 an absent issuer is read as the provider’s Entity Identifier.
OpenID Federation for OpenID Connect 1.1 section 5.1.2 allows no other
value. An issuer that is present and names another entity is still
refused. The ID Token’s iss is still checked against the Entity
Identifier. Nothing this service publishes changes.
New: export and import a person as LDIF
A person’s page under Directory → Users has an Import / export tab,
the one an application’s page has had since 1.0.0. Export saves the
person as an LDIF file of one record: the attributes a create takes, and,
only when its box is ticked, their credentials unencrypted (the
password as its stored hash, the authenticator app, passkeys, recovery
codes, app passwords and stored certificates). Import creates a person
from such a file in the realm the console is in, and never overwrites one
who is already there. Both need Admin Write and a recent sign-in. The API
is POST /admin-api/users/export-ldif and /import-ldif; see
Exporting and importing a person as LDIF.
Nothing that existed in 1.0.0 changes.
An ISO mdoc is issued
The issuer offers IdentityCredentialMdoc (mso_mdoc). It is signed with
COSE ES256 (-7) or ESP256 (-9) by a document signer that chains to an
ECDSA Issuing Authority CA this realm mints on first use
(GET /oid4vci/mdoc-iaca, and GET /admin-api/mdoc-iaca). The credential
names GET /oid4vci/status-lists/mdoc. A wallet sign-in accepts an mdoc
only when this realm issued it. The Digital Credentials API still does not
carry one, and the Mobile Security Object is not signed with a post-quantum
algorithm.
The verifier’s default document type and namespace are now the type this
realm issues (urn:iya:sts:mdoc:identity, urn:iya:sts:mdoc), not the
mobile driving licence. A deployment that asked for
org.iso.18013.5.1.mDL sets oid4vp.expectedDoctype and
oid4vp.mdocNamespace.
bbs-2023 is the W3C cryptosuite
Until 1.1.0 an ldp_vc this service issued was labelled bbs-2023 but
used a private format: no W3C bbs-2023 implementation could verify it, and
the Verifier could verify no other issuer’s. It now follows W3C Data
Integrity BBS Cryptosuites v1.0 (baseline), in issuance, presentation and
verification (Verifiable credentials).
- The base proof is the specification’s: blank nodes relabelled by HMAC,
the statements named by the configuration’s mandatory JSON pointers hashed
into the BBS header, and the other statements signed as messages
(
oid4vci.ldpVcMandatoryPointers,oid4vci.ldpVcDidMandatoryPointers; default/issuer,/type,/validFrom,/validUntil). The proof carries nocreated. - A presentation is a reveal document, the credential with only what the
holder reveals, carrying a derived
DataIntegrityProof. Presented on its own, its presentation header must be the request’s nonce; inside aVerifiablePresentation, the presentation’s proof carries the nonce as itschallengeand the client as itsdomain(OpenID4VP 1.0 B.1.3.2.5), and the header may be the nonce or empty. - The BBS key is published as the specification’s Multikey:
publicKeyMultibaseiszand base58btc of0xeb01and the 96-byte key, at/bbs/keys/{kid}and in the DID document. It wasuand the raw bytes. - Credentials issued by 1.0.x cannot be presented by default. Their
proofs are in the old, non-standard format and cannot be turned into the
new one, so a realm refuses a presentation in it, naming it as the pre-W3C
format (
STS-VC-0181). Holders need their credential issued again: a refresh or a new issuance from 1.1.0 gives a W3C one. A 1.0.x credential expires afteroid4vci.credentialLifetimeS(thirty days by default) anyway. oid4vc.bbs2023LegacyFormat(per realm, defaultfalse) makes a realm use the old format again: it issues itsldp_vccredentials in it and accepts presentations in it, as well as W3C ones. Turn it on only while a wallet that has not moved to W3C bbs-2023 is in use, and off once it has; a credential issued under it cannot be presented once it is off. The old format is namediya-bbs-2023-legacyin the metadata and in the credential, neverbbs-2023, and every use is logged (STS-VC-0182for a presentation,STS-VC-0183for an issuance).
The remote PEP authenticates with its key; the client certificate is retired
A remote XACML PEP authenticates every call it makes to the service — the
registration, the pulls, the heartbeat, the PIP, the decision records and
the AuthZEN forward — with a DPoP-bound access token from an RFC 7523
assertion it signs with its own key (PEP_ASSERTION_KEY). The key is
generated where the PEP runs and certified with issue-pep-credential; the
service never holds it (How the PEP authenticates to the service).
xacml.pepAuthenticationdefaults totoken. A PEP that presents only a client certificate is refused (401,STS-XACML-0289).eitherandcertificatestay available for an older PEP image or another implementation.- The 1.1.0 upgrade script keeps a 1.0.0 deployment’s PEPs working.
Every PEP 1.0.0 registered authenticated by its client certificate, so
postgres/upgrade-1.0.0.sqlandmariadb/upgrade-1.0.0.sqlstorexacml.pepAuthentication=eitherin every realm with at least one registered remote PEP (an entry under itsou=peps), only where the realm stores no value. When the default realm has a PEP itseitheris service-wide, so the script also storestokenin each other realm with no PEP and no value. A realm with no PEP, and a new installation, gettoken. - Then move each realm to
token: give each PEP its key (issue-pep-credential, thenPEP_ASSERTION_KEYon the 1.1.0 PEP image), and once every PEP in the realm holds its tokens, setxacml.pepAuthenticationtotokenor reset it (Upgrading a deployment whose PEPs use a certificate). Without the script (the LDIF store, or a split cell database), seteitheryourself before the PEPs reconnect. If a PEP is refused anyway, the 401 says thateitherwould accept its certificate, and the service logs a warning underSTS-XACML-0289once per realm. - The PEP ignores
PEP_TLS_CERTand says so once at start (STS-XPEP-0135).PEP_TLS_KEYis still read as the assertion key whilePEP_ASSERTION_KEYis unset.GET /’scredential.clientCertificateis alwaysfalse. - The CRL-only plain listener binds only with
PEP_CRL_HTTP=true. It served the client certificate’s CRLs. A PEP with a CRL directory and no switch says once that it is not bound (STS-XPEP-0136). - An anonymous request to
/xacml/pep/*is now a 401 (STS-XACML-0289) in a realm on the default, where it was the access policy’s 403. - The seeded client
sts-remote-pepno longer declares certificate-bound tokens; an entry a pre-release build seeded with the flag has it removed at the next start (audited asapplication.update). A token request through it with no DPoP proof isSTS-OAUTH-1012. - The test stacks and the AWS suite runner mint no client certificate for the PEP and post no trust anchor for it.
A remote PEP’s directory entry is a service account
The entry a remote XACML PEP’s client certificate maps to is now a service account, owned by the realm’s Admin Write group, or by its bootstrap administrator where that group does not exist (details).
- When it happens. An entry becomes one when it joins
remote-peps. The seededremote-pep-1and every entry already in the group become one at the next start, so an existing deployment needs no step of its own. - What changes. The PEP’s connection is unaffected: mutual TLS is not a service-account door. A browser sign-in as the entry is now refused (STS-SVCACCT-0010) unless the realm’s service-account policy allows it.
- When it waits. A realm with no Admin Write group and no bootstrap administrator leaves the entry as it is and logs STS-SVCACCT-0051: a service account is never made without an owner.
- The console and the API. The PEP’s Overview tab shows it, with the
owners and a link to the person’s Service account tab. Each row of
GET /admin-api/xacml/pepscarriesidentityAccount. The change is additive.
The remote PEP binds no plain-HTTP listener by default
The remote XACML PEP container (iyasec/iya-sts-xacml-pep) no longer binds
its plain-HTTP decision API on 9090 or its plain-HTTP reverse proxy on 9180
unless you ask for them. Over HTTPS, 9443 and 9543 behave as before.
- To keep the old behaviour, add
PEP_HTTP=true(the API) andPEP_PROXY_HTTP=true(the proxy) to the container’s environment. Withdocker-compose.yml, setXACML_PEP_HTTP=trueandXACML_PEP_PROXY_HTTP=trueon the host. - A container that sets
PEP_PORTorPEP_PROXY_PORTwithout the switch logsSTS-XPEP-0106once at start, naming the line that brings the listener back. A switch set to anything other thantrueorfalseleaves the listener off and logsSTS-XPEP-0107. - The image’s healthcheck probes
/healthcheckover HTTPS onPEP_HTTPS_PORTwhen plain HTTP is off. A PEP with no HTTPS pair yet reports itself unhealthy until it has one. If something gates on that health, turnPEP_HTTP=trueon. docker-compose.yml’s defaultPEP_NOTIFY_URLis nowhttps://xacml-pep:9443/notify. The oldhttp://default was refused unlessxacml.pepNotifyAllowHttpwas on.- The client credential’s CRL stays reachable. A credential minted with
tests/tools/pep-credential.js --crl-base=http://<pep>:9090/crlnames the PEP’s plain port, and with plain HTTP off nothing answered there, so the service could not fetch the list and refused every pull as unauthenticated. WithPEP_HTTPoff the PEP now bindsPEP_PORTforGET /crl/<name>and nothing else, whenever it has a CRL directory to serve.PEP_CRL_HTTP=falseturns it off andPEP_CRL_HTTP=truebinds it even with no directory; a value that is neither logsSTS-XPEP-0115. Since the client certificate was retired (above), onlyPEP_CRL_HTTP=truebinds it. Anything else asked of that port is a 404 (STS-XPEP-0114). The Listener tab shows it as listening, CRLs only. - Admin console: the remote PEP’s Listener tab shows the two listeners as off, each with its switch. A listener the PEP reports off no longer holds its port, so a listener defined on the tab may use 9090. A listener the PEP has not reported, or reported with no state, reads not reported (it read listening before), and an environment plain-HTTP listener with no report reads as its default, off.
The nudge to a remote PEP is HTTPS only, and verifies with no setting
The service sends a remote PEP’s “pull now” nudge over HTTPS only, in every mode, and always verifies the PEP’s certificate.
- Trust with nothing set. The PEP’s HTTPS listener certificate is issued
by the realm’s Remote PEP listeners (
pep-tls) Issuing CA, and the nudge verifies against that chain by default, with the host checked against the notify URL’s. A certificate from this service’s Root but another Issuing CA (another realm’s PEP, a custom listener) is refused (STS-XACML-0260).xacml.pepNotifyCaFileis still read, as an additional anchor for a PEP certified elsewhere. The nudge that 8081 refused with “self-signed certificate in certificate chain” (STS-XACML-0070) is delivered. xacml.pepNotifyAllowHttpandxacml.pepNotifySkipTlsVerificationare retired. Both are still accepted, so a configuration naming them keeps starting, and both are ignored; one that is on logsSTS-XACML-0258once per process. Remove them.GET /admin-api/xacml/peps’notify.transportreportsallowHttpandskipTlsVerificationasfalse.- A PEP registered with an
http://notify URL is shown with that URL unusable, plain http, the nudge is sent over HTTPS only, and goes on converging by polling. Set its notify URL tohttps://<host>:<PEP_HTTPS_PORT>/notify(the PEP’s Settings tab now refuses anhttp://one,STS-XACML-0239).STS-XACML-0259is recorded for a nudge refused that way;STS-XACML-0073andSTS-XACML-0074are retired. - The PEP answers
POST /notifyon its HTTPS listener only (a 404 over plain HTTP,STS-XPEP-0112), and rejects anhttp://PEP_NOTIFY_URL, or anhttp://notifyUrlan older service stored (STS-XPEP-0113, at ERROR, once per value). A rejected URL means the PEP advertises no notify URL at all, not the derived one, until it is fixed or unset. It is reported withrejected: true(peps[].settingsInUse.values.notifyUrl.rejectedonGET /admin-api/xacml/peps), and the PEP’s Settings tab and Notify column say it is rejected. - Admin console: the Notify column of the Remote PEPs tab, and the PEP’s Overview, show usable, unusable with a one-line reason, or none, and two words about the last nudge; the full sentences are under Details.
- The PEP derives its notify URL when none is set. With neither the
PEP’s Settings tab
notifyUrlnorPEP_NOTIFY_URLset, the PEP advertiseshttps://<host>:<PEP_HTTPS_PORT>/notify.<host>is the DNS name in the HTTPS listener certificate it serves that equals its hostname, else the certificate’s first DNS name, elsePEP_NAMEif that is a DNS name, else the container’s hostname. So a certificate naming the PEP’s registered name first andxacml-pepsecond, on a container namedxacml-pep, givesxacml-pep. A PEP with no HTTPS certificate yet advertises none until it has one, and a new certificate derives the URL again. The PEP logs the derived URL at INFO, and reports its source asderived(GET /admin-api/xacml/peps’peps[].settingsInUse.values.notifyUrl.source). The Notify column says derived by the PEP from its HTTPS listener certificate. The service still checks the URL as before: https only, the certificate verified, and the host checked against it.docker-compose.ymland the test stack no longer set a notify URL, so they derive it.XACML_PEP_NOTIFY_URLstill sets one, and an empty one now means unset. - The PEP reports its hostname, and the realm’s default certificate names
it. The PEP sends
hostname(the value the derivation reads) on its registration and heartbeat. The service stores it and adds it to the default names of the PEP’s HTTPS listener certificate, beside the registered name and the notify host, for both the environment pair and a defined listener’s certificate. So on a fresh install the derived notify URL uses the hostname with no names added by hand. The PEP’s Overview tab andGET /admin-api/xacml/peps(peps[].hostname) show it. The service accepts only a DNS name, never an IP address, and refuses anything else with 400 (STS-XACML-0261). A PEP that reports none keeps today’s defaults, and an older service ignores the member. A certificate issued before this does not name the hostname: issue it again, or let a defined listener renew.
The reverse proxy’s fixes from the 8081 demonstration
- The service’s cookies never reach the application. A browser sends
cookies by host, not port, so where the service and the proxy share a host
__Host-sts_sessionand the rest were forwarded upstream. The proxy now strips every cookie the service names on the pull (realm.serviceCookiePrefixes:sts_*,__Host-sts_*,__Secure-sts_*), and the managed settingproxyStripCookies(PEP_PROXY_STRIP_COOKIES) adds names, a trailing*for a prefix. The application’s own cookies are untouched. A service older than this sends no list, and the PEP strips the same three prefixes. - An identity header with no value is not sent. A person in no group sent
an empty
X-Iya-Groups; an empty string or list now sends no header, for every identity header. X-Iya-Amris sent. The identity endpoint answered every proxy session’s access token with noamr; it now reads the token’s ownamr,acrandauth_time.- A proxy session a CAEP signal ended clears its cookie on the redirect to sign in, as the documentation said.
- Between a sign-out and its signal, a browser whose identity the service refused because its session had ended got a 403; it is now sent to sign in with the proxy session ended, and anything else gets a 401.
- The account chooser shows usernames. The service’s ID Token carries no
preferred_username, so an account was labelled by itsurn:uuidsubject; the sign-in now asks the service’s session endpoint, whose answer also carries the person’s display name (name), shown beside it. - A route’s identity is edited on the route’s own page. The Reverse
proxy tab drew a How route … forwards the identity form under its table
for every route; that is now only the identity part of the route page’s
form, which the route id in the table links to.
POST /admin-api/xacml/set-pep-route-identityis unchanged. /admin-api/xacml/*PEP acts takepepas well asname, the nameGET /admin-api/xacml/pepstakes as?pep=.namestill works; both naming different PEPs is refused (STS-XACML-0038).
Plain HTTP is off by default has the precedence and the reasons.
New: a remote PEP route’s own page, and several accounts in one browser
- Each reverse-proxy route has a console page of its own, where every value can be edited and the route renamed (A route’s own page).
- A session route can let one browser hold several signed-in accounts and
switch between them (
multipleAccounts, off by default; the bound isproxyMaxAccounts,PEP_PROXY_MAX_ACCOUNTS, default 5; Several accounts in one browser).
Changed: every reverse-proxy route is authorized by its own policy
- Every request on every route is decided in XACML by that route’s own
policy, never by the realm’s root. Each route makes one
authorizationchoice: an existing policy, a simple generated policy (a resource, CRUD or read/write, and the roles for each action), or Public, which generates a policy too (Authorizing a route). The route forms draw the choice as one selector, with a search for the policy and for each action’s roles. - An empty methods list is deny-all, and a route takes any method by
listing all seven. Every route states its
methods. - Not compatible with the proxy documents of earlier builds, which the
proxy feature’s unreleased state allows:
public,resourceandactionare refused as members,methodsandauthorizationare required, and a remote PEP and the service upgrade together. Save each route’s choice again (or edit the document) after the upgrade.
Credentials are signed by a key of their own, whose certificate names the issuer
Until now, a dc+sd-jwt or jwt_vc_json credential and its Token Status
List Token were signed with the realm’s general JOSE key. That key also
signs ID Tokens, access tokens, metadata and Security Event Tokens, and its
certificate named no issuer. A wallet following HAIP 1.0 section 6.1.1 had
nothing in x5c to compare the credential’s iss with
(Verifiable credentials).
- Each realm signs its credentials and their status lists with a
dedicated key for each algorithm family (RSA, each curve, each
post-quantum algorithm). That key signs nothing else. It is made the first
time a credential needs it, is published in
/oauth2/jwksand in the DID document, and is accepted by this realm’s Verifier. It is not accepted for any of the realm’s other tokens. - Its certificate binds the issuer. The subjectAltName holds one
uniformResourceIdentifierfor every issuer identifier the realm answers to, plus thedid:webof each. Withglobal.publicBaseUrl(or the credential application’s listener) pinned, that is exactly one issuer. Otherwise it is eachtls.hostnamesandtls.ipsname on the main port. The extended key usage isid-kp-documentSigning(RFC 9336). There is no DNS name and no TLS usage, so no TLS stack takes the certificate for a server certificate. keyUsage isdigitalSignaturealone. A post-quantum key, ML-DSA included, has a certificate over itself, never over a partner’s key. - It is re-issued when the issuer identifiers change (a new
global.publicBaseUrl, a listener, a host name), at the next credential. The certificate it replaces is not revoked, so credentials issued under it keep verifying. - Revoking the live certificate takes effect at once.
- After
superseded,affiliationChangedorcessationOfOperation, the same key gets a new certificate. - After any other reason, including
keyCompromiseandcertificateHold, the next credential is signed by a new key. The old key is no longer published or accepted while the revocation stands (STS-PKI-0287).
- After
- A credential whose
issthe certificate does not name is still issued with itsx5c. That happens when a request reaches the service by a name nobody configured. The service logs a warning once per realm and address (STS-PKI-0283), and a strict wallet refuses the credential. Pinglobal.publicBaseUrl, or add the name totls.hostnames. keys.credentialSigner(STS_KEYS_CREDENTIAL_SIGNER):dedicated, the default, orrealm-key, which keeps 1.0.0’s behaviour for a deployment whose verifiers pinned the realm’s general key. Credentials already issued verify either way.ldp_vcandmso_mdocare not affected, and neither is the trusted list, which its scheme operator signs.
WS-Trust uses XML Encryption selected by an XPath expression map; ?encrypt=1 is retired
POST /sts?encrypt=1 encrypted the issued SAML 2.0 assertion to the
requester’s certificate. That query parameter was this service’s own test
control. It was never part of WS-Trust, and it is retired. A request that
still carries encrypt=1 is handled as if the parameter were absent:
nothing is encrypted because of it, and the parameter alone is not a fault.
XML Encryption of a WS-Trust message is now chosen per application, once
for the request and once for the response. Each direction is a checkbox
and an XPath expression map: a list of expressions, one per value, naming
what must be element-encrypted. An expression may select a SOAP header,
the SOAP body, or any other element, so a SAML assertion, a JWT, a
username token and any other token are covered by the same map. Each
selected element is replaced by xenc:EncryptedData with Type
http://www.w3.org/2001/04/xmlenc#Element, and the key sits inside that
element. The response is not wrapped in saml:EncryptedAssertion.
This does not use the SAML assertion settings.
saml2.encryptAssertion, saml2.encryptionAlgorithm,
saml2.keyTransportAlgorithm and samlEncryptionCertificate are
unchanged and apply to SAML only. WS-Trust has its own settings and its
own attributes.
- Each direction has a checkbox and its XPath map. Both checkboxes
default to off, and an application may override either.
wstrust.encryptRequest(wstrustEncryptRequest) requires every expression inwstrustEncryptRequestElementsto arrive as XML Encryption. The service verifies a WS-Security signature on the message as it arrived, then decrypts those elements with the realm’s XML private keys.wstrust.encryptResponse(wstrustEncryptResponse) replaces every match ofwstrustEncryptResponseElementsin the response.- A switch that is on with an empty map is a fault. An expression that matches nothing is a fault. Either one stops processing at once and returns that fault: nothing is issued, and the clear response is not sent.
- An expression is a stated subset of XPath. It may use
/and//,*, an element name,prefix:local, a union with|, and the predicateslocal-name(),namespace-uri()and@attr, joined byand. Any other expression iswst:RequestFailed(STS-WSTRUST-0079). Writelocal-name()andnamespace-uri()when one expression should match SOAP 1.1 and SOAP 1.2. A prefix is resolved from the namespaces declared on the element, and from SOAP 1.1, SOAP 1.2, WS-Addressing, WS-Security, WS-Security Utility, WS-Trust, SAML, XML Signature and XML Encryption. - The algorithms are WS-Trust settings, overridable per application.
wstrust.encryptionAlgorithm(wstrustEncryptionAlgorithm) defaults toaes256-gcm.aes128-gcmis also available, andaes256-cbcandaes128-cbconly where broken algorithms are allowed.wstrust.keyTransportAlgorithm(wstrustKeyTransportAlgorithm) defaults torsa-oaep-mgf1p.rsa-oaepis also available, andrsa-1_5only where broken algorithms are allowed. Where legacy hashes are not allowed,rsa-oaep-mgf1pis used asrsa-oaep. An elliptic-curve recipient uses ECDH-ES whatever the key transport says. - The response is encrypted to one recipient, and a configured step
that cannot be used does not fall through to the next.
wstrustEncryptionCertificateon the application, when it is set: base64 DER or PEM. A value that cannot be used is a fault.- Otherwise
wstrustResponseRecipientXPath: the firstds:X509Certificateor#X509v3BinarySecurityTokenthat expression selects in the request. An expression that is set and matches nothing, or that selects an element that is not one of those two, iswst:InvalidRequest(STS-WSTRUST-0076). A certificate element whose text is not a certificate iswst:RequestFailed(STS-WSTRUST-0077). The next source is not tried. - Otherwise the first signer certificate element the request’s
WS-Security signature names, in document order. That is the
#X509v3BinarySecurityTokenthe signature’s reference points at, or ads:X509Certificatein that signature’sKeyInfo. A thumbprint, Subject Key Identifier or issuer-serial that does not carry the certificate element is not a recipient. A certificate inside an assertion, or insideOnBehalfOforActAs, is not the signer’s. With response encryption on and no recipient, the fault iswst:InvalidRequest(STS-WSTRUST-0076) in both modes. A cipher failure, a response expression that matches nothing, or a certificate the encryption-recipient check refuses iswst:RequestFailed(STS-WSTRUST-0077). Under paranoid PKI mode the certificate must permitkeyEnciphermentorkeyAgreement. A message-signing certificate permitsdigitalSignatureonly, so setwstrustEncryptionCertificatewhen the signer’s certificate cannot be an encryption recipient. A certificate with nokeyUsagemay encrypt (RFC 5280).
- A request element the map requires, sent in clear, is refused in both
modes. After decryption every request expression must select at least
one node, and every selected node must be one restored from ciphertext
or inside one. A clear match, a miss, or a decrypt that fails is
wsse:FailedCheck(STS-WSTRUST-0075), WS-Security 1.1’s code. Development mode no longer answers in clear when encryption was required and could not be done. - Arbitrary ciphertext is a setting, off by default. With
wstrust.acceptEncryptedElements(an application’swstrustAcceptEncryptedElements) on, an encrypted element anywhere in a request is opened: anEncryptedDataof type Element or Content, a WS-Security 1.1EncryptedHeader, its key in its ownKeyInfoor in anEncryptedKeyin the security header that lists it. Off, ciphertext is accepted only where the request map names it, and anything else isSTS-WSTRUST-0080. A ciphertext must open with this realm’s keys either way. A signature is verified in the order the security header gives, so a request signed before it was encrypted verifies, and what opens outside the signed Body isSTS-WSTRUST-0046in product. - A map’s prefixes are the service’s.
wst,wsa,samland the rest mean what WS-Trust lists, whatever the request declares. - An encrypted answer announces itself. Its
EncryptedKeyandReferenceListare in awsse:Securityheader, so WSS4J and WCF decrypt it in their own security processing. - A recipient expression selects only what the signature covers. The
certificate
wstrustResponseRecipientXPathselects must be the signer’s own token or inside a part the accepted signature references, or the request isSTS-WSTRUST-0081. - The WSDL describes it (the metadata document).
The message signature is an
sp:AsymmetricBindingundersp:Basic256Sha256on the eight ports, and under this service’s own suite,urn:iya-sts:ws-securitypolicy:algorithm-suite:1Basic256GcmRsaOaepSha256(AES-256-GCM, RSA-OAEP over SHA-256, RSA-SHA256), on eight moreIyaSuiteports. A request may sign every header and the Body, and may be encrypted where the realm accepts it under the port’s suite; an answer may be encrypted where the service-wide cipher is that suite’s. Each choice is optional. Ansp:IssuedTokennow carries the nestedwsp:PolicyWS-SecurityPolicy requires; without it Apache CXF would not load the WSDL. - The encryption certificate as each port’s identity is a setting, off by
default. With
wstrust.advertiseEndpointIdentityon, every port carries the realm’s encryption certificate in awsa:EndpointReference/wsid:Identity, where WCF reads it. That element is from WS-AddressingIdentity, a Microsoft specification that was never standardised, so the WSDL does not carry it by default. Off, a client is configured with the certificate from/saml2/metadata(The encryption certificate). - An RST may name a cipher only inside the application’s policy.
Absent
wst:EncryptionAlgorithmandwst:EncryptWith, the application’s settings are used as they stand. Either element may name a cipher only when response encryption is already on and the name is the configured algorithm. Anything beyond that iswst:InvalidRequest(STS-WSTRUST-0078).wst:UseKeyandwst:ProofEncryptionstay unimplemented, because this service issues bearer tokens. STS-WSTRUST-0012andSTS-WSTRUST-0013are retired. They named the query parameter. A fault response is not encrypted.
To encrypt the issued SAML 2.0 assertion, set wstrustEncryptResponse
to true and add this as one value of
wstrustEncryptResponseElements:
//*[local-name()='Assertion' and namespace-uri()='urn:oasis:names:tc:SAML:2.0:assertion']
Callers that looked for EncryptedAssertion find EncryptedData.
Nothing already stored has to be migrated, and there is no upgrade-script
step. Both switches default to off, so a deployment that never sent
?encrypt=1 is unchanged. A caller that did has to set the application
as above. The query parameter no longer encrypts the assertion.
New: an application’s own WS-Trust decryption key pair
An application may now hold a decryption key pair of its own, so a request for it is encrypted to its certificate rather than to the realm’s XML Encryption certificate (#1668). On the application’s Credentials tab, WS-Trust decryption key pair, and through three new management API operations:
- Issue one from the realm’s certificate authority
(
POST /admin-api/applications/issue-wstrust-decryption-key): thekey-enciphermentprofile,rsa-3072orec-p256, subjectCN=<application>-encryptwith the realm’s organisation. - Upload a PEM certificate and its unencrypted private key
(
upload-wstrust-decryption-key). The key must be the certificate’s, RSA of 2048 bits or more or EC on P-256, P-384 or P-521; each refusal has its code,STS-ADMIN-0946to0950. - Remove it (
remove-wstrust-decryption-key).
The private key is sealed where keys persist and is never shown, answered
or logged. The certificate is on the page, with a download, and in
credentials.wstrustDecryption of GET /admin-api/applications?application=.
The WSDL does not name it: configure the client out of band.
A request is opened with the key its EncryptedKey names, so a request
whose AppliesTo is inside the ciphertext still opens. Ciphertext opened
with an application’s key in another application’s request is
wsse:FailedCheck (STS-WSTRUST-0082), and a request for an application
with its own key encrypted to the realm’s key is STS-WSTRUST-0083. An
application without one is unchanged. Four new directory attributes carry
it (wstrustDecryptionCertificate, wstrustDecryptionCertificateChain,
wstrustDecryptionPrivateKey, wstrustDecryptionKeySource); nothing
existing has to be migrated, and there is no upgrade-script step.
1.0.0
1.0.0 is the first release of iya-sts. Every build before it was a pre-release.
SAML service provider metadata written through the API is read
Writing an application’s samlSpMetadata through POST /admin-api/applications/set
or add, or through the console’s field grid, now reads the document the way
creating the application or uploading the document always has: its assertion
consumer services, their bindings and its certificates are registered. Until
1.1.0 those doors stored the text and registered nothing, so a SAML 1.1 relying
party updated that way was answered with the Browser/POST profile at a consumer
its metadata declares for Browser/Artifact.
A document that does not describe the application is now refused with HTTP 400
and nothing is written, as the create and upload doors already refuse it
(STS-ADMIN-0935). Writing an empty value still clears it.
An inbound OpenID Connect ID Token’s iat is held to the sign-in
A federation relationship that signs people in from an OpenID Connect partner
now refuses an ID Token whose iat is before the sign-in started or after now,
each end widened by oauth2.clockSkewS (OpenID Connect Core 3.1.3.7, step 10;
STS-FED-0253). Nothing is redeemed and UserInfo is not asked after the
refusal. Until 1.1.0 any iat was accepted, so an ID Token issued a week
earlier signed a person in. This applies to every relationship, not only the
FAPI profiles. A partner whose clock is behind this service’s by more than the
skew is now refused; raise oauth2.clockSkewS for it.
Not backwards compatible with earlier builds
1.0.0 is not backwards compatible with the pre-release builds that came before it. Moving an existing deployment from a pre-release build to 1.0.0 works in many situations, but there are edge cases with no clean upgrade path. Stored settings, directory entries, persisted data or client configurations created by an earlier build may need to be recreated rather than carried forward.
This is deliberate. The earlier builds were pre-release versions, and we are not attempting to keep 1.0.0 compatible with them.
If this causes you trouble, open an issue on the GitHub repository: github.com/rcbj/iya-sts/issues. Say which build you are moving from and what did not carry over.
Backwards compatibility from here on
Our goal is backwards compatibility going forward. Releases after 1.0.0 are intended to upgrade cleanly from 1.0.0 and from each other. The steps from a running 1.0.0 deployment to 1.1.0 are in 1.1.0 above. Where a later release cannot upgrade cleanly, its notes on this page will say so and describe the path.
Version numbers
A build reports its version as M.N.O.<build>. M.N.O is the release, and
for 1.0.0 the release build is 1.0.0.0. Other builds of the same code carry
the UTC time they were built as their build number. After 1.0.0, each change
published from main is the next patch release (1.0.1, 1.0.2, …), and a new
minor or major release starts when the repository’s VERSION file is set to
it. A release that needs an upgrade script is a minor (or major) release,
never a patch: going from one patch release to the next never asks you to
run anything against your database. That is why the release after 1.0.0 is
1.1.0. The running service shows its version on the admin console and in its
metadata.
Release candidates. Before a release is published, its candidate may be:
iyasec/iya-sts:1.1.0-candidate and iyasec/iya-sts-xacml-pep:1.1.0-candidate
(also on ghcr.io/rcbj), each beside its full 1.1.0.<build> tag. A candidate
is for testing. It reports its version as 1.1.0.<build> like any other build,
and it is not the release: :1.1.0 and :latest are published only by the
release itself. A newer candidate replaces the -candidate tag.