Upgrading Between 8.0 Previews
Only for a deployment that already runs an 8.0.0 preview: what changed from each preview to the next, newest first. A 7.x deployment needs none of it: Upgrading is the whole upgrade. These notes are removed when 8.0 is released.
Start here
Each section below is what changes when you leave that preview. Read the section of the version you run and every section above it:
| You run | Read |
|---|---|
8.0.0-beta.5 | From beta.5 |
8.0.0-beta.4 | From beta.4, then the one above |
8.0.0-beta.3 | From beta.3, then the two above |
8.0.0-beta.2 | From beta.2, then the three above |
8.0.0-beta.1 | From beta.1, then the four above |
8.0.0-alpha.4 | From alpha.4, then the five above |
8.0.0-alpha.3, alpha.2, alpha.1 | From alpha.3, alpha.2 or alpha.1, then every section above it |
Which preview of the library may run behind which preview of the gateway image: see Upgrading a running deployment.
From 8.0.0-beta.5
- The control plane's facade is a module of its own,
cosec-control-sdk(CTL-65). Affected: code that callsControlService.ControlService,ControlCallerandControlRefusedExceptionkeep their names and package (me.ahoo.cosec.control.sdk);cosec-controlbrings the module, so a build that hascosec-controlchanges nothing. Code that only calls a control-plane host needscosec-control-sdkalone, with an implementation of it.ControlService.changesfilters byme.ahoo.cosec.control.sdk.ChangeState, the wire's closed set, which keeps an unknown value's text (isUnknown), instead of the control plane's internal enum: passChangeState.READYof the new package, orChangeState.of("READY").ControlCaller.of(context)no longer throws for a security context CoSec did not make: the call it is passed to does, with the sameIllegalArgumentException(PIP-29).
From 8.0.0-beta.4
Twelve properties are computed and have no key (
SNP-23,CTL-72; the rule is that what can be computed is not configured). Affected: a configuration that sets one. Startup fails with the keys CoSec does not read, and says of each that it is no longer a property and what replaced it. Remove the key; where you had moved the value, move what it follows (Computed, not configured).snapshot.reload-concurrencyis the one that was in no release.Removed Now cosec.authorization.snapshot.lag-warn,lag-escalate6 and 30 passes of revalidate-interval: set that to move themcosec.authorization.snapshot.cold-load-timeout40 % of cosec.pipeline.timeout: set that to move itcosec.authorization.snapshot.compile-threadsone per 2 cores, at least 1 and at most 4 cosec.authorization.snapshot.reload-concurrency16, a constant cosec.authorization.shadow.report-intervala sixth of the status's life (10 s), and no oftener than a fifth of cosec.control.shadow.min-durationor a secondcosec.authentication.revocation.cache.initial-capacity,expire-after-accessnone: the cache sizes itself, and local-max-ageexpires every entrycosec.control.revisions.orphan-age,reclaim-intervalone reclaim pass, and 1 hour cosec.control.shadow.check-intervala fifteenth of cosec.control.shadow.min-duration, between 250 ms and 1 minutecosec.control.http.max-body-sizethe 8 MB document cap and 2 MB: 10 MB The starter logs once at startup, in a line that begins
CoSec derived, not configured:, what it derived and from what. A system test that shortenedreport-intervalandcheck-intervalnow shortenscosec.control.shadow.min-durationalone, and both follow.New:
GET /documents?kind=tenant|applists which tenant and app documents exist (CTL-68), a page at a time, on the operators' routes, the service port and the facade (ControlService.documents). Who may list, and what a page says, is in Listing documents. Nothing to change.The control API's listings page with opaque cursors, and a page may be short or empty before the end (
CTL-55,CTL-68, review round 3). Affected: clients ofGET /changesandGET /documents.nextandafterare tokens: passnextback asafterunchanged, and read nothing out of it. A malformed token, another listing's, or one for a position the listing does not have is a400, never a listing from the start.GET /changes?state=is decided before the store is read, and reads at most four pages' worth of changes per request: a page with anextmay hold fewer entries thanlimit, or none. Ask again withafteruntilnextis absent (Listing cursors).
A change's answer carries how its author was identified (
CTL-70). Every reader getsorigin.assertedandorigin.via.method; a reader who holdscosec:approveon the change's document, orcosec:readon the platform's, also getsvia.credential,via.requestandpeer. A change no request made has noorigin. A client that does not know the member ignores it (What a change answers).A change listener receives a change's events in the order they were written, through a queue of its own bounded by a share of the heap (
CTL-66). Affected: change listeners of your own, and consumers of the change stream.- Each listener has one queue and one consumer, so it no longer receives one change's events out of order.
- A
REQUIREDlistener with no room, a failure or no answer withincosec.control.audit.required-timeoutfails a gated step (503), as before. For any other step the step is stored, and the event that finds no room, or whose call fails, is lost: counted incosec.control.listener.lostand logged atERRORnaming the change. - At shutdown the queues are delivered within
cosec.observability.listener.drain-timeout(Order and queues).
CoSec's own token verifier answers a token it has verified from memory until the token expires (
IDN-32). On by default; the revocation and reserved-attribute checks still run on every request.cosec.authentication.token-cache.enabledandmax-entries(16384) are new; an application's ownTokenVerifiergets no cache (The verified-token cache). Nothing to change.A Redis that hangs is answered as one that is down, for the revocation check (
PIP-7). Affected: a deployment that setcosec.pipeline.authentication-timeout. Each read of CoSec's revocation reader now has its own budget, the newcosec.authentication.revocation.read-timeout(300ms); past it the token is accepted (or refused, withfail-closed) and a refresh fails, where a hang used to make every authenticated request503. Startup fails unless twice the read timeout is less than the authentication timeout, naming both. An application's ownRevocationReaderbounds its own reads.Data-plane instances read the staged list and compile a staged candidate on sight (
CTL-47,CTL-12,OBS-8). An instance samples only the requests that read a document the list names, reportsCANDIDATE_ERRORfor a candidate it cannot compile within a report interval of seeing it, whatever its traffic, and makes no decision event for the shadow listener when nothing was sampled. A list that cannot be read counts as no list, and every candidate is read by its key as before. Nothing to change; the Redis ACL line ofCTL-46above is what an instance needs.The control API's service port is the application's own server on another port (
CTL-71). It takes the application's TLS and client authentication, bind address, HTTP/2, limits and timeouts, and serves the control API's service profile only, no route of the application. If mutual TLS on the application port is what makes the statement of what can reach the host true, it holds on the service port too.An app change that defines a system role id another app already defines carries a warning (
ROL-12): aREFERENCESfinding naming the role id and the other apps, never a refusal.The login beans back off for the application's own, and
min-samples: 0is said at startup (UB-15). An application that declares its ownCompositeAuthentication(or the token composite) starts with it, where it failed with two primaries. Withcosec.control.shadow.min-samples=0, startup logs aWARNthat a window then closes on time alone.New: the control plane has an image,
cosec-control, and two named deployments (The control-plane host, Choosing a Deployment). Nothing to change for an application that embeds the control plane: it is the second deployment, unchanged. A deployment that wants the control plane as a process of its own runs the image beside the gateway, under the statementcosec.pipeline.identity.only-trusted-callers-can-reach=true(the image does not start without it) and the three network policies that make it true (k8s/control/).An IAM service in
gatewaymode that now needs the control plane runs inenforcewithcosec.pipeline.caller=forwarded-identityinstead. Affected: a service that was incosec.pipeline.mode=gatewayand addscosec-control.gatewaymode wires no documents, no Redis and no control plane, so the control plane cannot be added to it.- Change
cosec.pipeline.modetoenforceand addcosec.pipeline.caller=forwarded-identity: the service still believes the identity the gateway forwards, and still states what can reach it. The statement is the same (only-gateway-can-reach, oronly-trusted-callers-can-reachonce a service port is on), and so is the refusal of a hidden-method filter. - It now needs
cosec-cocache,cosec-controland a Redis user that writes the documents (Who may write which keys). - Its own routes stay authorized at the gateway or not at all. Set
cosec.control.http.enabled=falsewhen its code reaches the control plane in process only (Configuration).
- Change
CoSec's own routes no longer answer on the management port (
CTL-69). Affected: a WebFlux host (or a gateway host with the control plane on) with amanagement.server.portof its own, whose control API (/cosec/control/v1/...) or login routes (cosec.authentication.login.refresh.path,.logout.path) a client reached there. Spring Boot's management server inherits the application'sRouterFunctions, so they answered on the management port behind the pipeline; on a host that believes the identity it is stated (cosec.pipeline.caller=forwarded-identity, the control-plane host image) that was the whole control API for whoever could reach the port. They answer on the application's port (and the control API on its service port) only, and are a404elsewhere. Call them on the application's port. An application's own routes are unchanged.New: the control plane's facade,
ControlService, for a service that embeds the control plane (CTL-65).- Calls are decided as the
ControlCallerthey state, and recorded as that caller's. - It reaches only the narrow set: tenant and app document reads, and a tenant's change flow.
- Requests and answers are the control API's bodies and JSON.
IdentityHeaderwrites theCoSec-Identityheader.- Nothing to change for an application that does not use them (Changing policies from your code).
- Calls are decided as the
A shadow window passes only when every live instance acknowledges it (design D2,
CTL-10). Affected: shadow windows during and after the upgrade, and clients that read a change'sshadow.- Each data-plane instance now lists, in the status it writes every report interval, the windows whose candidate it has compiled. A window with enough samples still waits until every instance with a status in the last minute lists it; at
cosec.control.shadow.max-durationit closes insufficient as before. - During a rolling upgrade, instances of the previous preview send no acknowledgements, so a window opened then closes no earlier than the upgrade's end (their statuses expire within two minutes of their stopping), or at
max-durationas insufficient. Upgrade the data plane before you stage changes you need closed soon. GET /changes/{id}addsshadow.acknowledgedandshadow.waitingForwhile the window is open (What a change answers);contract/control/change.jsonpins them.
- Each data-plane instance now lists, in the status it writes every report interval, the windows whose candidate it has compiled. A window with enough samples still waits until every instance with a status in the last minute lists it; at
Skipping a shadow window and rebasing a change are recorded as change events (
CTL-63). Affected: change listeners, and consumers of the change log or the audit stream.ChangeEvent.KindgainsSHADOW_SKIPPEDandREBASED. A skip used to be recorded only in the provenance of the revision it published, so a skip whose change was abandoned left no record; now:skip-shadow, and a break-glass change's exempt window, writeSHADOW_SKIPPEDwith the reason in the note, and:rebasewritesREBASED.- A listener that handles every kind adds the two; one with an
elsebranch, as the kind's documentation asks, needs nothing.
The control plane records how each step's operator was identified, and a service port can be added (
CTL-57,CTL-58,CTL-59). Affected: code compiled againstChangeEvent,ChangeRequestorHttpFacts(experimental), whose constructors gained a trailing parameter (origin,origin,peerAddress, each with a default): recompile. Change events written as JSON, and the stored change, gain anoriginmember (asserted,via,peer), which a reader that does not know it ignores. New and unset by default:cosec.control.http.enabledandcosec.control.http.service-port(Configuration). Nothing to change for a deployment that sets neither. Every control-plane instance runs the maintenance passes, kept apart by their leases, and no property turns them off.The control API answers from a response model of its own; a refused scope says why under
reason; propagation counts the instances that hold the document (review round 2,R2C-11,R2C-12,CTL-61,CTL-62). Affected: clients of the control API.- A change answer (
GET /changes/{id}and every route that answers a change) no longer holdscheckedWith,checkedAppsor its window'sshadow.reporters: they were the store's bookkeeping, not part of the API. Every other member is as before (What a change answers). simulateandexplain: aRejecteddecision carriesAPP_MISMATCHorSPACE_NOT_MEMBERunderreason, no longer undercause.causeis anIndeterminatedecision's only, with the values it had.GET /documents/{key}/revisions/{n}/propagationaddsholding(the recent instances that hold the document) andasOf(when the statuses were read; an answer may be up to 5 seconds old).installedandrecentmean what they meant. No instance is behind wheninstalledequalsholding: most instances never hold a given tenant, soinstallednever reachedrecentfor it.holding: 0means no instance holds the document, and the first request loads it at the published revision. A status read that fails is now503, not500.contract/control/pins the members of these answers, the closed sets they write and the audit kind of each route; a release that changes one says so.
- A change answer (
A host that takes its caller from the
CoSec-Identityheader is asked for the statement of what can reach it, however it got that gate (STA-6,STA-7,STA-9). Affected: an application that declared its ownIdentityGatebean besidecosec.pipeline.mode=enforce, which started without one. It now fails startup untilcosec.pipeline.identity.only-gateway-can-reach=true(oronly-trusted-callers-can-reach=true) says that nothing but the gateway, and the services you name, can reach it, and until its hidden-method filter is off. A host ingatewaymode is unchanged.New:
cosec.pipeline.caller=forwarded-identity. A host inenforcemode, with the snapshot and the control plane wired, can take its caller from the identity header instead of a credential: the shape of a control-plane host, or of an IAM service that embeds the control plane. Nothing to change for a host that does not set it (Configuration).Every stored record carries its format, and a reader ignores what it does not know of a known format (review round 2,
R2C-10,R2C-28,CTL-53,IDN-31). Affected: every deployment, once.- Stop the control plane, upgrade it, start it. The previews before this one refuse the
formatmember the new records carry, so instances of both cannot run side by side. From this release on, readers are tolerant, and a later release upgrades in place. - Roll the login hosts together. A login host that still runs the older preview cannot read a session a newer one wrote: a user whose refresh lands there signs in again.
- Data-plane instances that still run the older preview skip a staged candidate the new control plane wrote, and report nothing for its window until they are upgraded. The window waits; it does not pass.
- Nothing to convert: a record written before formats reads as format 1. The window reporters and the instance index are now objects (
{"format":1,"reporters":[...]}), and their earlier forms still read. - A value of a stored record that does not decode is now always a format error. Before, some were an
IllegalArgumentException, which the control API answered400.
- Stop the control plane, upgrade it, start it. The previews before this one refuse the
The control API answers
503whenever the control store cannot answer (review round 2,R2C-6,CTL-52). Affected: clients and alerts of the control API, and aControlStoreof your own.- A Redis outage or timeout during a publish, a document read or a revision read used to answer
500internal-error. It now answers503unavailable, which a client may retry, and is logged atWARN, notERROR. A stored value that does not decode stays a500. ControlStorenamesme.ahoo.cosec.control.store.ControlStoreExceptionfor "the store could not answer". AControlStoreof your own throws it for an outage; anything else it throws is a500.
- A Redis outage or timeout during a publish, a document read or a revision read used to answer
An app change lists the tenants it reaches as one entry per policy; an escalation's reason is an enum (review round 2,
R2C-14,R2C-5,CTL-48). Affected: whoever reads a change'sescalations(the control API'sGET /changes/{id}, aChangeListener, the audit JSON on Kafka), and code that builds or reads anEscalation.TENANT_BINDING, one entry per tenant binding, is gone. An app change that widens a permission policy carries oneTENANT_BINDINGSentry per policy:tenants binding [<policy>] in app <app>, with the statements, how many tenant documents bind it (an upper bound, from the back-reference index) and the first 20 of them. A consumer that countedTENANT_BINDINGentries to tell how many tenants a change reaches reads the count indetailinstead. At 50,000 tenants the change record went from about 50 MB to a few KB, each audit event likewise, and no tenant document is read to check the change.Escalation.reasonisEscalation.Reason, an enum with the names the JSON always carried;Escalation.TENANT_BINDINGandEscalation.DETECTION_TIMED_OUTareEscalation.Reason.TENANT_BINDINGSandEscalation.Reason.DETECTION_TIMED_OUT. A stored change with a name this version does not know reads it asUNKNOWN, which is never informational.ChangeEvent,Escalation,RevisionRefandMovedHeadare@ExperimentalCoSecApi: aChangeListenerof yours opts in, and they may change in a minor release until a release has used them.
The public shapes of the core modules are fixed before RC (review round 2,
R2A-1toR2A-7). Affected: code that compiles againstcosec-model,cosec-spi,cosec-apior the engine. No document, property, stored value or wire format changes.- The decision values are plain final classes with
equals,hashCodeandtoString, not data classes:Decision.Permit,Deny,Indeterminate,Obligation.RateLimit,ViewVersion(incosec-engine) and everyCausebutNotLoadedhave nocopyand nocomponentN, so a new field never breaks a caller. Read the properties (decision.by,cause.error) instead of destructuring a decision. me.ahoo.cosec.spi.ratelimit.RateLimitandRateLimiter.windoware gone.RateLimitSpechaslimitPerWindowandwindowMillis, andlimit.resultOf(allowed, estimate, nowMillis)(importme.ahoo.cosec.spi.ratelimit.resultOf) builds theRateLimitResult: in aRateLimiterof yours, uselimitwhere you usedRateLimiter.window(limit).AuthnResult.Authenticated(principal, method)takes anIdentity.Method, not a string:Identity.Method.API_KEY, orIdentity.Method("ldap")for a credential of your own, any non-empty name. What the audit record andCoSec-Identitysay for CoSec's own methods does not change (jwt,api-key).AuditEvent.kindis anAuditEventKindenum with the five values it always had; the JSON a sink or a Kafka consumer reads is the same bytes. Readauthorization.reasonCodefor why a request ended as it did (decisionis its coarser grouping, mapped in the KDoc ofAuditDecision);bindingis a label for people,authorization.source.viaanddocumentare the typed facts.SnapshotDocumentStoreis@ExperimentalCoSecApi: its shape follows its one backend,cosec-cocache, and a batched or store-wide conditional read is planned. An implementation of yours opts in and may have to change in a minor release.Resource.attributesdefaults to an empty map: nothing sets one today (DOC-10).
- The decision values are plain final classes with
The control plane keeps a list of the staged candidates (
CTL-46),<s>:candidate-staged:all, which instances will read instead of a candidate key per document they serve. Affected:- a Redis ACL for a data-plane instance: add
%R~cosec:candidate-staged:*to its keys (Who may write which keys); - a downgrade of the control plane to a preview before this one: delete
<s>:candidate-staged:allfirst, or instances trust a list nobody keeps. Such a list can only cost shadow samples, never pass a window.
- a Redis ACL for a data-plane instance: add
The back-references and the document list are sets: run
cosec-migrate repair-referencesonce (CTL-42,CTL-43,CTL-44,MIG-4). Affected: every store a control plane of 8.0.0-beta.4 or earlier wrote. Data-plane instances are not: they read none of these keys.- A policy's back-references (
<s>:control:refs:<doc>:<policyId>) were one value, rewritten whole by every tenant that added or dropped itself; they are now a set with a member per referrer and revision, and the document list moved from<s>:control:list:documentsto the set<s>:control:documents:all. A tenant's publish now writes its own members only, whatever the number of tenants (Storage). - Stop every control plane of an earlier version, then run
cosec-migrate repair-references --to-redis <uri> [--cluster] [--key-prefix <p>]once; the control plane of this version may run meanwhile. It converts each back-reference value a head touches, never replaces a set, and removes the old document list last, printingThe store is in the format of 8.0.0-beta.5.A second run changes nothing (Repair the back-reference index, which gives what it costs: at 50,000 tenants about 1.3 million commands, some 22 minutes at a round trip of 1 ms). - Until it has run, the control plane starts, logs one
ERRORnaming the command, and itscosecControlStoreFormathealth indicator isDOWN(Observability). A change that touches a back-reference of the old format is refused (503, naming the command), never let through. - A value no head touches stays in the old format: it blocks nothing, and a later change that touches it fails closed, naming the command, until it runs again.
- The two sets are never kept locally:
local-max-ageanddegraded-local-max-ageofReferenceIndexCacheandControlDocumentSetCacheare locked to 1 ns, and acocache.caches.*entry that sets one fails startup (Configuration).
- A policy's back-references (
The open changes are sets, and
GET /changeslists them: stop the control plane and runcosec-migrate repair-references(review round 2,R2C-2,R2C-4,CTL-54,CTL-55). Affected: every store a control plane of 8.0.0-beta.4 or earlier wrote, and aControlStoreof your own.- The open changes were one value,
<s>:control:list:open-changes, rewritten by every change; they are now sets of record, one per document and one per state, plus a marker,<s>:control:changes:kept(Storage). Two changes no longer contend on one value, and a maintenance pass reads the changes of one document, or of one state, instead of every open change. - Stop every control plane, upgrade it, and run
cosec-migrate repair-references(the same run as for the back-references, above): it lists each still-open change of the old list in the sets, then marks them kept and removes the old list, only once every one of them was read. It printsListed N open change(s) in the open-change sets.and aFAILEDline for each change whose record does not read, and fails while one is left: remove or fix that record and run it again. A store a control plane of this version created has no old list and is kept from the start. - Until the sets are kept, and whenever the old list is there again (an older control plane started on the store), the control plane reclaims no revision and logs a
WARNnaming the command, andGET /changesis503: the sets are not trusted to hold every open change, and a revision an open change rests on must not be reclaimed. A change that is not shadowing is now expired by the reclaim pass (cosec.control.revisions.reclaim-interval, hourly) or when it is read, no longer everycosec.control.shadow.check-interval. GET /changes?document=&state=&after=&limit=lists the open changes the caller may read, as summaries (Finding open changes).ControlStore.openChanges()is gone.ControlStorehasopenChangesKept(),keepOpenChanges(),openChanges(document)andchanges(state, after, limit, documents), which answerListedChange(ReadableorUnreadable) andChangePage, all@ExperimentalCoSecApi.ControlChangeSetCacheis a set of record: itslocal-max-ageanddegraded-local-max-ageare locked to 1 ns, as the other sets' (Configuration).
- The open changes were one value,
A shadow window whose reporter vanished waits, then closes insufficient; the shadow pass skips what it cannot read (review round 2,
R2C-3,R2C-17,CTL-56). Affected: changes in shadow mode, whoever reads a closed window's summary (GET /changes/{id}, aChangeListener, the audit JSON on Kafka), and alerts on the control plane's log.- An instance that reported on a window and has no report now used to make every look at the window fail (
503toPOST /changes/{id}:shadow's caller, aWARNfrom each shadow pass), and the window never closed. The window now waits for it and logsShadow window <w> of change <c> is waiting for [<instances>]; atcosec.control.shadow.max-durationit closes insufficient, as a window with too few samples does, and its summary names the instances invanished. It never passes on the others' reports: publishing needs the summary acknowledged (Testing changes). ShadowSummaryhasvanished, empty unless instances vanished; the stored change and the audit event'sshadowcarry it as an array only when it is not empty.- One shadowing change the pass cannot read no longer stops it from looking at the others; a
WARNnames it at most once an hour. The pass looks first at the windows it looked at longest ago, and a pass its interval cuts short logslooked at <k> of <n> windows. ControlMaintenancetakes aClock(last parameter, default the system clock).ShadowReportReaderhasreadings(window), answeringShadowReadings: the reports that read and the instances whose listed report cannot be read, which the window treats as vanished.CoCacheShadowReportsoverrides it. A reader of your own may too (Extending); without it,readingsreadsreportsand throws where it throws, as before.
- An instance that reported on a window and has no report now used to make every look at the window fail (
Gateway mode states the network boundary it trusts, and the gateway forwards the method it decided (
STA-7,STA-6,PIP-31). Affected: every service incosec.pipeline.mode=gateway, and every gateway.- A service in
gatewaymode believes anyCoSec-Identityheader, which carries no signature, so the network is its boundary. It now fails to start unless you writecosec.pipeline.identity.only-gateway-can-reach: true(COSEC_PIPELINE_IDENTITY_ONLYGATEWAYCANREACH=true), your statement that nothing but the gateway can reach it. Absent, empty,false,1andonfail alike, and the message says what to write. Make it true first (aNetworkPolicythat admits the gateway's pods only, mutual TLS, a private network;k8s/examples/gateway-mode-service-networkpolicy.yaml). Once it is set, theWARNthrough beta.4 is oneINFOline. - A service in
gatewaymode fails to start with a hidden-method filter:spring.mvc.hiddenmethod.filter.enabled=true,spring.webflux.hiddenmethod.filter.enabled=true, or aHiddenHttpMethodFilterbean of its own. The gateway decided the method of the request line, and a_methodform field would run another. Remove it. A host that decides itself (enforce) is unaffected. - The gateway removes
X-HTTP-Method-Override,X-HTTP-MethodandX-Method-Override, in any letter case, from every request it forwards, on every route. Not configurable. A backend that honoured one of them for a request through the gateway no longer does: send the method in the request line.
- A service in
A path holding an encoded
;or control character is a400(R1A-3,PIP-30). Affected: clients that send%3Bor%00to%1For%7F, in either case, anywhere in a path. Through beta.4 they were decided as text of a segment, which Spring reads alike, while a backend behind a gateway that decodes before it strips path parameters serves/admin%3Bx/usersas/admin/users, past aDENYon/admin/**. They are now refused before authentication, mapped route or not, with the400invalid-requestof any path the pipeline will not interpret, and the gateway refuses them before anything is forwarded. So is a raw control character, which the servers CoSec runs on already refuse themselves. A value that holds such a character goes in the query or the body, or has its%encoded again (%253B), which the pipeline decodes once, to the text%3B.%25, a trailing.and a trailing space are unchanged. To check: search access logs, or the audit records'request.path, for%3B,%00to%1Fand%7Fin request paths (Troubleshooting). There is no switch to accept them.The diff of two revisions names the sections that differ (
GET /documents/{key}/diff, UC-14). Affected: scripts and tools that read itssections. Through beta.4sectionswas a boolean,truewhen anything besides the policies, bindings and roles differed. It is now the list of those sections' names, ofcatalog,boundary,limits,attributesandrateLimitsin that order, and[]when none differs. Readsections.length > 0(or its equivalent) where you readsections, or look for the section you care about (Testing policies).A refused forwarded identity is counted and says why, and the gateway no longer writes one a service would refuse (#1690). Affected: services in
cosec.pipeline.mode=gateway, their dashboards and log alerts, and code that callsIdentityHeader.ofin tests.- Such a service logs the reason of each refused
CoSec-Identityheader atWARNon the loggerme.ahoo.cosec.runtime.identity.IdentityGate, at most once a minute for each problem type (every one atDEBUG). Through beta.4 it logged them only atDEBUG. The response is unchanged: it never says why. - With
cosec-micrometerand aMeterRegistryit counts every refusal incosec.identity.refused{problem}(invalid-request,token-invalid,token-expired). Alert on any non-zero rate (Observability). - The gateway refuses to write an identity a service would refuse to read (an empty id, an unpaired UTF-16 surrogate, a time past year 9999, an empty claim name): the request fails with
500and no header is forwarded, where through beta.4 the service behind answered400. CoSec's own gateway builds no such identity; a customAuthenticatorcould.IdentityHeader.ofthrowsIllegalArgumentExceptionfor such an identity, as it did for one too large.
- Such a service logs the reason of each refused
A gateway forwards the caller's credentials only when it accepted them (R1A-7,
IDN-8). Affected: gateways withcosec.gateway.identity.forward-authorization=true. Through beta.4 a request whose token was expired, revoked or invalid, which goes on as anonymous, still took itsAuthorizationheader, API key, query token and cookie to a route that receives the identity when a public route let it through. They now stay at the gateway: the backend sees an anonymous request. A backend that answered such a request by verifying the token itself now gets none.The IP blacklist compares an address in its canonical form (R1A-4). Affected: implementations of
BlacklistSource, and callers ofInMemoryBlacklistSource.block.contains(BlacklistKind.IP, value)is asked with2001:db8::1for any spelling of that address and192.0.2.1for::ffff:192.0.2.1: keep blocked addresses in that form (Extending).InMemoryBlacklistSourcekeeps them so and refuses a value that is no address withIllegalArgumentException.The security context's readers are named for what they do (UA-7). Affected: code that reads the
SecurityContextfrom a Reactor context, an exchange, a servlet request orSecurityContextHolder. Every reader now comes asrequireSecurityContext(), which throws anIllegalStateExceptionsaying what to do where CoSec did not handle the request, andsecurityContextOrNull(), which answersnull. All are@JvmStatic. The old names are gone, with no aliases:Through beta.4 From beta.5 ContextView.getSecurityContext()(threwIllegalStateException("SecurityContext is null."))ContextView.requireSecurityContext()ContextView.getSecurityContextOrEmpty()(answerednull)ContextView.securityContextOrNull()ServerWebExchange.getSecurityContext()(answerednull)ServerWebExchange.securityContextOrNull(), orrequireSecurityContext()HttpServletRequest.getSecurityContext()(answerednull)HttpServletRequest.securityContextOrNull(), orrequireSecurityContext()SecurityContextHolder.context(Java:getContext())SecurityContextHolder.securityContextOrNull()SecurityContextHolder.requiredContext(Java:getRequiredContext()), which threwIllegalArgumentExceptionSecurityContextHolder.requireSecurityContext(), which throwsIllegalStateException: code that caught the other type no longer catches itA handler's
SecurityContextparameter is unchanged, and its message is now the request reader's (Web).A context bound that CoSec's pipeline did not make (one built by hand, or a mock) is still ignored (
PIP-27), but no longer silently:requireSecurityContext()says so ("A SecurityContext is bound … that CoSec's pipeline did not make, and it is ignored"), andsecurityContextOrNull()logs that sentence atWARN, at most once a minute for each reader. A test that binds such a context sees a missing or anonymous caller, or a permit where its code lets an absent context through. Grep the tests forSecurityContext.KEY,mockk<SecurityContext>and your own implementations ofSecurityContext, and bind a context the pipeline made instead (Testing your application).A check that throws reports its own cause (UA-16). Affected: code that reads the cause of a check's
Indeterminatedecision (AuthorizationChecker.decide). It isCause.CheckFailed(error), where through beta.4 it wasCause.SourceUnavailable(PLATFORM, error)whatever failed. A document the check could not read is stillSourceUnavailable. A check reaches no decision listener, so no event, audit, metric or span changes (Checks in code).A pipeline that answers API keys needs a membership provider when it is built (UA-12). Affected: applications that build a pipeline with
ApiKeyAuthenticator, alone or in aCompositeAuthenticator, and nomemberships(...).build()fails with anIllegalStateExceptionthat says to add one. Through beta.4 it built, then answered503to every key. The starter already refused such a host at startup (IDN-6).The test kit's entries are static for Java (UA-13). Affected: code compiled against beta.4 that calls
PermittedRequestorIdentityHeader. Their functions are now@JvmStatic, so the methods onINSTANCEare gone: recompile. Kotlin sources stay the same; Java dropsINSTANCE(PermittedRequest.withToken(...)).@JvmOverloadsand@JvmStaticare added toPipelineFixture's companion (load,of,unreadable),PipelineFixture.request, the constructors ofPipelineFixture.PrincipalandTokenSubject, andTokenSubject.of, which only adds.The skill
cosec-custom-matcheriscosec-extending(UE-21). 8.0 has no matchers, and the skill is about extending CoSec with beans (AttributeProvider,MembershipProvider,DecisionListener,RateLimiter,Authenticator). The directory isskills/cosec-extending, itsnameiscosec-extending, and an agent invokes it as$cosec-extending. Affected: an agent configuration, a prompt or a plugin list that namescosec-custom-matcher; nothing in a running deployment changes.The test bindings are the test kit's (the Wow drill). Affected: tests that import
CoSecTestBindings. They move out of the production jars intocosec-testkit, one for each stack:Through beta.4 From beta.5 me.ahoo.cosec.webflux.testing.CoSecTestBindings(cosec-webflux)me.ahoo.cosec.testkit.webflux.CoSecTestBindings(cosec-testkit)me.ahoo.cosec.webmvc.testing.CoSecTestBindings(cosec-webmvc)me.ahoo.cosec.testkit.webmvc.CoSecTestBindings(cosec-testkit)Change the import and add
cosec-testkitas a test dependency if the build lacks it. Its functions are the same. The WebFlux one adds a suspendingwithSecurityContext(context) { ... }for coroutine code under test, andPipelineFixture.ofandloadtake anauthenticatorof the application's own (Testing your application). The kit brings neither adapter; the bindings need the one of your web stack on the test's classpath, which a test of such a handler has.A document whose ids hold a control character, or whose DENY matches a path undecoded, no longer compiles (R1B-3, R1A-1;
DOC-13,DOC-14). Affected: documents that hold either.- Control characters in ids. No id a document writes may hold a control character or an unpaired surrogate: policy ids and statement names, binding ids and subjects, roles, catalog permission ids, declared attributes, attribute paths and path variable names (Ids and special values). Through beta.4 a policy id could hold a line break, which forged a log line on every host with a route map.
- DENYs that match the path as received. A DENY statement or a rate limit rule may no longer set
decodeAndParseSegmentstofalse: it missed every percent-encoded spelling of its path (/%61dmin/usersfor/admin/users). Remove the option; an ALLOW keeps it (HTTP paths).cosec-migrate convertrejects a 7.x DENY written so (DOES_NOT_COMPILE, at its statement) and writes no document. - What happens to a stored document. A host fails closed on it, as on any document it cannot compile: every request that needs the document answers
503, the host logsSnapshot document [<doc>] revision <n> does not compileatERRORwith each error's JSON path and the id escaped, and thecosecSnapshothealth indicator counts it ininvalid(Troubleshooting). The control plane refuses a change that would publish one: aCOMPILEfinding at the id's or the statement's path, and the change stays a draft. - Before upgrading the hosts, check every published document with beta.5's compiler, as in Policies in CI (
PolicyDocumentCompiler.validate), and publish a revision that fixes each one it refuses: ids renamed, the option removed. A document that holds neither is unaffected. - Then upgrade one host first (or the control plane's host), and read its
cosecSnapshothealth indicator'sinvalidcount and theERRORline it logs per document before you upgrade the rest of the fleet. A document nobody fixed fails closed on every upgraded host: each request that needs it answers503there.
The control plane holds every change to entry budgets, and caps a change's operations and body (R1B-4,
CTL-40,CTL-41). Affected: control planes with documents over a default budget or proposing very large changes, and WebFlux hosts that raisedspring.codec.max-in-memory-sizefor the control API. Before these budgets, a change of 100,000 entries exhausted a 512 MB heap in the control plane.- Entry budgets. The platform's
limitstakemaxPolicies(10,000),maxStatements(20,000),maxRoleBindings(10,000) andmaxAnyoneBindings(1,000) per document (Entry budgets). A change that would raise a count over its budget is aV2finding (422) naming the budget, the count and the limit, and stays a draft. A document already over a budget keeps being served by every host, may change, and may shrink; only a change that adds to an over-budget count is refused, and a check warns of each count still over. To keep a large document growing, raise the budget in the platform document first.cosec-migrate convertwarns of a converted document over a default budget and writes it. - Operations. A change a client proposes carries at most
maxChangeOperations(20,000) operations, also in the platform'slimits; a larger one is a400. Propose it as several changes.applyand rollback are not held to it. - Body.
cosec.control.http.max-body-sizedefaults to10MBinstead of16MB, and now bounds the control API on WebFlux too, in place ofspring.codec.max-in-memory-size(256 KB by default, which kept larger changes out of a WebFlux control plane). A larger body is a400invalid-request.
- Entry budgets. The platform's
An instance holds the tenants it serves (
SNP-7,SNP-14). Affected: every instance that decides, the gateway above all.cosec.authorization.snapshot.max-tenantsdefaults to 16,384 instead of 1,024. The ids an instance knows have no document now have a bound per family:max-absent-apps(256, as before) andmax-absent-tenants(65,536, where 256 was shared before). Both are properties, andSnapshotSettingshas them.- With every place used, the tenant entries take about 520 MB of heap at 30 KB a tenant document of 5 roles of 20 permissions and 20 bindings. Check your heap against Sizing a SaaS gateway, or set the two properties back. The production overlay of
k8s/now gives a gateway a 2 GiB heap and a 3200Mi limit, where it gave 1 GiB and 2Gi: room for every snapshot and revocation default at its bound. cosec.authorization.snapshot.reload-concurrencyis new, and a revalidation pass reads 16 documents at a time, not 4. The reads per interval are unchanged; a pass ends four times sooner, in a burst four times denser.- An install that takes its family over the cap evicts at most 64 entries of that kind on its own thread, and housekeeping the rest, where it evicted back to the bound.
A configured
cosec.authorization.shadow.instance-idis a prefix. The id is<instance-id>.<suffix>, with a suffix new at every start, so a restarted process never replaces the shadow reports of the one before it, which could erase aCANDIDATE_ERRORand unblock a window. Affected: a Redis ACL that names an instance's keys. Change~cosec:shadow:report:*:pod-aand~cosec:shadow:status:pod-ato~cosec:shadow:report:*:pod-a.*and~cosec:shadow:status:pod-a.*(Who may write which keys); an instance with the old lines is denied its report and status writes, which it logs atWARN.A host loads the apps it names at startup (
SNP-20). Itscosec.authorization.scope.app-idand, on a gateway, every route'scosec-app-idload withprewarm-apps, and readiness waits for them as forprewarm-apps: an instance whose Redis cannot answer for one stays not ready, retrying.prewarm-appskeeps working as before.cosec.authorization.snapshot.prewarm-host-apps=falserestores loading those apps on their first request.A host that serves the refresh route states how a refreshed token gets its memberships (
STA-8). Affected: every host that setscosec.authentication.login.refresh.path, declares noRefreshTokenAuthenticationof its own and noMembershipRefresh<RefreshTokenCredentials>bean. Through beta.4 such a host refreshed silently withMembershipRefresh.CLAIMS: a role removed from a member kept working until their next sign-in, up tocosec.jwt.session.lifetime(30 days), as long as they refreshed within the refresh token's lifetime. It now fails to start, and the message says what the choice costs. Choose one:- to keep what the host did, write
cosec.jwt.session.memberships-on-refresh: from-token(COSEC_JWT_SESSION_MEMBERSHIPSONREFRESH=from-token). Any other value fails like an absent one. Startup logs oneINFOline with the session lifetime it implies; - or declare a
MembershipRefresh<RefreshTokenCredentials>bean that reads the member's roles and attached policies again, so a removal applies withincosec.jwt.token-validity.access(10 minutes).
Either way
TokenRevoker.revokeSubjectends a member's tokens at once (How long a removed role lives). A host that serves no refresh route, or builds its ownRefreshTokenAuthentication, is unaffected.- to keep what the host did, write
The published JSON schemas have a new identity, and their files moved to
schema/8.0/(R2A-5). Affected: editors, CI checks and tools that load a CoSec schema by URL or by path, or that pinned one by its$id.- Until beta.4 each file's
$id, and the base its cross-file$refs resolve against, was the file onmainatraw.githubusercontent.com/Ahoo-Wang/CoSec/refs/heads/main/schema/<file>, so an 8.0 file resolved against whatevermainheld later. It is nowhttps://cosec.ahoo.me/schema/8.0/<file>:8.0is the release line (not theschema: 2of a document), the site serves the files, and the repository keeps them atschema/8.0/<file>. - An editor setting that still names the raw
mainURL gets a404once this reachesmain: completion and validation stop, with the editor's "could not load schema" warning. Point it athttps://cosec.ahoo.me/schema/8.0/cosec-snapshot-document.schema.json, or at the tag of the version you run (.../refs/tags/<tag>/schema/8.0/<file>from the first tag after beta.4; beta.4's own files stay atschema/<file>). A setting that names the beta.4 tag keeps working and keeps the$idit had. - Until 8.0.0 the site's
/schema/8.0/holds whatmainholds for the 8.0 line, so it changes between previews; a tag is the immutable copy (Policy language). A CI job that validates againstschema/<file>in a checkout readsschema/8.0/<file>. No document stops compiling.
- Until beta.4 each file's
The public shapes of the login, JWT, WebMvc, gateway and metrics modules are fixed before RC (R2B-1, R2B-2, R2B-4 to R2B-6, R2B-10, R2B-11, R2B-12, R2B-16, R2B-24). Affected: applications that build a
TokenSubject, aJwtTokenVerifieror aJwtTokenConverter, read the WebMvc holder, catchRefreshTokenMismatchException, or supply anAlgorithmbean.TokenSubject:tenantnow comes beforeapp.TokenSubject("alice", "acme")still compiles and now means the tenantacme, where it meant the appacme. Search for every call that passes a second positional argument and write it by name (TokenSubject(id = "alice", app = "acme")); the Java overloads are gone with@JvmOverloads.toString()no longer prints the attributes, only their number.JwtSigningreplaces java-jwt'sAlgorithmin the public constructors.JwtTokenVerifier(JwtSigning, skew)andJwtTokenConverter(idGenerator, JwtSigning, ...), withJwtSigning.hmac256(secret),hmac384andhmac512. The constructors that took anAlgorithmare internal. The starter'sAlgorithmbean is now aJwtSigningbean built from the same properties (cosec.jwt.secret,cosec.jwt.algorithm), so nothing an operator writes changes; an application that declared its ownAlgorithmbean to replace it declares aJwtSigninginstead. A signing key that is an RSA or EC key pair has no public entry yet.RefreshTokenMismatchExceptionisme.ahoo.cosec.spi.token.RefreshTokenMismatchException. Change the import. The verifier side ofcosec-jwtno longer imports anything ofcosec-login; the converter still does (TokenConverter,TokenSubject).me.ahoo.cosec.webmvc.SecurityContextHolderisCoSecSecurityContextHolder, so that it is not taken for Spring Security's.requireSecurityContext()andsecurityContextOrNull()keep their names.- Starter-only classes are internal: the constructors of
IdentityStripFilter,IdentityHeadersFilterandOrderedCorsWebFilter, and the filter-order and attribute constants of the filters. The starter registers them. MetricsListener.bind(...)and its constants moved toCoSecMeters(internal: the starter registers them).MetricsListenerkeeps its name,cosec.authorizationand the four tag names. A meter's name and tags are unchanged.- A refresh strips
Bearerfrom the refresh token too, as it did from the access token. The Kafka audit listener logs failed sends once every 10 seconds with a count; a closed sender says it is closed.
The social sign-in states are
cosec-spi'sSocialStateStore, on Redis incosec-cocache; sign-in starts are bounded; an unknown principal is remembered briefly (R2B-3, R2B-23, R2C-18).SocialStateStoreandInMemorySocialStateStoremoved tome.ahoo.cosec.spi.social. If you implementSocialStateStoreor build the in-memory one, change the import: the interface is unchanged (putandtake, both suspending).RedisSocialStateStoreis nowme.ahoo.cosec.cocache.RedisSocialStateStore, over the non-blocking client andGETDEL, internal to the starter (its constructor takes aReactiveStringRedisTemplateand no longer a parallelism). The keys are the same,<s>:oauth:binding:<state>, so states in flight survive an upgrade.- Social login needs
cosec-cocache(or aSocialStateStorebean of your own): startup fails naming the artifact without either (STA-1).cosec-socialno longer bringsspring-data-redisto your compile classpath; JustAuth's own state cache still blocks and needs aStringRedisTemplate, which your application has when it uses Redis. authorizerefuses what it cannot take at once. EachJustAuthProviderhas at most 64 sign-in starts in flight, on a pool of its own beside the login's; one more throws aSocialAuthenticationExceptionwhere it used to queue without bound.cosec.authorization.membership.unknown-ttl(default5s, at most1m,0sfor the old behaviour): an instance remembers that yourMembershipLoaderansweredUnknownfor a principal, so a removed member's token no longer reaches the loader on every request. A principal you add is known when that time ends on the other instances, and at once whereinvalidateran. A failed load is never remembered.
The control API answers less and refuses more (R2C-32, R2C-33, R2C-34).
simulateandexplainname a statement only to a caller who may read the document that defines its policy. A tenant administrator whose tenant binds a platform policy, or an app's permission policy, no longer sees that policy's statements, in the decision or in the trace: the decision says"redacted": trueand the trace counts them. Before, the document of the binding decided it, which a tenant administrator reads. A caller who may read the defining document (a platform operator) sees what they saw.- A section operation with an
ifMatchis a400.putCatalog,setLimits,setAttributesandsetBoundaryreplace a section, which has no digest of its own; they accepted anifMatchand ignored it. The change'sbase, the digest of the document it was proposed on, guards the document. Remove the member. Each operation also takes only its own members now:removePolicywith apolicy, for one, is an unknown member. - A change is checked, analysed and approved on the document the data plane reads: the candidate as written and read back, not as the operations built it. No change of outcome is expected: the two are the same unless the format codec fails to round-trip a member.
A cold load waits for a full compile pool;
fail-closed.tenantstakes*; the local rate limiter bounds each document's rules (R2D-3, R2D-4, R2D-5). No document, property default, stored value or wire format changes.- A cold load that the full compile queue refuses no longer answers
503at once. It compiles again every few milliseconds untilcold-load-timeout(2 s), then fails closed as before. On a new replica, a burst of tenants queues instead of being refused (What a new replica costs). cosec.authorization.snapshot.fail-closed.tenants: "*"fails every tenant closed pastfail-closed.max-lag. The default stays empty.LocalRateLimiterholds at most a quarter of its buckets for the rules of one document, and counts each bucket it refuses incosec.ratelimit.local.refused. Its constructor takesmaximumBucketsPerOwneraftermaximumBucketsPerRule: code that calls it with named arguments compiles unchanged; code compiled against beta.4 that constructs one must be compiled again.
- A cold load that the full compile queue refuses no longer answers
A
TokenVerifierbean turns token authentication on without acosec.jwt.secret(review round 2,R2D-7). Affected: applications that declare their ownTokenVerifierand have no CoSec signing key (cosec.jwt.enabled=false).- Before, tokens were on only where a signing key existed: such an application's authenticator refused every request that carried a token (
token-invalid), whatever its verifier said, and the application had to set a secret it never used. Now tokens are on when aTokenVerifierbean or a signing key exists. A verifier alone issues nothing: the login and refresh routes and the token converter still come with the key. - A verifier alone needs a revocation reader: a
RevocationReaderbean, orcosec-cocacheon the issuer's Redis. Without one, startup fails with a message naming it, instead of every token being refused.RevocationReader.NONEaccepts revoked tokens until they expire. - If a
TokenVerifierbean was declared for another purpose and its tokens were meant to stay refused, remove the bean: with no verifier and no key, a request with a token is stilltoken-invalid.
- Before, tokens were on only where a signing key existed: such an application's authenticator refused every request that carried a token (
From 8.0.0-beta.3
The policy test kit refuses a run that could pass for the wrong reason (
PolicyTestKit, experimental; UC-7).loadfails without aplatform.json(write an empty document there to test without one) and when the directory holds a file or directory the kit would not read. A scenario names itscredential(tenantandid, or"anonymous": true) and its request'sactionandresource: the example defaults (acme,alice,order:read,order/1) are gone. Among tenant documents, a scenario decided in a tenant without one fails, and among app documents one in an app without one, unless it says"withoutDocument": ["tenant"]or["app"](Testing decisions). Affected: scenarios that relied on the defaults or on a misplaced document;PipelineFixture.loadreads a directory by the same rules. Name the fields, move the files.The
cosec-gateway-serverimage: no JMX agent, the actuator on a management port, and the image's defaults kept under a mounted file (UB-2,UB-21). Affected: whoever runs the image. A service on one preview of the library behind a gateway image of another: Upgrading a running deployment.- Through beta.3 the start script started a JMX agent on port 5555 with no authentication, on every interface. It no longer starts one. To attach, set it in
JAVA_OPTS, bound to loopback (the image); the-Dcom.sun.management.jmxremote.host=127.0.0.1the Kubernetes base set is gone with it. - The actuator is served on the management port
8081(management.server.port), no longer on8080:/actuator/health/*on 8080 is404. The probes are now/livezand/readyzon 8080 (the same groups, served on the gateway's own port, not decided by CoSec);/actuator/healthand/actuator/prometheusare on 8081. Change a probe or health check of your own to/livezand/readyz(the image'sHEALTHCHECKand thek8s/manifests did), and publish 8081, if you scrape it, to a monitoring network only. - The image has
cosec-micrometerand a Prometheus registry (Micrometer 1.17.2, from Spring Boot's dependency management):cosec.authorization,cosec.snapshot.*and the others are on/actuator/prometheus. - The image's defaults are now in its jar, and a
config/application.yamlyou mount is read in addition to them, key by key; it used to replace them (Kafka audit, login and ip2region came back on). A file that set what it needs is unaffected; one that left the defaults out now gets them. A list such asroutesis still replaced whole. k8s/base: the demo CORS origin is a placeholder (https://app.example.com, no longer*;max-ageis in seconds), the demo route and discovery list are marked, the container has amanagementport, and the production NetworkPolicy admits it from themonitoringnamespace only.
- Through beta.3 the start script started a JMX agent on port 5555 with no authentication, on every interface. It no longer starts one. To attach, set it in
A
cosec.*switch whose value CoSec cannot read fails startup (UB-1). Through beta.3 a value such ascosec.enabled=1,on, an empty string ortruewas true to Spring's binder and "off" to the condition that wires the beans, so CoSec, or the feature, was switched off without a word; an emptycosec.pipeline.modewired no pipeline, and a Spring Cloud Gateway host started as an open proxy.cosec.authorization.shadow.enabled=off(or0) left shadowing on. Now the starter refuses, before any bean, every switch that is nottrueorfalse(any case, no surrounding spaces;cosec.pipeline.modeacceptsenforceorgateway,cosec.api-key.storememoryorredis), naming the key, the value found and the values accepted (Startup fails on an unreadable switch). Affected: a configuration, an environment variable or a Helm value that writes a switch another way. Writetrueorfalse, or remove the key to take its default. A switch writtenfalsestill switches its feature off.The
cosec.authorizationtimer has aproblemtag, and every series has the same tag keys (UB-8). The new tag holds the slug of the problem the client was told (unauthorized,token-expired,forbidden, ...) ornone, so a401tells apart from a403and one token problem from another (Metrics). Thecausetag, which onlyindeterminateseries had, is now on every series,noneoutsideindeterminate: a Prometheus registry refuses meters of one name with different tag keys. Affected: a query that selects series by the absence ofcause(cause="") now selectscause="none"; a sum over the new tags is the old series.One vocabulary for what decided: metrics, audit and the decision event's method (UD-7, UD-11). Through beta.3 each output named a decision its own way, and an alert on explicit denies also counted requests no DENY statement refused. Now every output takes the decision event's words (What decided, in every output):
Output Before (beta.3) Now cosec.authorizationresultallowpermitexplicit_denyfor a DENY statement, a scope rejection and a boundary refusalexplicit_deny(a DENY statement only),scope_rejected,boundarybad_requestinvalid_requestAudit authorization.decisionALLOWPERMITEXPLICIT_DENYfor a DENY statement, a scope rejection, a boundary refusal and a400EXPLICIT_DENY,SCOPE_REJECTED,BOUNDARY,INVALID_REQUESTAudit authorization.reasonCodeALLOW;EXPLICIT_DENYfor a400;TOKEN_INVALIDfor a token not valid yetPERMIT;INVALID_REQUEST;TOKEN_NOT_YET_VALIDDecision event subject.methodtokenfor every token,apikeyjwt(CoSec's own token),api-key, another verifier's name (tokenby default): whatCoSec-IdentitysaysThe timer changes together with the
problemtag and thecauseon every series (the entry above): migrate a dashboard once, for both. Affected: dashboards and alerts onresult="allow", onexplicit_denycounts (they now count fewer requests: addscope_rejectedandboundaryto keep the old total), onbad_request; audit consumers (the log, Kafka records) matchingALLOWor expectingEXPLICIT_DENYfor the three other kinds; decision listeners matchingsubject.methodtokenfor CoSec's token orapikey.ApiKeyAuthenticator.METHODisapi-key.AuditDecisionandAuditReasonCode(cosec-api) loseALLOW: recompile against this version.New log lines (nothing to change): one INFO summary of what CoSec is configured as, and one WARN when
cosec.enabled=false(Startup summary); a WARN, repeated everylag-warn, while the platform document is absent, naming the key, the key prefix and the Redis it reads (Instance is not ready); a WARN on a Spring Cloud Gateway host that has controllers or functional routes of its own, which CoSec does not decide (Web); and the client-address line now says what the defaultmax-trusted-indexrisks.Mapped routes that escape
http:statements are reported (UC-1; nothing to change). A platform DENY or rate limit rule onhttp:*stops applying to a path once a route map maps it. A host with a route map now logs one WARN for each document revision it installs that holds such statements, naming them (What CoSec warns about); a review it could not run is counted incosec.snapshot.housekeeping.refusedundertask="install-review". The control plane, given the services' route maps in the new optionalcosec.control.analysis.route-maps, adds aROUTESwarning to a change whose candidate holds them (Validating policies).IdentityHeaderincosec-testkit(#1656, experimental; nothing to change) writes theCoSec-Identityheader a gateway forwards, with CoSec's own encoder, for a test of a service behind a gateway or a local client:of,forSubjectandwithToken(Testing your code against a real pipeline).Security: a check of a request that has ended is denied (
PIP-26). Through beta.3, aSecurityContextkept after its request (in a field, a cache, a message to a consumer) went on permitting withAuthorizationChecker, on the memberships it was made with, after logout, a revoked token or a removed role. Now the adapter that bound the request ends it when the request completes, and every check of it afterwards isfalse(decideanswersDeny(null)). A request in progress is answered as before, however long it runs: a streamed or server-sent-events body, an async servlet request. Affected: code that keeps a context and checks with it after the response was written. Check within the request instead; work that runs afterwards (a consumer, a scheduled job) carries its own authorization (Checks in code). A context of a request your own transport handed toPipeline.evaluate, and the test kit's, is ended only when you end it: close theOutcome, or callPipelineFixture.end/PermittedRequest.end(below).Security: the readers of the security context answer only a context the pipeline made (
PIP-27).exchange.getSecurityContext(),ContextView.getSecurityContextOrEmpty()/getSecurityContext(),request.getSecurityContext(), theSecurityContexthandler parameter andSecurityContextHolderreturned whatever object sat underSecurityContext.KEY, so an application filter or a library that wrote its own was taken for an authenticated caller. Now anything else reads as no context:null, or the failure an unbound context is. Affected: code, test code above all, that binds aSecurityContextit made itself (a mock, an implementation of the interface) under that key. In a test, use a context the pipeline made and let the adapter's test entry put it in place (Testing your application): a handler test runs behind CoSec's own filter,CoSecTestBindings.filter(fixture.pipeline)(cosec-webflux,cosec-webmvc), with a fixture principal'sAuthorization; a unit test bindsPermittedRequest.forSubject(...)(orwithIdentity,withToken) withCoSecTestBindings.withSecurityContextorbind. A filter of your own that runs the pipeline bindsoutcome.security!!.securityContext.Such a test does not always fail loudly. The context it bound reads as no context, so the code under test sees a missing or anonymous caller (a
401, a refused handler); and where your code lets an absent context through, for example as "a command with no request of its own", it gives a permit the test did not expect: a test that expects a denial sees an allow. Search your tests forSecurityContext.KEY,mockk<SecurityContext>and every class that implementsSecurityContext.Breaking: three shapes of a document that never did what they read no longer compile (
DOC-9,DOC-10,DOC-11). Each refuses a document whose statement already did not apply as written:ignoreCaseoneqorprefixwith a literal holding a letter beyond ASCII (Ärzte), where missing a spelling lets a request through: in a DENY statement or a rate limit rule, an ALLOW under anot, or a policy condition guarding a DENY. The fold is ASCII only, soärztepassed the DENY. Write every spelling in aninwithoutignoreCase(Case folding). In an ALLOW it still compiles, with a warning.resource.attributes.<name>, in a condition or a rate limitkey: nothing sets it, so a DENY on it denied nothing. Put the fact in the resource id and read it asresource.var.<name>(Object-level rules). A test kit scenario that setsrequest.resource.attributesis refused too.- A
subject.idliteral beginning with(({"not": {"eq": ["subject.id", "(0)"]}}matched every anonymous request) and a principal binding to an id beginning with((it never applied). Write{"eq": ["subject.authenticated", false]}for anonymous requests.
Affected: whoever stored such a document. After the upgrade an instance installs it as failed, and every request that reads it fails closed (
503), so find them first. With beta.3 still running, read each head (GET <control base>/documents/{key}, the control API) or take the files you publish from, and search them:grep -nE 'resource\.attributes\.|"subject\.id" *, *"\(|"principal" *: *"\(' <files>finds the second and third shapes; for the first,grep -n '"ignoreCase": *true' <files>and look for a letter beyond ASCII beside it (grep -nP '[^\x00-\x7F]'). Or load the files with this version'sPolicyTestKit.load, which compiles each document as an instance does and names the path of each error.cosec-migrate convertnow refuses the same shapes from 7.x data: an ALLOW on a 7.x resource attribute is a statement that can never hold, which you remove.Breaking:
:applywithREPLACEchecks the revision the file was read at. Through beta.3 the header'srevisionwas required and ignored, and aREPLACEremoved whatever the head held that the file did not, including what was published after the file was read. Now a file whoserevisionis not the head's is a409. Affected: jobs that apply a file from git with a fixed or stalerevision. Send the revision the job last read (GET /documents/{key}, itsrevision), merging what changed since (Changes). A document not published yet is not compared.MERGEis unchanged, and its change now names, in aWARNING, the entries it keeps because the file leaves them out.A change that would lock its publisher out of the control plane needs an acknowledgement. A change to the platform document, the platform tenant's or the control app's that would leave its operator unable to reach the control plane carries a
V4warning, and its publish is a422unless the body says"lockout": true(Publishing and rolling back). Affected: automation that publishes such a change on purpose; add the acknowledgement. The way back from a lock-out is the newcosec-migrate restore, not an emptied Redis (Recovering from a lock-out).Fixed: a lost invalidation is installed by the first pass after it, even past a load in flight. The beta.3 release notes listed it as a known issue: when a revalidation pass met a load of a document already in flight, it took that load's read as its confirmation, though the read could predate the change, so a change whose invalidation was lost could take two
revalidate-intervals to install, and decisions used the previous revision meanwhile. A pass now joins only a load that started after it, and otherwise waits for one more load (SNP-6, Storage). Nothing to change; Redis may see one more conditional read of a document when a pass meets its load.The
cosec-gateway-serverimage turns ip2region off. Itsconfig/application.yamlnow setscosec.ip2region.enabled: false, as the Kubernetes base already did; through beta.3 the image left it on. A document that readsext.ip2region.*no longer compiles on it: setCOSEC_IP2REGION_ENABLED=truebefore you upgrade the image. Its DockerHEALTHCHECKnow probes/actuator/health/liveness, so a gateway that waits for its platform document is no longer reported unhealthy.@ahoo-wang/cosec-react:logoutends the session at the server.useSecurityandSecurityProvidergain thetokenManageroption (theJwtTokenManagerof the sameTokenStorage, with atokenRevoker) andlogout(), which calls the server's logout and then removes the pair here (Building a client).signOutis unchanged: it removes the pair here only, and the session stays refreshable at the server until its refresh token expires. Nothing breaks; point the user's "Log out" atlogout.Security: whoever builds a
TokenAuthenticatornames its revocation reader (IDN-27). Through beta.3,TokenAuthenticator(verifier)compiled and read revocations fromRevocationReader.NONE: an authenticator an application built itself (a customAuthenticatorbean, a pipeline outside Spring) accepted every revoked token until it expired, after logout orrevokeSubject, and nothing warned. The parameter has no default any more, and neither hasPermittedRequest.withToken's (cosec-testkit). Affected: code that builds either without a reader; it no longer compiles. Pass the reader of theTokenStoreyour logout writes to (the starter'sRevocationReaderbean), orRevocationReader.NONEwhere nothing is ever revoked, such as most tests. Binary compatible; the starter is unchanged.RefreshTokenAuthentication(verifier, revocation, families)names itsMembershipRefresh(IDN-27). The factory defaulted toMembershipRefresh.CLAIMS, which keeps the roles the old token claimed, while the KDoc ofMembershipRefreshsaid the opposite. Its KDoc now says what happens, and the factory has no default. Affected: code that calls the factory with three arguments; it no longer compiles. AddMembershipRefresh.CLAIMSto keep today's behaviour (a removed role applies at the next sign-in or afterrevokeSubject), or aMembershipRefreshthat looks the user up again. The starter's refresh route still usesCLAIMSunless you declare aMembershipRefreshbean. The syntheticRefreshTokenAuthentication$defaultmethod is gone fromcosec-login: recompile against this version.Security:
JwtTokenVerifierandJwtTokenConverterrefuseAlgorithm.none()(IDN-28). java-jwt'snoneaccepts any token with an empty signature, so a verifier built on it took tokens anyone can write for CoSec's own, break-glass included. Both constructors now throwIllegalArgumentException. Affected: code, test code above all, that builds either onAlgorithm.none(). Pass a signing algorithm, such asAlgorithm.HMAC256(secret).CoCacheTokenStore.revokerefuses a token given for its id.TokenStore.revoke(tokenId, ttl)takes a token's id (VerifiedToken.id, itsjti); a logout that passed the access token there revoked nothing and wrote the token as a Redis key. Now a value shaped like a token (a JOSE compact serialization, with or withoutBearer) throwsIllegalArgumentException, which namesTokenRevoker; no token id CoSec or another issuer gives is refused. Affected: a logout written againstTokenStore, which never worked. CallTokenRevoker.revoke(accessToken).A pipeline built with
Pipeline.buildercounts rate limits (UA-10). Through beta.3 a pipeline built withoutrateLimiter(...)had none: a rule withstrictFailureanswered every request it covered503, and every other rule was skipped. It now counts in aLocalRateLimiterof its own, as the starter's default does, and a request over a rule's limit is429.PipelineFixture.ofandloadcount the same way and take arateLimiter, so a test sees the429(pass aLocalRateLimiterwith a clock of the test's to cross a window). Affected: a pipeline outside Spring, and tests, whose documents have rate limit rules: they are limited now. GiverateLimiter(...)a limiter shared across instances to limit a service as a whole. The starter is unchanged.PipelineFixture.ofandloadgained a parameter: recompile tests against this version.A transport of your own can end its requests (
PIP-26).OutcomeisAutoCloseable: close it when the response is complete (pipeline.evaluate(facts).use { … }), or from the response's completion callback when it outlives the handler, and every later check of its context isfalse(Pipeline outside the adapters). In tests,PipelineFixture.end(context)andPermittedRequest.end(context). Nothing breaks: a transport that does not close it behaves as before.A check refused for how it was called is logged (UA-5). A context the pipeline did not make, a check after its request ended and a malformed action string still answer
false(Deny(null)), and now log aWARNonce a minute per kind, naming the request (Troubleshooting). Nothing to change.The request's
Principalis CoSec's if and only if CoSec authenticated the request, on every stack (PIP-28). Through beta.3, WebFlux and the gateway gave an anonymous caller the anonymous principal(0)asexchange.getPrincipal()and as ajava.security.Principalhandler parameter, so code that took "a principal is present" for "signed in" counted every anonymous caller as one user; Spring MVC set none at all. Now:- WebFlux and the gateway set none for an anonymous request. Affected: code that expects a principal for anonymous callers (an
exchange.principal.map { … }that now completes empty, a non-nullPrincipalparameter). - Spring MVC sets CoSec's principal for a signed-in request:
getUserPrincipal()is it,getRemoteUser()its id, and aPrincipalhandler parameter is no longer null. It replaces a principal the container or a filter in front (Spring Security) had set; on a request CoSec treats as anonymous, that one is left as it was.isUserInRoleisfalseandgetAuthType()nullon a request CoSec authenticated. Affected: servlet applications that readgetUserPrincipal()orgetRemoteUser()(they now get CoSec's caller for signed-in requests) and ones that askisUserInRolebehind CoSec (ask CoSec through a check instead).
Read the caller from the
SecurityContext(principal.authenticated,principal.id), the same on all three (Web).- WebFlux and the gateway set none for an anonymous request. Affected: code that expects a principal for anonymous callers (an
Fixed: a token from an issuer whose clock runs ahead is accepted (#1666,
IDN-29). Through beta.3,JwtTokenVerifierallowed no room for clocks: a token whoseiatwas even milliseconds later than the verifier's clock was401 token-invalid, so a deployment whose issuer and gateway do not share a clock saw intermittent401s in the last milliseconds of a second. A token'siatandnbfmay now be up tocosec.authentication.revocation.skew(5 seconds) ahead;expstays strict. A token beyond the skew is stilltoken-invalidto the client, and the decision event names itTOKEN_NOT_YET_VALID(a new member ofAuthnResult.RejectReason, a set that grows; awhenover it already has anelse); the log saysToken refused as not valid yet.JwtTokenVerifier(algorithm, issuerSkew)takes the skew, the starter passescosec.authentication.revocation.skew; a verifier you build yourself defaults to 5 seconds, so pass the value yourTokenAuthenticator'srevocationSkewuses if you changed it. Nothing breaks.What the host logs at startup. Nothing breaks, but the log an operator reads changes. A
cosec.*property CoSec does not read fails startup before any bean is created, so a configuration with removed keys hears of every one first. When tokens are verified againstRevocationReader.NONE, the host logs aWARNthat says a revoked token is accepted until it expires. When the token stores are missing, one startup message names every store that is missing, not the first.Testing an application (#1679,
PIP-29, nothing to change).PermittedRequest.forSubject(subject, tenant, app, space, roles)makes a signed-in caller's context with no token and no documents, the samePipelineFixturemakes;PermittedRequest.withIdentity(header)makes the one a service behind a gateway reads.CoSecTestBindings(cosec-webflux,cosec-webmvc, packagetesting) runs CoSec's own filter over a test pipeline, or binds a kit context in the Reactor context, the exchange, the request orSecurityContextHolder, refusing a context made by hand.PipelineFixture.authorization(principal)is a fixture principal'sAuthorizationfor a request a test builds (Testing your application).
From 8.0.0-beta.2
Security: a revocation table keeps "not revoked" for 30 seconds at most. Through 8.0.0-beta.2 the
absent-ttlofRevokedTokenCacheandRevokedSubjectCachewas not locked, sococache.caches.RevokedTokenCache.absent-ttl, acocache.defaults.store.absent-ttlor a customizer could lengthen it, and an instance that missed an invalidation accepted a revoked token for that long. It is now CoSec's, 30 seconds: acocache.caches.[name].absent-ttlfor either table fails startup (remove it), and the global defaults and customizers no longer reach it.Security: requests verify with the application's
TokenVerifier. Through 8.0.0-beta.2 the starter's pipeline verified request tokens with CoSec's ownJwtTokenVerifier, even when the application declared aTokenVerifierbean, which refresh and logout did use. Now a request, a refresh and a logout verify with the same one (IDN-25). What changes depends on your verifier:- A verifier of another issuer's tokens now works on requests as it always did on refresh.
- A verifier that wraps CoSec's own (
JwtTokenVerifierand a check of yours) makes its tokens not CoSec's on every request: the principal's credential istoken, notjwt, it has no session, so no tenant switch from that request's session and no session forwarded by a gateway, and it never gets break-glass. Through beta.2 its requests had all three. Leave such a verifier out unless that is what you want.
Nothing changes for an application without its own
TokenVerifier.Security: the served refresh route uses your
RefreshTokenAuthentication. Through 8.0.0-beta.2 the route built its own and used only aMembershipRefresh<RefreshTokenCredentials>bean, so a hook declared inside yourRefreshTokenAuthenticationbean (refusing a disabled user, say) did not apply to it. Now your bean serves the route. One over a credentials class of your own fails startup whilecosec.authentication.login.refresh.pathis set: serve that refresh from your own route and unset the path, or declare it overRefreshTokenCredentials.A session store that fails or cannot do a call. A store that fails in
TokenRevoker.revokeSubject(Redis down, say) now throwsSessionStoreUnavailableException, asrevokealready did: answer503and revoke again. Code that caught the store's own exception aroundrevokeSubjectcatchesSessionStoreUnavailableExceptioninstead. A session store that throwsUnsupportedOperationException, because it cannot do the call at all, now passes it through on every session-store call (login, refresh, tenant switch, logout and both revokes), where it used to leave asSessionStoreUnavailableException: it is configuration, not an outage. On the served refresh and logout routes that is500where it was503.
From 8.0.0-beta.1
- Before upgrading: add
+evalsha_ro +eval_roto every data-plane Redis user whose commands are restricted. An instance that does not run the control plane now reads the documents and the candidates read-only, asEVALSHA_RO(Redis 7.0 or later, which CoCache 8 already requires). With a user that lists its commands, such as the one beta.1's Who may write which keys showed (-@alland then+evalsha +evalamong others), the upgraded instance fails at startup:Read-only store of Keyspace(...): Redis denied the command [evalsha_ro]: allow [+evalsha_ro] .... Add the two commands first; a user without a command list (+@all) needs nothing. Narrowing the documents and the candidates to read permission (%R~<s>:snapshot:* %R~<s>:candidate:*) is optional, and the page shows it. A process that runs the control plane is unchanged: it still writes them. cosec.control.enabledswitches the control plane off on an instance (an addition: nothing to migrate; the default,true, changes nothing). An image that carriescosec-controlfor both roles setsCOSEC_CONTROL_ENABLED=falseon the data-plane role: it runs no control plane, reads the documents and candidates read-only, and can use the read-only user of Who may write which keys. A value other thantrueorfalsefails startup.- The starter can serve the refresh and logout routes (an addition: nothing changes until a path is set).
cosec.authentication.login.refresh.pathandlogout.pathserve them on Spring MVC and WebFlux, with the statuses and bodies of Building a client. A route you wrote keeps working: unset the path and nothing is served. To move onto the served one, set the path your clients call, delete your handler and its exception mapping, and keep the statement that permits an anonymousPOSTof it. - A failure of the session store leaves
TokenFamiliesandStoreTokenRevokerasSessionStoreUnavailableException(cosec-login), with the store's own as its cause, so that a store that cannot answer (503) is told apart from an error (500). Code that caught the store's own exception type around a refresh, a switch or a logout catches it instead.StoreTokenRevoker.revokeSubjectis unchanged. MembershipRefreshrefuses with aTokenVerificationException(TokenRevokedExceptionwhen the membership is gone), a401; any other exception is an error,500on the served route, and the client keeps its pair. A hook that refused with another exception, such asIllegalStateException, throwsTokenRevokedExceptioninstead.- The snapshot source runs each document key through its own runner (nothing to migrate, no API or property change; decisions are unchanged). What an operator sees differs:
- A request made while its document is loading, and taken only after that load ended, is served the installed document as a hit, where beta.1 joined it to the load as a cold one: the same document, but one fewer
cosec.snapshot.loads{result=cold}. - A store read that answers "absent" after
closeended its load is not reported: a closed instance no longer logsSnapshot document [<doc>] disappeared from the store; failing closed.or countscosec.snapshot.lostfor it. One abandoned at the store read timeout (30 seconds) that answers "absent" late is reported by the document's next load, not at once. - The bound on ids without a document holds without a gap (How instances read documents): an eviction pass skips an entry that is loading, and when that load finds the document still absent, the entry now asks for the bound itself. In beta.1 the family stayed above that bound until some later install.
- When the platform document changes and every document is recompiled, a document whose load was in flight may be loaded once more: at most one extra read of the store per document.
- Each document held costs about 64 bytes more heap, and each cold load allocates about 1.2 KB more.
- A request made while its document is loading, and taken only after that load ended, is served the installed document as a hit, where beta.1 joined it to the load as a cold one: the same document, but one fewer
- The snapshot source is metered (an addition: nothing to migrate). With
cosec-micrometerand aMeterRegistry, the data plane's snapshot source now registers thecosec.snapshot.*meters: 80 new series, whatever the number of documents, since no tag carries an app or tenant id. A request that finds its documents installed is not counted: only the loads a request had to wait for.cosec.metrics.enabled=falseturns them off with the rest of CoSec's metrics. The meters and what to alert on are in Snapshot metrics. - What the snapshot source's housekeeping thread refuses is dropped and counted (
SNP-19; nothing to migrate). That thread writes the source's log lines and runs its eviction passes; its queue holds 4,096 tasks. When the queue was full, beta.1 ran the refused task on the thread that offered it, often a request's, so a slow log appender slowed requests. Now the task is dropped and counted incosec.snapshot.housekeeping.refused{task}, and the thread writes oneWARNat most every 10 seconds,Snapshot housekeeping since its last summary: refused <n> tasks, full or stopped …, naming the last line dropped for each task without its stack; a closing instance writes what is left once. A meter that throws is counted in the same line instead of logged. Nothing to do, unless the summary appears: then use an asynchronous log appender (Snapshot log lines are missing), and alert on any rise of the counter.
From 8.0.0-alpha.4
If you published documents cosec-migrate convert wrote with any preview, check their ALLOW statements (the first entry below): a converted 7.x "every action" granted the control plane. 8.0.0-alpha.4 is a preview with no compatibility promise. Every token issued before this version declares no app, so a service with an app refuses it (below): plan a re-login, or have tokens expire first. API keys stored in format 2 fail and have to be provisioned again. Close or withdraw open shadow windows before you upgrade: a candidate staged by 8.0.0-alpha.4 states its header beside its document, and is refused as unreadable, so its window is not compared.
The revision index entries gain a
parent, and the first read of each document rewrites an index an alpha wrote (CTL-35). An entry of<s>:control:revisions:<doc>carries the digest its document names as its parent, and a document's history is returned only when its last entry is the head and each entry names the one below it. An index written before has noparent: the first read of each document (a control API call, or the maintenance pass) walks the head's chain once, decoding each retained record, and rewrites the entries with it; no migration is needed, and nothing is lost.RevisionEntry's constructor has a fourth parameter,parent(defaultnull), for code that builds one. The same read repairs a head that moved back and a reused revision number, which used to read the old branch's document; see Revisions, history and rollback.Security: a tenant switch no longer issues from a revoked or ended session. From 8.0.0-alpha.1 to 8.0.0-alpha.4, a switch read no revocation itself: while the revocation store could not be read, which the request path then read as "not revoked", a logged-out token, or one of a revoked principal, could be switched into a new token that no revocation names. Sessions came after 8.0.0-alpha.4, and until this change a switch also started a live session from a token whose own session was revoked: by a pair presented again after a refresh (
IDN-16), whose access tokens stay valid for up tocosec.jwt.token-validity.access(10 minutes), or by a logout. Whoever copied a pair and refreshed first could so hold a session until the user's would have ended, up tocosec.jwt.session.lifetime. That was in no preview. A switch now issues only from a live session and reads revocations strictly, in the one check a refresh makes too (IDN-22,IDN-14): from a dead session it answerstoken-revokedortoken-expired, and 503 while a store cannot be read. A token a preview's switch issued during an outage of the revocation store is not revoked by the revocation it escaped; if one may have been, revoke the principal.Security: a converted 7.x "every action" no longer grants the control plane. From 8.0.0-alpha.1 to 8.0.0-alpha.4,
convertwrote an ALLOW of every 7.x action as"action": "*", which also matches every control-plane action (cosec:*) and every action of a check in code. A converted global policy such as "signed-in users may do anything" gave every authenticated principal every control-plane action on its own tenant's document, and a principal of(platform)on the platform's and the app documents. An attachable one did the same for every token that lists it. Such a principal could write and grant in that document, and another holding the same grant could approve it.convertnow writes"action": "http:*"(Every action is every HTTP request); a DENY of every action stays*. If you published converted documents:Find the ALLOW statements on
*in each document (platform,app:<id>,tenant:<id>). An administrator reads the head through the control API (Revisions, history and rollback):bashcurl -s "$CONTROL/documents/platform" -H "$AUTH" \ | jq -r '.policies[] | select(any(.statements[]; .effect == "allow" and ([.action] | flatten | index("*")))) | .id'The ones
convertwrote are in the conversion'splatform.json,apps/andtenants/, and itsprovenance.jsonnames the 7.x policy of each. A statement on*you wrote yourself after the upgrade is yours to keep.Change each converted one to
http:*through the control plane: a change that puts the policy again with"action": "http:*". If a document has not changed sincepublish,applythe file a newconvertwrites for it instead; the change it proposes is exactly those statements.
Tenant and app ids hold no
/(SCP-13). An 8.0 preview acceptedacme/westas a tenant id anda/bas an app id; this version refuses them at every entry, so a preview deployment that stored one must remove its records before upgrading. Find them withGET /documentson the preview: any key with/aftertenant:orapp:. The preview's own control plane cannot remove them, since it refuses such ids too. Stop the control plane, then, for each such document<doc>(tenant:acme/west), delete these Redis keys under<s>(Redis keys):<s>:snapshot:<doc>(the head) and<s>:candidate:<doc>(a staged candidate);<s>:control:revisions:<doc>and every<s>:control:revision:<doc>:*(the revision index and records);- every
<s>:control:refs:<doc>:*(back-references to its policies); <s>:control:stage:<doc>and<s>:control:lease:reclaim:<doc>;- every
<s>:control:change:<id>whose"key"is<doc>, and its id in<s>:control:list:open-changes; - the entry
<doc>in<s>:control:list:documents, and, for an app, its entry in<s>:control:apps:all; - every
<s>:api-key:<sha256>whose"tenantId"or"app"holds/.
Then delete each
<s>:control:refs:*set that names<doc>among its referrers, and runrepair-references, which writes back what the remaining heads refer to. Until this is done, this version fails whole on each such record and names it (SCP-10): a back-reference set fails the publish over its policy, a change answers503, an open change stops every maintenance pass, and an API key fails its lookup (503). An instance status of a preview that installed such a document fails the shadow windows' statuses until it expires, two minutes after that instance stops (the time to live of its status key,ShadowCacheSpecs.STATUS_TTL). Rename the tenant or app and publish its documents under the new id; tokens of the old id are401 token-invalid(Tenant and app ids hold no slash).No CoSec module imports a platform, and
cosec-dependenciesis no longer published (R11). Until now every library module's POM and Gradle module metadata importedcosec-dependencies, which imports the Spring Boot, Spring Cloud, CoCache, OpenTelemetry, springdoc and fluent-assert BOMs and manages jmh, mockk, archunit, blockhound, json-schema-validator and detekt-formatting, so adding one module raised those versions in the whole build of an application,cosec-cocache's CoCache 8 over an application's CoCache 4 included. Now a module's metadata names the libraries it needs with the versions it was built with, as minimums, and nothing else; Maven no longer needs the import to resolve them. An application that importedme.ahoo.cosec:cosec-dependenciesremoves the import and manages the versions it wants itself (what CoSec needs from your build).cosec-bomlists the CoSec modules an application can depend on, withoutcosec-migrate, and imports nothing. The POMs ofcosec-cocacheandcosec-kafkamarkcosec-controlprovided: a Maven application that uses the control plane addscosec-control, which they used to bring (withcosec-runtime) to run time.Three packages follow their modules' names.
me.ahoo.cosec.cache(cosec-cocache) is nowme.ahoo.cosec.cocache,me.ahoo.cosec.servlet(cosec-webmvc) isme.ahoo.cosec.webmvc, andme.ahoo.cosec.spring.boot.starter(cosec-spring-boot) isme.ahoo.cosec.spring.boot. Sub-packages keep their names under the new root; no class, artifact id,cosec.*property, bean name or Redis key changes. In an application, change the imports; the names of auto-configuration classes inspring.autoconfigure.excludeand in@ConditionalOnClass(name = ...)strings (me.ahoo.cosec.spring.boot.starter.CoSecAutoConfigurationis nowme.ahoo.cosec.spring.boot.CoSecAutoConfiguration); and the logger names in its logging configuration (logging.level.me.ahoo.cosec.cacheis nowlogging.level.me.ahoo.cosec.cocache).The policy documents, route maps and the JSON formats are a module of their own,
cosec-document.me.ahoo.cosec.runtime.documentis nowme.ahoo.cosec.document,me.ahoo.cosec.runtime.document.formatisme.ahoo.cosec.document.format, andme.ahoo.cosec.runtime.routeisme.ahoo.cosec.document.route; the classes (PolicyDocument,PolicyDocumentCodec,PolicyDocumentCompiler,DocumentCompileException,Actor,RouteMap,RouteMapCodecand the rest) keep their names. No document, schema,cosec.*property, bean or Redis key changes. In an application, change the imports.cosec-runtimeand the starter bringcosec-document, so no dependency changes; code that only reads or writes documents (a generator, a CI check) can depend onme.ahoo.cosec:cosec-documentalone instead ofcosec-runtime.cosec-openapinow depends oncosec-document, notcosec-runtime: an application that compiled against the pipeline through it addscosec-runtime, or the starter, itself.The shadow window ports and their values are in
cosec-spi.CandidateStore,StoredCandidate,ShadowReportSink,ShadowReportReader,ShadowReport,ShadowSample,ShadowOutcome,InstanceStatusandInstalledDocumentmove fromme.ahoo.cosec.runtime.shadowtome.ahoo.cosec.spi.shadow, still experimental, with their names. A store of your own changes its imports and can depend oncosec-spialone.cosec-cocacheno longer depends oncosec-runtime: an application that compiled against the pipeline throughcosec-cocachealone addscosec-runtime, or the starter, itself. No stored format or Redis key changes.Issuing tokens is
cosec-login's.TokenFamilies,DefaultTokenRevokerandSimpleCompositeTokenmove fromme.ahoo.cosec.runtime.tokentome.ahoo.cosec.login.token, with their names, and two of them changed again:DefaultTokenRevokerisStoreTokenRevokerin the same package, andSimpleCompositeTokenis gone, replaced byCompositeTokenincosec-api(both below);me.ahoo.cosec.runtime.tokenkeeps what verifying a request's token needs (TokenRevocation,CoSecTokenVerifier). In an application, change the imports; the starter andcosec-jwtbringcosec-login, so no dependency changes.The adapter contract is one package,
me.ahoo.cosec.runtime.http.RequestGate,Outcome,Problem,ProblemType,ProblemEncoderandRequestSecuritymove fromme.ahoo.cosec.runtime, andTraceContextfromme.ahoo.cosec.runtime.event, besideHttpFacts,HeadersandCookies; the classes keep their names. In an application, change the imports: an adapter of your own, a handler that readsRequestSecurity, a test that reads anOutcome. No status code, header, body or property changes. Five loggers are named after the class that now logs on its own, so a logging configuration that sets their level uses the new name:Before After me.ahoo.cosec.runtime.FallbackIdsme.ahoo.cosec.runtime.call.FallbackIdsme.ahoo.cosec.runtime.attribute.AttributeProvidersme.ahoo.cosec.runtime.attribute.FetchedAttributesme.ahoo.cosec.runtime.event.ShadowListenerme.ahoo.cosec.runtime.shadow.ShadowListenerme.ahoo.cosec.runtime.shadow.Candidatesme.ahoo.cosec.runtime.shadow.CachingCandidateSourceme.ahoo.cosec.runtime.shadow.ShadowRecorderme.ahoo.cosec.runtime.shadow.ShadowReporterThe change log has a logger named on purpose.
LoggingChangeListenerwrote the change log to the loggerme.ahoo.cosec.control.audit.ChangeAudit, a name that came from the file it was in; it now writes tome.ahoo.cosec.changelog(LoggingChangeListener.LOGGER_NAME), as the decision audit writes tome.ahoo.cosec.audit: a name outside every package, so no class logger is a child of it. A logging configuration or a log shipper that routed or filtered the old name uses the new one (Control-plane change log). The line itself is unchanged. The dispatcher's own warning,Change listener [<name>] could not record <event>., is now logged by the logger of its own class,me.ahoo.cosec.control.audit.ChangeListeners.A pipeline without Spring is built with
Pipeline.builder.Pipeline.builder(authenticator, store)compiles and installs the documents of aSnapshotDocumentStoreas the starter does.memberships,attributes,listener,rateLimiter,routes,ids,clockandforwardIdentity { … }set the other parts;options { … },snapshots { … }andlisteners { … }set what the parameters ofPipelineOptions,SnapshotOptionsandDecisionListenersset, with the same names and defaults.snapshots { prewarmApps = …; prewarmTenants = … }names the documents loaded at build, ascosec.authorization.snapshot.prewarm-appsandprewarm-tenantsdo for the starter;awaitDocuments()waits until they have been read and answers those not installed, an empty set when ready.close()delivers the listeners' queued events, then closes the documents. A service behind a CoSec gateway gets its gate fromPipeline.behindGateway { … }.Pipeline's constructor,PipelineComponentsandSuspendingSnapshotSource.ofare gone;PipelineOptions,SnapshotOptions,SuspendingSnapshotSource,AttributeProviders,DecisionListeners,IdentityIssuer,IdentityGateandCoSecParameters.readare now@InternalCoSecApi, which applications never opt in to. No status code, header, body orcosec.*property changes. One change in the safe direction for a pipeline assembled by hand: its documents now compile as the starter's do, so a condition or rate limit key on the API key header it reads (options { apiKeyHeader = … }) does not compile (CND-5). Such a document is installed as failed and its requests are a 503, whereSuspendingSnapshotSource.of(store)installed it. A builder given two forms of one input (listenerandDecisionListeners, for instance) refuses to build rather than drop one.kotlinval pipeline = Pipeline.builder(authenticator, store) .snapshots { prewarmTenants = setOf("acme") } .memberships(memberships) .build() check(pipeline.awaitDocuments().isEmpty()) // before the first requestDurations in public and SPI signatures are
java.time.Duration.AttributeProvider.timeoutis ajava.time.Duration?: a provider of your own writesoverride val timeout: Duration? = Duration.ofMillis(200)withjava.time.Duration, where it wrote200.milliseconds.CoCacheMembershipProvider.DEFAULT_FILL_TIMEOUTand thedrainTimeoutofKafkaAuditListenerandKafkaChangeListenertake ajava.time.Durationtoo; code that passed akotlin.time.Durationconverts it withtoJavaDuration(). No property, default or behaviour changes.CompositeTokenis a final class incosec-api, andSimpleCompositeTokenis removed. Build one withCompositeToken(accessToken, refreshToken). It is equal by value and has nocopyorcomponentN. Logging a token no longer prints it: its string isCompositeToken(accessToken=***, refreshToken=***). The JSON a login or refresh endpoint answers is unchanged ({"accessToken":…,"refreshToken":…}).RefreshTokenCredentialsdeclaresaccessTokenandrefreshTokenitself and no longer is aCompositeToken: a credential an application implements does not inherit from a value. Your refresh credentials class overrides the two, as it did:kotlindata class RefreshCredentials(override val accessToken: String, override val refreshToken: String) : RefreshTokenCredentialsCode that passed it where a
CompositeTokenis expected (TokenRevoker.revoke) builds one,CompositeToken(credentials.accessToken, credentials.refreshToken).SimpleRefreshTokenAuthenticationisRefreshTokenAuthentication, in the same package and with the same constructor: the only one there is needs no prefix. Rename the class where you declare its bean.DefaultTokenRevokerisStoreTokenRevoker: it revokes through theTokenStore, which the name now says. Same package (me.ahoo.cosec.login.token) and constructor; the starter's bean is stillcosecTokenRevoker, andTokenRevokeris still the SPI. Rename the class where you construct it.api.CoSecis removed. Its values keep their spelling and gain names where they mean something: the anonymous principal isCoSecPrincipal.ANONYMOUS_IDand the default tenantTenantId.DEFAULT, two different ids both spelled(0); thecosec.*properties and the default Redis key prefix (cosec.key-prefix,cosec) are as before, and so are the span attributes (cosec.tenant_id, …) and the OpenAPI schemecosec.BearerAuth. Code that readCoSec.COSEC,CoSec.COSEC_PREFIXorCoSec.DEFAULTwrites the value it meant. No key, property or attribute changes.A tenant switch is
SwitchTenantAuthenticationwith aTenantSwitch, and it can set the app.AbstractSwitchTenantAuthenticationis removed. Where you extended it and implementedswitchTenant(targetTenantId, previous), declareSwitchTenantAuthentication(families, revocation, YourCredentials::class.java) { credentials -> … }as a bean, with the starter'sTokenFamiliesandTokenRevocationbeans: the switch gets your own credentials class (credentials.targetTenantId,credentials.context, and anything else it carries), and answers aTenantMembershipas before.SwitchTenantCredentialsgainstargetAppId, the app the user asks for, null by default, and losesaccessToken: the switch issues from the session of the request, which thecontextthe pipeline made carries (IDN-22), so stop passing the token text (and parsingAuthorizationfor it).TenantMembershipgainsapp. The new token is for the app your switch answers, else the previous token's (SCP-12): a switch that answers none behaves as before, and a user never gets an app by naming it.TokenSubject.authTimeis removed, andTokenFamilies.rotateandTokenFamilies.startAt(the formerstart(…, authTime)) are CoSec's own (@InternalCoSecApi): an issue from an earlier login goes through the check of a live session. See Switching tenant and app.The forwarded identity carries the session and the issue time of CoSec's token (
auth.session:sid,auth_time,generation;auth.iat), so that a service behind the gateway knows when the user signed in and a tenant switch there issues from that session (IDN-22). The format stays version 1, and a service reads it strictly: one older than its gateway refuses the new members with400. Upgrade the services behind a gateway before the gateway. An identity without them (an API key's, or one an older gateway sent) reads as before and cannot be switched from.Identity.CredentialgainsissuedAtandsession, both optional.SecurityContextgainsrequestIdanddeviceId.requestIdis the id CoSec used for the request (the client'sCoSec-Request-Id, or the one CoSec generated, which no header holds);deviceIdthe client'sCoSec-Device-Id, empty when none, which CoSec checks for form only and which proves no device. Read them there instead of the headers. ASecurityContextof your own still compiles: both default to"". Behind a gateway the service now readsCoSec-Device-Idunder the rule the gateway reads it with (one value, else400), soenvironment.devicein a check in code sees it there too; before, it saw no device behind a gateway.A refresh can re-read the user.
RefreshTokenAuthenticationtakes an optionalMembershipRefresh, which answers what the user holds now; the class keeps the verification, the revocation check, the rotation and the session. Where you wrote anAuthenticationof your own to re-read the user on refresh, pass aMembershipRefreshinstead. Without one, a refresh keeps the token's claims, as before. The hook is given the token and the refresh's credentials ({ token, credentials -> … }); to read facts of your own there, a device say, pass your credentials class too,RefreshTokenAuthentication(verifier, revocation, families, YourCredentials::class.java) { token, yours -> … }, as a tenant switch takes its own.RefreshTokenAuthentication(verifier, revocation, families)is written as it was.TokenCompositeAuthenticationis built withTokenCompositeAuthentication.of(authentications, tokenConverter, families). Its constructor took two types no application could build (CompositeAuthentication,DefaultAuthenticationProvider) and is now@InternalCoSecApi. The starter's bean is unchanged; a login assembled by hand, in a test say, passes itsAuthentications toof.An
httpaction no request can have does not compile (DOC-8). A statement or rate limit rule onhttp:HEAD(decided ashttp:GETsincePIP-18) or on a verb with a lower-case letter (http:get) matched nothing, so a DENY on it denied nothing. Such a document is now refused: a stored one is installed as failed, which fails its requests closed (503), and the control plane refuses a change that makes one. Find them before upgrading, in the documents the control plane lists ("http:HEAD", or an"http:action with a lower-case letter after the colon), and publish them again withhttp:GET, or the method in upper case. For a 7.x conversion,cosec-migrate convertreports once, whatever the statements say, that a HEAD request is now decided as GET (PIP-18: permitted wherever GET is, denied wherever GET is); it reads the country prefix of 7.x'sipRegionasext.ip2region.country, which the platform document then declares (every host that enforces such statements needscosec-ip2region); and a part only 7.x's request appenders filled (ipRegion, an application's own attributes) is always absent in 8.0, so a condition on it translates only where it narrows an ALLOW (recorded asNOT-IN-8.0); every other case is refused (MIG-1), since it would widen an ALLOW, deny every request in scope, or stop a DENY matching what 7.x denied.cosec-migrate cocache8is removed. It moved 8.0.0-alpha.2's data from CoCache 6 to CoCache 8 (Data written through CoCache 6): a deployment that still holds such data moves it with thecosec-migrateof 8.0.0-alpha.4 before upgrading. While<p>:meta:cocache8is there,publishrefuses and writes nothing: the marker is left by an upgrade that stopped after it deleted the documents, which are in its export, not in Redis. Finish that upgrade with the 8.0.0-alpha.4cosec-migrate(publish --resume, with--inon the export the message names), or check that every document the marker lists is published, then delete the key.cosec-migrate api-keys --appworks (round 2 M3). The step could not be run since #1302, which added--appto the code and this page but not to the options the command takes: it refused--appas an option it does not take. Rerun it with--app <id>for keys a service with an app must accept.The starter's startup checks run under lazy initialization (
STA-3). Withspring.main.lazy-initialization=trueno check ran: a Spring MVC host withoutcosec-webmvcstarted with no authorization, a Spring Cloud Gateway host ingatewaymode forwarded every request unchecked, and Redis's eviction policy, replica reads, exposed actuator endpoints, API keys without aMembershipProviderand unknowncosec.*properties went unchecked. They now fail startup as they do without lazy initialization. A configuration that started only because they were skipped no longer does: fix what the message names.A social login registration with an unknown field fails startup (round 2 L4). A misspelt field under
cosec.authentication.login.social.registration.<name>(pcke,scope) was ignored, leaving the provider configured otherwise than meant; the message now names the key. Rename or remove it.cosec.cosid.generatorthat does nothing fails startup (round 2 L7). Set without aCosIdRuntimebean, or beside anIdGeneratorbean of the application's own, it was ignored and CoSec kept its random ids. Configure CosId, or remove the property.Two in-memory API keys with one hash fail startup (round 2 L5). The key authenticated as whichever entry came last in
cosec.api-key.keys; keep one entry per key.The control plane's authorization beans cannot be replaced,
@Primaryor not (round 2 L6). A secondControlAuthorizer,ChangeAuthority,Changes,ControlPlaneorControlHttpbean marked@Primary, or named as an injection point's parameter, was injected in place of CoSec's; it now fails startup, as a plain second bean did.A principal's attributes are read-only (round 2 L3).
SecurityContext.principal.attributeswas the map the authenticator handed over: an application that cast it to a mutable map and changed it changed what every furtherAuthorizationCheckercheck of the request decided on. It is now an unmodifiable view, and a token's nested objects and arrays are read-only too: a change throwsUnsupportedOperationException. Copy the map to change it. An authenticator of your own must not change the map it hands over afterwards.The test kit reads a request as enforcement does (round 2 M2,
PIP-15).PolicyTestKitdecidedhttp:HEAD, a lower-case method and a path with a dot segment as written, so it confirmed a DENY onhttp:HEADthat the pipeline, which decides HEAD as GET, never applies. It now decides HEAD as GET and normalizes paths, and answers{"decision": "InvalidRequest"}where the pipeline answers400: rewrite such scenarios, and a statement onhttp:HEADas one onhttp:GET. Anexpectmust name adecision(an empty one passed whatever was decided), and a directory of shortened file names needs thereport.jsoncosec-migrate convertwrote beside it. The experimentalevaluate(JsonNode)andcheck(String, JsonNode)are gone: pass the scenario as text,check(name, json).A generated route map sits at the
serverspath, and its resources name every path variable (round 2 L4). ThecosecServiceGeneratorendpoint dropped a server path (/api/v1), so its routes matched no request and every request was in thehttpnamespace; and/users/{id}/avatar/{size}was the resourceuser/{size}, one resource for every user. Routes now start with the server path, without the context path, and the resource isuser/{id}/{size}: generate the route map again, and rewrite the resources a policy names after a generated one. Servers with different paths, or a server variable in the path, fail generation.ip2region: what it cannot locate is unavailable (round 2 M5). An IPv6 client, with only the bundled IPv4 database, had no country, so a geo-block DENY written as
country in [...]let it through; it is now unavailable, so that DENY makes the request503(or lets it through withonMissing: nomatch). Load an IPv6 database withcosec.ip2region.ipv6-location.Ip2RegionAttributeProvidertakes its databases as a list, each for the version its header names, instead of one database and a version.A failing
IdGeneratorcosts only its id (PIP-23). One that threw (CosId'sClockBackwardsExceptionafter the clock went back) left the pipeline before any outcome: no problem body, noCoSec-Request-Id, no decision event, and each adapter answered its own way. A random id now stands in, with a WARN at most every ten seconds;CosIdIdGeneratordoes the same for a CosId failure. Configure CosId's clock regression policy to fail rather than wait.A handler reads the security context from a
SecurityContextparameter (round 2 M4). The starter registersSecurityContextArgumentResolver.SecurityContextHolderis for blocking code on the request thread: asuspendhandler that resumes on another request's thread read that request's context from it. Withio.micrometer:context-propagationandspring.reactor.context-propagation=auto, Spring now restores the holder too; without them the holder is unbound in asuspendhandler:SecurityContextHolder.contextisnullthere, andrequiredContextthrows (PIP-22).Applications only read the security context (round 2 L5).
SecurityContextHolder.setContextandremove,ServletRequests.setSecurityContext,ServerWebExchanges.setSecurityContext, andReactiveSecurityContexts.setSecurityContextandwriteSecurityContextare internal API: only the adapters bind the context. Code that bound a context of its own, whichAuthorizationCheckeralready refused, no longer compiles.The context path is removed segment by segment (
PIP-20). On Jetty, which writes the context path canonically while the URI keeps the client's form,/%61pp/orders/1with the context path/appwas decided as/app/orders/1, past every statement on/orders; it is now/orders/1. A URI that does not start with the context path is400.The Spring MVC filter runs at
-9999, right after Spring Boot's hidden-method filter (-10000), instead ofHIGHEST_PRECEDENCE + 100. Withspring.mvc.hiddenmethod.filter.enabled, aPOSTwith_method=DELETEwas authorized as a POST and executed as a DELETE; WebFlux already authorized the DELETE. A filter of yours that must run before CoSec, a CORS filter say, needs an order below-9999.HEAD is decided as GET, and a method with a lower-case letter is a
400(PIP-18). Servers run the GET handler for HEAD, so a DENY onhttp:GETdid not stop it: HEAD now takes a route map's HEAD route, or GET's, and unmapped it ishttp:GET; a statement onhttp:HEADis refused (DOC-8, see above), since HEAD is decided ashttp:GETor as the action of the route map's HEAD route. A method such asdeletewas decided ashttp:delete, which a DENY onhttp:DELETEdoes not name, while backends that fold case served it as DELETE: it is now400 invalid-request.AuthorizationCheckerand the control plane's simulate, explain and analyze read anhttpaction the same way:http:HEADashttp:GET, and a lower-case verb is a deny, or400.The client address is read once (
PIP-16). Where the server resolves forwarded headers itself (server.forward-headers-strategy=native, which Spring Boot also turns on by itself on Kubernetes and the other cloud platforms it detects), CoSec no longer readsX-Forwarded-Fora second time: on Tomcat it takes the address theRemoteIpValveresolved, and on Reactor Netty and Jetty it reads the header and never the address the server forwarded. Before, on Tomcat, the two readings together took an entry the client wrote. Startup now fails underframework, with an explicitcosec.authorization.remote-ip.max-trusted-indexon Tomcat undernative, withmax-trusted-index: 0on Reactor Netty or Jetty undernative, and undernativeon a server CoSec cannot tell. Migration: the message names what to change (Troubleshooting).XForwardedRemoteIpResolveris now internal API.Several
X-Forwarded-Forlines are one list, and an unreadable client address is unavailable (PIP-17). A request with two header lines used the connection's peer, which let a client step around a block on its own address; the lines are now read in order. A trusted entry with a port, brackets or a zone is read as its address. One that is no address (unknown) madeenvironment.ipabsent, which a DENY read as no match; it is now unavailable: such a DENY is503, and the blacklist answers unavailable too.A credential's tenant must be a tenant id (
IDN-11). A token whosetenantIdis blank,*, holds a:or a control character, or is longer than 128 characters, or holds a/, is now401 token-invalid(it was503, or500for a blank one), andJwtTokenConverterdoes not issue it; anApiKeywith such a tenant cannot be built, so a stored one fails its lookup (503) and a configured one fails startup.SnapshotVersionis removed fromcosec-spi: it named the two documents of 7.x. A decision event'ssnapshotVersionis aViewVersion(platform,app,tenant), as before.A rate limit window is at most a day (
windowSecondsup to86400), andpermitsPerSecond × windowSecondsat most 2⁶³: a larger quota overflowed the limiters' arithmetic, and a longer window kept one Redis key per bucket value for two windows in a Redis that must not evict (round-2 review M3). Such a document no longer decodes;RateLimitrefuses the same values. To migrate: express a daily or longer quota as a per-second rate over a day.The Redis rate limiter keeps one key per bucket and counts by Redis's clock (round-2 review L1). A bucket is now the hash
<cosec.key-prefix>:rate-limiter:<rule>:<bucket>, not a key per window (...:{<rule>:<bucket>}:<window>), and the script takes the time from Redis, so instances whose clocks differ no longer count apart. Counters written by an earlier version are not read and expire on their own: a bucket starts from zero once, at the upgrade.ReactiveRedisRateLimiterno longer takes aclock.A document holds at most 64 rate limit rules (
DOC-6). Every rule a permitted request matches costs one call to the limiter, so a document with more no longer compiles: a stored one is installed as failed (its requests are503), and the control plane refuses a change that would make one with422. To migrate: merge rules that differ only in what they count into one rule with akey.A statement with several resource patterns means one statement per pattern (
ALG-10). When its condition reads a path variable and a request matches more than one of its patterns, the condition is now tested under each matching pattern's captures and the statement matches if any holds; before, only the first matching pattern's captures were read, so a DENY could miss a request one of its own patterns denied, and the order of the patterns changed the decision. A DENY written this way now denies at least what it did; an ALLOW may permit more. A rate limit rule keyed by a variable takes it from the first pattern under whose captures its condition holds. To check: search your documents for statements with severalresourcepatterns whoseconditionreadsresource.var.*.A path with an empty segment, an encoded separator or a backslash is a
400(PIP-14).//admin,/admin//x,/;x/admin,/admin%2Fx,/admin\xand/admin%5Cxwere decided as paths of their own, so aDENYunder/admindid not match them, while a backend that merges slashes, decodes separators or reads\as/served them as/admin/.... A trailing/is unchanged:/admin/stays its own path. Requests that were served before and are refused now:- a
\in a path, raw or encoded: no client is expected to send one, as browsers turn it into/; - a
/encoded inside a path variable, such as/files/a%2Fb.txtor/repos/group%2Fproject: send the value in the query, or encode its/twice (%252F), which the pipeline decodes once, to the text%2F, and the application decodes again; - a URL whose parts were joined with a
/each (https://host/api/+/orders): fix the client; - a path parameter alone in a segment before the last (
/;jsessionid=x/orders): URL rewriting puts it at the end of the last segment (/orders;jsessionid=x), which is still accepted.
There is no switch to accept them: a pattern cannot say what a backend will make of these paths, so deciding them would bring the bypass back.
- a
A check refuses what enforcement refuses (
PIP-15).AuthorizationChecker.checkanddecidenow read a path as the pipeline reads a request: one the pipeline answers400for is a deny, as is any resource over a request path's length bounds. Before,/public/../admincould be permitted by anALLOWunder/public.Shadow windows count two more outcomes:
BECAME_DENIEDandOBLIGATIONS_CHANGEDwere counted asSAME, and a publish must now acknowledge them. Finish or abandon open windows before a rolling upgrade: an instance of the previous version cannot read a report that holds them.A social login's state is single use and bound to the browser that started it (round-2 review M4). JustAuth only checked that a state existed: one state signed in any browser that opened a callback holding it, as often as it was opened within 3 minutes, which allowed login CSRF.
SocialAuthentication.authorizeUrl(provider)becomesauthorize(provider), which answers aSocialAuthorization(url,binding);SocialAuthenticationProviderdoes the same. Setauthorization.setCookie(path)on the browser before redirecting it, and pass the cookie's value toJustAuthCredentials(provider, binding), which takes it as a second argument;SocialCredentialshas abinding. The state is taken from Redis on the callback (<s>:oauth:binding:<state>, Redis 6.2 or later forGETDEL).JustAuthProvidertakes aSocialStateStore.ignore-check-state: trueon a registration fails startup.Tokens and API keys declare their app (batch R7b, RFC 0012 §3.5,
SCP-11). A token'saudand an API key'sappname the app the credential belongs to, andScopeResolvercompares them with the host's: a host with an app (cosec.authorization.scope.app-id, or a route'scosec-app-id) refuses a credential declaring another app, or none, with403 scope-rejected. Without a host app the credential's app applies, and without one either no app document is read. To migrate: setTokenSubject.appwhen you issue a token, one token per app. Setappon API keys (ApiKey,cosec.api-key.keys[].app). Stored keys move to format 3 with a requiredappfield: format 2 fails (API key format [2] is not 3.), so re-provision them (cosec-migrate api-keys --app <id>sets the app on the keys it converts from 7.x). A token that operates the control plane is issued forcosec.control.app-id(defaultcosec-control); control-plane routes on a host whose own app differs answer403, so give them a host with no app, or that app.CoSec-App-Idis gone. A client no longer declares an app; the header is not read, and a request that sends it gets the credential's app. A gateway's forwarded identity still carries its app: a service behind it with an app refuses an identity naming another app, or none, with400 invalid-request. ReadSecurityContext.scope.appIdfor the request's app.SecurityContextis read-only:tenantId,principal, a non-nullscopeandforwardedIdentity(gatewayRequestId,credentialId, which replace the attributescosec.identity.ridandcosec.identity.jti), andrequestIdanddeviceId(see above). The attribute map and its accessors are removed;tenant.tenantIdbecomestenantId.CoSecPrincipalis what an application reads of the request:id, an explicitauthenticated,attributes. The roles effective for the request are inSecurityContext.scope.roles;principal.rolesandprincipal.policiesare removed.The token contracts are values.
TokenVerifier.verify(accessToken: String)andrefreshreturn aVerifiedToken(me.ahoo.cosec.spi.token), with no type parameter;TokenRevoker.revoketakes the token string, or aCompositeToken(below).TokenConvertertakes aTokenSubject(me.ahoo.cosec.login.token), andAuthentication<C>answers one. Removed: the wrappersSimplePrincipal,SimpleTenantPrincipal,TenantPrincipal,TokenPrincipal,TokenTenantPrincipal,SimpleTokenPrincipal,SimpleTokenTenantPrincipal,MembershipMarkedPrincipal,Delegated,findInDelegationChain,IssuedAtCapable,ExpiresAtCapable,MembershipMarkerCapable,AccessToken,RefreshToken,TokenandTokenIdCapable. Replace a customTokenVerifierby building aVerifiedToken; its constructor refuses invalid claims, whichverifylets through as theTokenVerificationExceptionit already throws.RoleCapable,PolicyCapable,SpacedRoleId,RoleIdCapable,SpaceIdCapable,Tenant,TenantCapable,SimpleTenantandNamedare removed. The claim names are constants ofMembershipClaims, and the tenant idsTenantId.DEFAULTandTenantId.PLATFORM;role@spacedoes not change.SocialAuthenticationProviderkeeps itsname.A token whose subject begins with
(is invalid (IDN-12), as are tokens with nosuborjti: a token cannot name CoSec's own ids, the anonymous principal(0)above all.AttributeRequestcarries thetenant, andSubject.tenantIdis removed: a stage-A provider readsrequest.tenant.SwitchTenantCredentialscarries thecontext(SecurityContext) of the request instead of aprincipal, andswitchTenantreceives it (AbstractSwitchTenantAuthentication.switchTenantis now theTenantSwitchhook ofSwitchTenantAuthentication, see above). The new token keeps the previous token's app.Login is suspending, and
cosec-loginno longer brings Reactor (batch R7c).Authentication.authenticate,TokenCompositeAuthentication.authenticateAsToken,AbstractSwitchTenantAuthentication.switchTenant(now theTenantSwitchhook ofSwitchTenantAuthentication, see above),SocialAuthenticationProvider.authorizeUrlandauthenticate,SocialAuthentication.authorizeUrlandSocialUserPrincipalConverter.convertaresuspendfunctions that return the value instead of aMono. To migrate: make the overridesuspendand return the value; await a Reactor client withawaitSingle(); make the controller functionsuspend. AMono.empty()that refused a login becomes an exception, since there is no empty answer. A module that compiled against Reactor throughcosec-logindeclares it itself.cosec-socialno longer brings Guava.DefaultAuthenticationProviderandSocialProviderManagerare classes, and the starter assembles one of each per application context (#1222). Replace a call on the old singletons with theAuthenticationProviderorSocialProviderManagerbean;SocialAuthenticationtakes the manager in its constructor.JustAuthProviderruns on its own dispatcher, at most 16 threads per provider, so social login no longer needsSchedulers.boundedElastic().Libraries export what their public classes implement (
cocache,kafka,ip2region,micrometer,opentelemetry): you may drop a dependency you added only to compile against them.The public API is classified (RFC 0010 C4). What an application needs stays public; everything else is
@InternalCoSecApi(applications never opt in) orinternal. Most ofcosec-engine, the condition AST ofcosec-model,cosec-runtime's snapshot views, shadow recording and document model, the control plane'sControlPlane, grant and access analysis, and the starter's auto-configuration classes are internal now. If you compiled against one, use what the page you found it on documents instead: the checks and listeners are still there. In the test kit, onlyPolicyTestKit,PipelineFixture,PermittedRequest,AttributeRequests,EngineOutcomeand their exceptions are public.PipelineComponentsis a plain class, as isSnapshotOptions; both losecopyand thecomponentNfunctions.PipelineComponentsno longer takes anengine. A host without Spring Boot is built withPipeline.builder(authenticator, store)(SuspendingSnapshotSource.of(store), which this bullet first named, is gone: see above).PolicyDocumentCompiler.compileis internal. A CI check callsvalidate;forPlatform(platform)is the overload for it.A public
data classis now a value that cannot grow (RFC 0010 C4):Identity,Identity.Credential,TokenSubject,SocialUser,ForwardedIdentity,Audit*Data,ShadowReport,ShadowSample,InstalledDocument,InstanceStatusand the starter's*PropertieslostcopyandcomponentN.Identity,Identity.Credential,TokenSubjectand the shadow records still compare by value; the others no longer defineequals.A refresh token is refused where an access token is expected, and an access token where a refresh token is (
IDN-13).JwtTokenConverterwritescosec.token: "refresh"on every refresh token; a token with that claim authenticates nothing, and a refresh reads only a token with it, whoseiatis the access token's. Access tokens issued before this version keep working until they expire; their refresh tokens, which lack the claim, no longer refresh, so their users sign in again.Revocation is one judgement, and the token contracts do no blocking I/O.
TokenVerifieris pure computation by contract.RevocableTokenVerifieris removed: the pipeline, refresh and logout all read revocations throughTokenRevocation(cosec-runtime), over theRevocationReader.TokenStorekeeps only its writes,revokeandrevokeSubject, nowsuspend; its synchronousisRevokedandsubjectRevokedBeforeare gone (read them throughRevocationReader), as isTokenStore.NoOp.TokenRevoker.revokeandrevokeSubjectaresuspend: call them from asuspendhandler instead of moving them off the event loop.DefaultTokenRevokertakes theTokenRevocation(it is nowStoreTokenRevokerinme.ahoo.cosec.login.token, see above).SimpleRefreshTokenAuthentication(tokenVerifier)becomesSimpleRefreshTokenAuthentication(tokenVerifier, tokenRevocation)(nowRefreshTokenAuthentication, see above) and no longer runs on a dispatcher of its own. The starter'sTokenVerifierbean is the plainJwtTokenVerifier, and it adds aTokenRevocationbean. ATokenStoreof your own implements the two writes assuspendfunctions, and its reads as aRevocationReaderbean.Refresh tokens belong to sessions (RFC 0009, round-2 review M2). A login starts a session, a family of token pairs whose id, login time and generation both tokens carry (
sid,auth_time,cosec.generation), kept in Redis under<cosec.key-prefix>:token:family:<sid>(Sessions). Only the current pair refreshes; an older one presented again ends the session; a session lastscosec.jwt.session.lifetime(30 days) from its login; logout ends the whole session. What changes for an application:- Every user signs in again once: a pair issued before this version carries no session and is refused on refresh (
token-invalid); its access token works until it expires. - Issue tokens through
TokenCompositeAuthentication, which starts the session, or start one yourself withTokenFamilies.startandTokenSubject.inSession: a pair fromTokenConverter.toTokenalone never refreshes.TokenCompositeAuthenticationandSimpleRefreshTokenAuthentication(nowRefreshTokenAuthentication, see above) take aTokenFamilies(a starter bean). - A client keeps only the newest pair: presenting a pair after a newer one was issued ends the session, unless it happens within
cosec.jwt.session.rotation-leeway(30 seconds) of that refresh: then it gets a pair of the newest generation, so a refresh whose response was lost can be retried. TokenRevoker.revoke(compositeToken)logs out with an expired access token;revoke(accessToken)now ends the session too. ATokenRevokerof your own implements both.- A tenant switch needs the session: it was
SwitchTenantCredentials.accessToken, andAbstractSwitchTenantAuthenticationtaking theTokenVerifier; it now issues from the session of the request (SwitchTenantAuthentication, above), and the new token keeps the login time. - Without
cosec-cocache, register aTokenFamilyStore, or startup fails (InMemoryTokenFamilyStorefor one instance). Redis holds one key per live session.
- Every user signs in again once: a pair issued before this version carries no session and is refused on refresh (
A revocation store that cannot be read is reported, never read as "not revoked" (round-2 review H1,
IDN-14). ARevocationReaderthrowsRevocationUnavailableExceptionwhen its store cannot be read; the revocation tables'unknown-readis locked tothrow, sococache.caches.[RevokedTokenCache].unknown-readfails startup. The pipeline still accepts a request's token then, as before; a refresh now fails instead of issuing a token, and the control plane publishes nothing on an approval whose approver's revocations cannot be read. A customRevocationReaderthat answered "not revoked" on a failure throwsRevocationUnavailableExceptioninstead. To refuse requests too, setcosec.authentication.revocation.fail-closed: true, which replacesunknown-read: throwon the revocation tables.Instance statuses carry the document format level (RFC 0010 C5): an instance reporting without
formatLevelis refused by a control plane of this version, and a shadow window reading one fails until every instance has been upgraded (a control plane counts only the statuses written within the last minute,ShadowReportReader.STATUS_TTL; the key itself lives two).The control plane refuses what used to fail at run time. A platform change that turns a policy other documents refer to into a boundary, or a boundary they refer to into a policy, is
REFERENCES(422,CTL-30). A binding that names a platform boundary isREFERENCEStoo: such a binding never granted, every request it applied to was503, and a document that holds one has to remove it before it publishes again. An id a change puts holds no/(V2,422): a rule ending in*did not reach such an entry. A permission policy'sperm:<app>/<id>may; entries that already hold one can stay or be removed. An app change that removes a policy tenants bind, or one its short forms derive, isREFERENCESwhen it is checked: it used to reachCHECKEDand fail only when it was published (CTL-30).ChangeEvent.KindlosesBOOTSTRAPandMIGRATE. No change event of those kinds was ever emitted: a bootstrap and a migration write their revisions through the store, and are recorded in the revision'sprovenance.kind(BOOTSTRAP,MIGRATE). AwhenoverChangeEvent.Kindthat names them stops compiling; delete the branches, nothing was ever delivered to them.A preflight is no longer seen by policies, rate limits or the audit when the application declares a
CorsConfigurationSourcebean (STA-5, CORS). The starter now registers a CORS filter before CoSec's on Spring MVC and WebFlux when the application declares the stack'sCorsConfigurationSourceand noCorsFilterorCorsWebFilterof its own: a preflight is answered by it from the source alone, so a statement onhttp:OPTIONS, a rate limit, the blacklist, the audit, a decision event or a metric never sees one; an origin the source does not allow gets a plain403before the pipeline, without a problem body or aCoSec-Request-Id; and a refusal now carries the CORS headers.@CrossOriginandaddCorsMappingsno longer answer a preflight: put every origin, method and header in the bean. A statement written only to let a preflight through (http:OPTIONS) is not needed any more and can stay. An application without the bean, or with a filter of its own, is unchanged.Removing a DENY from the platform or an app document needs a second person (RFC 0007 §7.4.4,
CTL-31). Until now, a platform principal withoutcosec:approvecould publish alone a change that only removed entries. A removal that takes away a DENY, a policy that holds one or a binding whose policy holds one (also through a role removed or put with fewer permissions), now waits inAWAITING_APPROVALwith aNOT_ANALYZEDescalation for each, as does the trust root's underfour-eyes(Approval). Removing ALLOWs, a tenant's own DENYs and break-glass revokes are unchanged. Plan an approver for emergency removals of a platform DENY.cosec:grantfollows what a role derives (RFC 0012 §7.2): aputCatalogorputPolicythat makes a"*"role derive a binding it did not needscosec:granton the role's scope, as aputRoledoes.cosec:breakglassis enough for break-glass (RFC 0007 §8): requesting one, publishing it once approved and revoking it no longer also needcosec:publish. No other change takescosec:breakglassin its place.A rollback carries
confirmations, as a proposal does, when it brings back a DENY withonMissing: "nomatch". Until now such a rollback could not be confirmed at all.repair-referencesalso removes what a publish indexed before a head write it lost, and printsRemoved <n> reference(s) no head refers to.. Repair the back-reference index.The public API of
cosec-model,cosec-engineandcosec-spiis classified for 8.0 (R9, RFC 0010 C4): what stays public is what 8.0 keeps stable. What an application notices:ApiKeyStoreis removed. Requests read keys throughApiKeyReader. Manage keys through theInMemoryApiKeyStoreor theRedisApiKeyStorebean, whose methods do not change; inject the bean by its own type. The pipeline never read anApiKeyStorebean of an application's own: to look keys up elsewhere, declare anApiKeyReader.- The evaluation trace moved, and is experimental.
me.ahoo.cosec.engine.flat.FlatTraceisme.ahoo.cosec.engine.trace.EvaluationTrace, withCandidateTraceandCandidateOutcomebeside it. These types andDecisionEvent.evaluationTraceare@ExperimentalCoSecApi(opt in with@OptIn(ExperimentalCoSecApi::class)), and their constructors are internal.ViewVersionandAttributeStatusare inme.ahoo.cosec.engine, and stay stable. Audit records and their JSON do not change. RevocationUnavailableExceptionextendsCoSecException, asMembershipUnavailableExceptiondoes. A handler that answers everyCoSecException(aSecurityException) with401now catches it too: handle it first, as the revocation store being unavailable.RateLimitResultis no longer adata class:copyandcomponentNare gone, and equality is unchanged.SnapshotDocument.DOCUMENT_SCHEMAis no longer aconst, so compiled code reads the schema of the CoSec it runs with. Aconst valset from it no longer compiles: make it aval.- A
SnapshotDocumentis made from its bytes (SNP-12): its constructor is internal. ReplaceSnapshotDocument(schema, revision, publishedAt, bytes)withSnapshotDocuments.read(bytes)(cosec-document), which reads the header from the bytes and refuses bytes that are not a document. The stored bytes do not change. - Internal now (
@InternalCoSecApi):Environment, the condition literals (Literal),Attributeand itsKind,ScopeResolver,ScopeSubject,SubjectRevocation,IdentityFormatException,IdentityOverflowExceptionandIdentifiers.isUnpairedSurrogateAt. The constructors ofScopeResolution.ResolvedandScopeResolution.Rejectedare internal;ScopeResolution.Rejected.Reasonstays.
The public API of
cosec-runtimeand the web adapters is classified for 8.0 (R9). With the starter nothing changes at runtime; in code:- Assembling a pipeline without Spring is experimental:
Pipeline.builderandPipelineBuilder,Pipeline.evaluate,RequestGate,HttpFacts,Headers,Cookies,Outcome,Problem,ProblemEncoderandRequestSecurityare@ExperimentalCoSecApi: opt in with@OptIn(ExperimentalCoSecApi::class).PipelineOptions,SnapshotOptions,SuspendingSnapshotSource,AttributeProviders,DecisionListeners,IdentityIssuer,IdentityGateandCoSecParameters.readare@InternalCoSecApi(no opt-in), andPipeline's constructor andPipelineComponentsareinternal; they were experimental first, andPipeline.builderreplaced them. A test that built a pipeline this way gets one fromPipelineFixture(cosec-testkit).Pipelineitself,AuthorizationChecker(pipeline),ProblemTypeand theCoSecParametersheader names stay stable. - Internal now (
@InternalCoSecApi):IdentityCodec(theCoSec-Identityformat on Web integration is the contract),RemoteIpResolver,PathNormalizer,HttpAttributes,PolicyDocument.attributes,PolicyDocumentCodec.encode,ATTRIBUTE_TYPES,WILDCARDandSCHEMA,PolicyDocumentCompiler's limits,PERMISSION_PREFIXandpermissionPrefix, and theAuthorizationChecker.checkanddecidethat take aRequestSecurity(those that take aSecurityContextand strings stay). So are the constructors ofPipelineWebFilter,PipelineServletFilterandPipelineGatewayFilter(declare the starter's beans, never your own),LoggingAuditEventSink(KLogger)(the constructor without arguments stays) andMetricsListener.bind(registry, listeners). The constructors ofRouteResolution.MappedandInvalidare internal:RouteMap.resolveanswers them. InstanceStatus.FORMAT_LEVELis no longer aconst.
- Assembling a pipeline without Spring is experimental:
The public API of
cosec-controlandcosec-cocacheis classified for 8.0 (R9):ControlStore,InMemoryControlStore,CoCacheControlStoreand the records a store keeps (ChangeRequest,ChangeRequestCodec,ChangeState,Base,Approval,CheckedApps,Finding,Severity,Operation,ShadowState,StageSlot,AppList,PendingRecord,RevisionEntry,RevisionIndex,StoredDocument,Versioned,HeadWrite), with the shadow window ports and their reports (CandidateStore,ShadowReportSink,ShadowReportReader,CoCacheShadowReports,InstanceStatus,InstalledDocument,ShadowReport,ShadowSample,StoredCandidate,ShadowOutcome) andProvenanceKind, are@ExperimentalCoSecApi: a store of your own opts in.ChangeListener,ChangeEventand what it carries stay stable;EscalationandConfirmationare no longerdata classes (nocopy, nocomponentN; equality is unchanged).- The CoCache caches (
RevokedTokenCache,RevokedSubjectCache,MembershipCache,PolicySnapshotCache) are@InternalCoSecApi, as are the constructors and factories ofcosec-cocache's classes that take CoCache or Spring Data types (CoCacheTokenStore,CoCacheMembershipProvider,CoCacheTokenFamilyStore,RedisApiKeyReader,RedisApiKeyStore,ReactiveRedisRateLimiter,RedisSnapshotDocumentStoreand its digest helpers,CoCacheControlStore.create,CoCacheShadowReports.create) and theDEFAULT_*_KEY_PREFIXconstants. OnlyCoSecCacheSpecs, internal already, could build those caches: the starter builds them, and an application declares its beans' types (RedisApiKeyStore,CoCacheMembershipProvider, ...) to use them. The cache names incocache.caches.[<CacheName>]do not change.
LocalRateLimiterkeeps every count that can still refuse a request, and a full one cannot count (OBL-5,OBL-6). It dropped a bucket idle for an hour, so a rule with a longer window (up to a day) let a client back in after an hour's pause, and evicted buckets by size, so a flood of new keys on one rule reset the counts of every rule. Now a bucket is removed only once it has been idle for an hour and for two of its rule's windows, and never to make room. The limiter holds at most 100,000 buckets and 50,000 of one rule; a new bucket beyond either cannot be counted, so the rule'sstrictFailuredecides: a strict rule answers503(RateLimiterUnavailable), a lenient one is skipped. Before, it was counted from zero. If a rule keyed on something a client can vary now answers503, key it on the principal or a trusted address instead (The local limiter is bounded).LocalRateLimiter's constructor takes a new second parameter,maximumBucketsPerRule, beforeexpireAfterAccessandclock: calls by name are unchanged, positional ones change.cosec-runtimeno longer brings Guava: an application that used it through CoSec declares it itself.The public API of the starter,
cosec-login,cosec-socialand the web adapters is classified for 8.0 (R9):cosec-login'sCredentialsisLoginCredentials, andAuthentication.supportCredentialsiscredentialsType. Two publicCredentialsin one product named different things: the pipeline's (me.ahoo.cosec.spi.authn.Credentials, a request's token or API key) keeps its name. AnAuthenticationof your own changes like this:kotlin// before data class PasswordCredentials(val username: String, val password: String) : Credentials class PasswordAuthentication : Authentication<PasswordCredentials> { override val supportCredentials = PasswordCredentials::class.java // ... } // after data class PasswordCredentials(val username: String, val password: String) : LoginCredentials class PasswordAuthentication : Authentication<PasswordCredentials> { override val credentialsType = PasswordCredentials::class.java // ... }AbstractRefreshTokenAuthenticationis removed:SimpleRefreshTokenAuthentication(nowRefreshTokenAuthentication, see above) implementsAuthentication<RefreshTokenCredentials>itself.AuthenticationProvider,DefaultAuthenticationProviderandCompositeAuthentication's constructor are@InternalCoSecApi: the starter registers everyAuthenticationbean.cosec-social:SocialProviderManagerandSocialAuthenticationProviderare@InternalCoSecApi, as are the constructors ofSocialAuthenticationandJustAuthProvider(which named JustAuth'sAuthRequest).JustAuthProvider.name()is removed: readname.The starter's
*Propertiesclasses andEnabledCapableare@InternalCoSecApi, and its@ConditionalOn*annotations areinternal. Thecosec.*keys are the contract and do not change. Read a value with@Value("\${cosec.jwt.enabled}")or theEnvironmentinstead of injecting a CoSec*Propertiesbean, and condition a bean of your own with@ConditionalOnProperty("cosec.jwt.enabled")instead of@ConditionalOnJwtEnabled.checkMono(cosec-webflux) andcheckBlocking(cosec-webmvc) are in Java classes namedAuthorizationCheckers, no longerPipelineWebFilterKtandPipelineServletFilterKt; Kotlin callers do not notice.SuspendingHandlerHolderInterceptoris@InternalCoSecApi: the starter registers it.
cosec-dependenciesno longer manages Guava's version, and no CoSec module brings Guava. An application that takes Guava's version from CoSec's BOM declares it itself.ChangeState.SHADOWEDis removed. No change was ever in that state: a closed shadow window is not a state, it is the change'sshadow(ShadowState.closed). Code that namesChangeState.SHADOWED(awhen, a filter on states, a test) stops compiling: delete the branch. A stored change request cannot carry it, and a"state":"SHADOWED"would not decode; no version wrote one. The states areDRAFT,CHECKED,SHADOWING,AWAITING_APPROVAL,READY,CONFLICTED,PUBLISHED,REJECTED,ABANDONEDandEXPIRED. The change event kindSHADOWED("the window closed") stays, with its log line.A family of documents holds at most its bound plus a stated slack (
SNP-14). Under a burst of cold loads a family could hold about itscosec.authorization.snapshot.max-appsormax-tenantsplus the 4,096 evictions the housekeeping thread had queued. It now holds at most twice the bound and never more than 4,096 above it, plus the documents being loaded at that moment; an install that finds its family over that evicts on the installing thread before it answers. Nothing needs configuring and no default changes; a memory budget made for the old worst case is safe. The property states the number.Retry-AfterandRateLimit-Resetround up, and a report interval under a millisecond fails startup. A429said1for a window with 1.75 s left, so a client that waited as told met the same window; both headers are now the remaining time in whole seconds, rounded up, at least1(1 msand1000 msare1,1001 msis2). Nothing to do: clients wait up to a second longer, andRateLimit-Remainingand-Limitare unchanged. The starter now refusescosec.authorization.shadow.report-intervalbelow1ms(cosec.authorization.shadow.report-interval is at least one millisecond, not …), where it used to start a reporter loop that never suspended: set a value of1msor more (the default is10s).cosec-migrate bootstrapbefore this fix dropped the platform tenant's roles. It rebuilt the platform tenant's document (tenant:(platform)) from its policies, bindings and rate limits only, so the revision of kindBOOTSTRAPit published had noroles. A migration that converted 7.x roles into that document and then ranbootstrap(with or without--force) lost them, and the members of those roles were denied afterwards: it fails closed, never open. It now keeps everything else the document holds. If you ran an earlierbootstrapafter converting roles, check the document, with the control API as the administrator: find the revision whoseprovenance.kindisBOOTSTRAP(GET /documents/tenant:(platform)/revisions, thenGET …/revisions/<n>), and readGET /documents/tenant:(platform)/diff?from=<n-1>&to=<n>: a non-emptyroles.removedis what the bootstrap dropped. Put those roles back with a change (putRoleoperations with the definitions from revision<n-1>). A deployment that bootstrapped before converting roles, or whose platform tenant has no roles, has nothing to do.ControlStoregainsstagedCandidate, andputCandidatewrites over a digest. A candidate is written only over the one the writer read, so a late write by a change that was preempted cannot replace the candidate of the change that took the slot (#1235).suspend fun stagedCandidate(key: SnapshotKey): Versioned<StoredCandidate>?is new, andputCandidate(key, expected: SnapshotDigest?, candidate: StoredCandidate): Booleantakes the digest it expects (null: only if there is none) and answersfalsewhen the candidate changed in between. AControlStoreof your own implements both (CoCacheControlStoreandInMemoryControlStoredo); one whose write has an unknown outcome reads back instead of writing again. Nothing to do for the starter's Redis store.The
cosec-migratecommand line is stricter and takes--name=value.--name valueand--name=valueboth work; a value that starts with--is a usage error (the next option, with its value forgotten, used to be taken as the value): write--name=--valuefor such a value. A flag given twice is--flag is given twice., a flag given a value is--flag takes no value., and a repeated or unknown option is a usage error. A script that relied on an option swallowing the next one fails now: fix its arguments.A control API path parameter is percent-decoded once.
GET /documents/tenant:acme%20westused to read the keytenant:acme%20west, a document that is not thetenant:acme westthe store and the bodies use; the path is now split into segments first and each parameter decoded once (+stays+, an encoded/is part of the value and never a second segment,tenant%3Aacmenamestenant:acme, and the route's own words are matched as written). A client that percent-encoded ids twice, or sent an encoded id and relied on it reaching the control plane as written, names another document now: encode once.An access review lists a break-glass binding.
POST /analyzecounted a break-glass binding (its policy,cosec:root, is defined by no document) among theopaqueones. It is now an entry ofallows, an allow ofcosec:rootfrom the engine's own statement, withbreakGlass: true,expiresAtandconditional: true, since the review does not evaluate the window;conditionalnow also marks any binding that has a window. A client that parses the review sees feweropaqueand newallowsofcosec:rootin the platform tenant's review; a tool that treats every allow as permanent should readconditionalandexpiresAt.A generated route map takes the server prefix per operation, and refuses what it cannot place. The prefix comes from the operation's
servers, else its path item's, else the document's, and a server URL is read by its components://example.test/v1,https://example.test:8443/v1and/v1all give/v1. A document that generated a route map before may be refused now, naming the operation (GET /orders: …): servers of one operation with different paths, a server variable in the path, a server path that does not start with/(v1,example.test:8080/v1,{baseUrl}/v1: relative to where the document was fetched from, which the generator does not know) or a dot segment. Generate the route map again; give the refused document absolute server URLs or paths that start with/.A stored document that does not compile is named, logged and counted.
Causeincosec-modelgainsDocumentInvalid(document, revision, error), so an application that matchesCauseexhaustively withwhenstops compiling: add the branch. The decision is still503(the instance cannot decide);SourceUnavailablenow means the store could not be read. The instance logs oneERRORline per revision, digest and inputs, and oneINFOline when it compiles again; its health names how many documents do not compile and the first ten, with their revisions. Nothing to do beyond thewhen; alert on that log line where you alerted on silence.A request never logs a dropped decision event. When a BEST_EFFORT listener's queue is full or closed, the request only counts the drop; a reporter logs, off the request's thread, one
WARNline per listener and interval (Dropping decision events: the queue of listener [<name>] is full; <n> dropped since the last report., oris closed). A log alert that matched one line per dropped event now sees a count per interval.TraceContextgainstraceState. The parent's W3Ctracestate, opaque,""for none; the three-argument constructor stays. Thecosec.authorizespan inherits it, where it used to start from the default state. It reaches everyDecisionListenerin the event and is vendor data: do not log it. No audit record, Kafka record or metric tag carries it.cosec-testkit's signatures grow.PermittedRequest.withToken(token, verifier, revocations, headers)takes the request's headers (default empty); a header that carries a credential (Authorization,X-API-Key,CoSec-Identity) is refused, and two differentCoSec-Device-Idvalues fail the request as the pipeline does.PipelineFixture.ofandloadtakeroutesandlisteners(defaults: none), andAttributeRequestsbuilds anAttributeRequestfor a provider's tests. The kit's exception takes a cause, and refuses a field given twice in what it reads and two files that hold one document. Source compatible (defaults), binary incompatible: recompile your tests against this version.
From 8.0.0-alpha.3
8.0.0-alpha.3 is a preview with no compatibility promise. What it stored still reads, except its back-reference sets, its approved changes and a document that spells a day of the week another way (below).
The audit record says what decided (batch R7a, #1237).
authorization.sourceis now{ via, document, policy, statement }(Audit events): the oldtyperecorded a tenant's role binding and a boundary asGLOBAL_POLICY. A boundary refusal, which had the sourceNONEand nobinding, now hasviaBOUNDARY, the boundary aspolicy, andbindingboundary:<tenantId>. Consumers of the audit log and of the Kafka topic change with it:Before Now source.typeBLACKLISTsource.viaBUILTINsource.typeROOTsource.viaBINDING,source.policycosec:root(andbreakGlass: truefor a break-glass permit)source.typeROLE_PERMISSIONsource.viaBINDING,source.documentAPPsource.typePRINCIPAL_POLICYsource.viaATTACHMENTsource.typeGLOBAL_POLICYsource.viaBINDING,source.documentPLATFORMorTENANTsource.policy.idsource.policysource.policy.statementsource.statementsource.policy.type,source.role,principal.policies,request.device.userAgentgone: typeonly repeatedsource.type, the others were always emptyIn code:
AuditSourceType,AuditPolicy,AuditRole,AuditPermission, their data classes,PolicyTypeandAuditReasonCode.REGEX_TIMEOUTare gone,AuditViaandAuditDocumentare new, and the attribute keysAuditTrace.TRACE_ID_ATTRIBUTE_KEYandSPAN_ID_ATTRIBUTE_KEY, which nothing read, are removed.Control-plane scale (batch E2b: #1214, #1217, #1218, #1219, and the stage window #1290 left open). An instance writes its status under its own key,
<s>:shadow:status:<instance>, and is listed in<s>:shadow:instances:all, so a heartbeat writes one status however many instances there are; the old<s>:shadow:status:instancesis not read and expires in two minutes. Until an instance runs this version it is not counted when a revision's propagation is read (read-only; publishing never waits for it): upgrade the data-plane instances together, and add~<s>:shadow:instances:*to the key patterns of an instance's Redis ACL (Redis keys). The decisions of one change are taken on one confirmation of the control documents, confirmed again at the end, so a large change no longer reads them twice per entry. In code: aControlStoreof your own returns the non-terminal change requests fromopenChanges()(aList<ChangeRequest>, each read once), and replacesputCandidate(key, candidate)withstagedCandidate(key)andputCandidate(key, expected, candidate): Boolean, a write over the candidate read (Extending).CoCacheShadowReportstakes the list of instances as its fourth store.SnapshotDigest.toString()and the digests of entries are unchanged, only faster.Shutdown waits for the Kafka audit (batch R7a, #1250).
KafkaAuditListenerwaits up tocosec.observability.listener.drain-timeoutfor the sends it still holds and the broker's answers, so the producer is closed after them. A shutdown can take that timeout twice, once for the listeners' queues and once here: check the pod's termination grace period.The
authorizationcookie is read only on request (batch R6,PIP-13). A request whose only credential is that cookie is now anonymous. A browser sends a cookie on its own, on a cross-site request too, so reading it by default made every deployment answer for CSRF. Send the token in theAuthorizationheader, or setcosec.pipeline.allow-cookie-token=trueand defend against CSRF yourself (Authentication). A gateway removes the cookie from what it forwards either way.CoSec-App-Id,CoSec-Space-IdandCoSec-Device-Idare headers only (batch R6,SCP-4). A query parameter of one of these names is no longer read: it sets nothing, and it no longer makes a request ambiguous. Clients that send them in the URL send headers instead (App and space).An unknown
cosec.*key always fails startup (batch R6,SNP-9).cosec.unknown-propertiesandUnknownPropertiesModeare gone, and setting the property is now itself an unknown key: remove it. The message lists the keys and links the table of removed and renamed keys rather than naming a replacement for each.A stored API key without
formatfails like any other wrong format (batch R6): the message isAPI key format [null] is not 2.. Such a key was already refused;cosec-migrate api-keysstill converts it.Roles and short-form permissions (RFC 0012). A catalog entry can define its permission with
actionandresource, and app and tenant documents can holdroles(Role permissions).schemastays 2, and nothing already published changes meaning. A document with either is not readable by an older instance, whose strict reader refuses the unknown fields and fails it closed: upgrade every data-plane instance before publishing such a document. A change may no longer put a policy or binding id starting withrole:; what already holds one stays readable.GET /documents/{key}/difflistsroles, and reports policies and bindings of the expanded document.POST /analyzeno longer counts a tenant's binding of a readable app's permission as opaque. In code:OperationhasPutRoleandRemoveRole, andDocumentDiff,CatalogPermissionandPolicyDocumentgained fields.Control-plane correctness (audit batch E2a: #1205, #1206, #1207, #1210, #1226, #1227). A revision diff's
sectionscompares the catalog, limits, attributes, boundary and rate limits by their content: a rule of the same id with another quota is a change.POST /analyzelists only the bindings that can apply in the tenant asked about, so a platform binding of another tenant's principal or role is no longer listed. An instance forgets a shadow window once its candidate is withdrawn and its last report is written. In code: aControlStoreof your own implementswithdrawCandidate(key, window)(putCandidatetakes a candidate, no longernull),referrersandputReferrerswith each referrer's revision (Map<SnapshotKey, Long>), and keepsRevisionIndex.reclaiming;releaseLeasemust check and remove in one step (Extending).ShadowRecorder.recordtakes the window's document first,forgettakes the samples its last report counted, andShadowReportertakes theCandidateStoreit reads ended windows from.Upgrade the control-plane instances together, and rebuild the back-reference sets (batch R4). A back-reference set (
<p>:control:refs:*) reads only as an object of each referrer and its revision. The JSON array of document keys alpha.3 wrote is a format error: a publish that touches one fails, andcosec-migrate repair-referencesreads a set before it writes it, so it cannot get past one either. Stop the alpha.3 control-plane instances, delete those keys, run this version'scosec-migrate repair-references, which writes each set again from the heads with each referrer's revision, and only then start this version's control-plane instances. An alpha.3 control-plane instance cannot read a set written that way, nor a revision index that lists records left to delete, and fails closed on them: its publishes that touch one fail, and its reclamation of that document stops. Data-plane instances need no order: an alpha.3 instance only keeps writing the reports of ended shadow windows.Stored approvals and confirmations have one shape (batch R4). A stored approval always has
memberships,attributes,principalBindings,breakGlass,credentialIdandissuedAt,nullwhere there is none, and one without them is a format error. Publish or abandon every open change that has an approval before you upgrade, or remove its record afterwards (<p>:control:change:<id>): while one is open, it answers503and every maintenance pass stops and reclaims nothing. Adeny-nomatchconfirmation's digest is always over{statement, policyCondition}, so one given before the upgrade for a policy without a condition no longer matches: its change is refused until the statement is confirmed again (428). A published document keeps its confirmation.One spelling for a day of the week (batch R5).
daysOfWeektakes exactlyMON,TUE,WED,THU,FRI,SATandSUN, the names the schema and the policy language have always listed.MONDAY,monandFrino longer compile: a change that writes one is refused, and a stored document that holds one is installed as failed, so the requests that read it answer503. Publish such documents with the three-letter names before you upgrade.cosec-migratenow writes those names, and still reads any spelling 7.x accepted.An empty
tenantIdclaim makes the token invalid (batch R5,IDN-11), where it used to mean the default tenant(0): read as no tenant, it put the principal in the default tenant with the token's roles. The request is evaluated as anonymous, so a deny is401 token-invalid, and refreshing such a token fails. A token with notenantIdclaim stays in the default tenant. The principal of a customTokenVerifieris held to the same rule, andJwtTokenConverterthrowsIllegalArgumentExceptionfor a principal whose tenant id is empty: give it no tenant, orSimpleTenant.DEFAULT.Rate limit counters have one form (batch R5). Every rule counts under its document and its id: a platform rule under
platform/<id>where it had its bare id, and app and tenant rules as before (app:<appId>/<id>,tenant:<tenantId>/<id>). A keyed bucket isk:<value>, no longerg:<value>. Rule ids in documents do not change. The Redis counters start again, so each rule's current window begins with its full quota, and while two versions serve they count apart. ARateLimiterof your own, and anything that readsCause.RateLimiterUnavailable.ruleIdorBasis.RateLimited.ruleId, sees the new names.Three groups of properties are renamed. An old key fails startup as unknown:
Old key New key cosec.pipeline.gateway.max-age,cosec.pipeline.gateway.max-sizecosec.pipeline.identity.max-age,cosec.pipeline.identity.max-sizecosec.audit.required.timeoutcosec.observability.listener.required-timeoutcosec.authorization.cache.token.*cosec.authentication.revocation.cache.*Route maps are opt-in.
cosec.authorization.routes.locationis unset by default, and a host without it loads no route map, so a WebFlux or Spring MVC service that has none needs no setting. A service that relies onclasspath:cosec-routes.jsonbeing read by default fails startup with a message that says what to do: set the property to that location. A map with no routes no longer loads (Route maps).cosec.jwt.enableddefaults tofalsewithcosec.pipeline.mode=gateway. A service behind a gateway that issues tokens sets it totrue; without it aTokenConverteris missing where one is injected. Nothing changes inenforcemode.cosec:tenant-adminalso holdscosec:skip-shadow, on its own tenant's document only (CTL-27), which widens what a tenant administrator can do: it skips a window with a recorded reason, and a change that only narrows takes a busy slot on that document. Grant analysis and approval are unchanged. To keep the old behaviour, bind a policy of your own instead (The control plane).cosec-cocachewithout aCacheRuntimefails startup, namingme.ahoo.cocache:cocache-spring-boot-starter. That combination could not work: it ended in a misleading error or an instance that never became ready.The
cosecServiceGeneratorendpoint reads what springdoc scanned, and needsspringdoc-openapi-starter-webflux-apior-webmvc-api. AnOpenAPIbean alone no longer makes it generate; a scan that found no operation is an error rather than an empty document.AuthorizationChecker.decideAsanddecide(security, app, action, resource)are@InternalCoSecApi: they are the control plane's, and an application never opts in. Check as the request's own principal withcheckanddecide(Checks in code).
From 8.0.0-alpha.2
8.0.0-alpha.2 is a preview with no compatibility promise. These changes since then, from the RC security review, make the grant analysis read the author's rights as enforcement does, so some changes that published alone now wait for approval (Testing policies). Nothing to migrate in the documents' content, but 8.0.0 stores its data through CoCache 8, which does not read what alpha.2 wrote through CoCache 6: move it with cosec-migrate cocache8 of 8.0.0-alpha.4, the last tool that has it, every instance stopped (Data written through CoCache 6). Those at the gateway and the edge of tenant isolation (RC1-5, RC1-6, RC1-15 to RC1-18, RC1-48, RC1-49), from Identity forwarding on, change what a gateway forwards and to which routes: read them before upgrading a gateway.
- A store upgraded from 8.0.0-alpha.2 runs
cosec-migrate repair-referencesonce, so that the list of app documents (<s>:control:list:documents) is complete (Storage). - Token attributes of every type (RC1-2,
GRT-5). The analysis readssubject.attributes.*as the engine does, a boolean or a number as its text. An author whose ALLOW is conditioned on not beingsuspendedno longer counts as holding it when the token says"suspended": true. In code,Operator.attributesandGrantor.attributesareMap<String, Any>, the token's claim as is, where alpha.2 kept only the strings. - Expiring bindings (RC1-3,
GRT-3). What an author holds through a binding withexpiresAtcovers only grants whose own binding expires no later; a grant withoutexpiresAt, a later one, or making a policy attachable is an escalation with the shortfallEXPIRY. - Removing a tenant policy whose id the platform defines (RC1-9,
GRT-4) is analyzed as granting the platform's policy to the tenant's bindings and attachments of that id. An id both define grants the author nothing. - Every app document (RC1-4,
GRT-6). The analysis of a tenant change reads every app document the app list names (<s>:control:apps:all, Storage), not only those the change names, so a DENY an app binds to one of the author's roles limits what the author may grant in every scope that reaches that app. An app document that cannot be read makes such a grant an escalation (UNREADABLE). The analysis trusts the app list only once it is complete, and an upgraded store's list is not: untilcosec-migrate repair-referenceshas run after the upgrade, every tenant grant over every app (a binding with app*, or an attachment, also one a condition narrows to apps the change does not name) needs an approval (UNREADABLE), and the control plane logs a WARN that names the command, at most once a minute. - A platform policy cannot take a tenant's id (RC1-9,
CTL-21). A platform change that adds a policy whose id a tenant document defines or binds is refused (V2,422, naming the tenant documents). A tenant that defines the id itself no longer blocks the platform from removing its own policy of that id. The back-reference index learns only the ids a tenant adds after the upgrade; the ones its document already had enter it only throughrepair-references: once every control-plane instance and everycosec-migratebinary runs this version, runcosec-migrate repair-referencesonce, as a Kubernetes Job, with the Redis and key prefix of the control plane, and again after any downgrade. Until it has run, a platform policy that takes the id of a tenant's own policy from before the upgrade is not refused, only ambiguous in that tenant, which enforcement fails closed on. - Escalations gain the reasons
UNRESOLVED(a new binding of a policy no document defines, RC1-32),UNREADABLE(RC1-4) andTENANT_BINDING(each tenant binding an app document change widens, RC1-34,APR-6).TENANT_BINDINGis informational: the app change needs its approval forNOT_ANALYZED, and the entry names only the binding and its tenant document. Code that matches everyUnknownReasonorShortfallgainsUNRESOLVED,UNREADABLEandEXPIRY. - Moved heads after a publish (RC1-33). When another document a change was checked with, or the app list, moved before its write, the control plane records
HEADS_MOVEDorREVIEW_NEEDEDafterPUBLISHED, with the heads in a newmovedmember (What a publish compares). A change listener that handles everyChangeEvent.Kindgains the two. - The trust root is the platform's (RC1-10,
APR-3). Only a platform principal holdingcosec:approvepublishes its own changes unanalyzed; a tenant principal the platform gavecosec:approvenow has its own changes analyzed, and approves others'. A tenant's boundary is the platform's: a tenant principal'sSetBoundaryis403, so is itsapplywithREPLACEor a rollback that would remove or change the boundary the platform set, and only a platform principal approves, rejects or abandons a change that sets one (BDY-2). An API key is never the trust root, even for a platform principal holdingcosec:approve; nor is any credential namedapi-key, a forwarded identity's included. Underfour-eyes, a platform principal's change needs another platform principal's approval. cosec:platform-adminis bound only by the platform (RC1-36,TNT-2): in the platform document, or the platform tenant's own, asbootstrapwrites it. A tenant or app document that binds it no longer compiles; remove such a binding before upgrading.- Approvals are a person's, and checked again (RC1-11,
APR-7,APR-8). A principal that authenticated with an API key cannot approve (403). An approval records the approver's credential (jti,iat); revoking that token, or the approver's tokens, before the change publishes takes the approval back. An approver whose memberships come from the membership provider must be permitted both on the roles it held then and still holds and on what the provider answers now; the starter now gives the control plane the application'sMembershipProvider(RC1-13). An approval that records no credential id does not count: every change approved before the upgrade goes back toAWAITING_APPROVALat publish, and is approved again; a credential without an id cannot approve (403). The API's view of a change (GET /changes/{id}and the answers of its steps) no longer shows the approval'smemberships,attributes,credentialIdorissuedAt. In code,AuthenticatedPrincipalhasissuedAtandapiKey. - The starter checks how approvals are revoked. The control plane needs a revocation reader, as the pipeline does: a
RevocationReaderbean, or CoSec's tokens withcosec-cocache; startup fails without one (declareRevocationReader.NONEwhen no approver's credential is ever revoked). Startup also fails whencosec.jwt.token-validity.refresh, how long a revocation is kept, is shorter thancosec.control.approval.expire-after. - A busy staging slot can be taken (RC1-12,
CTL-22,BRK-9): by a break-glass revoke, and by a change that only narrows, staged by a holder ofcosec:skip-shadow(Taking a busy slot). The change that held it becomesCONFLICTED. A publish retried after its answer was lost reportsPUBLISHED. Anyonein tenant(0)(RC1-35,GRT-7): such a grant reaches unauthenticated callers, and needs an approval (ANONYMOUS). Code that matches everyUnknownReasongainsANONYMOUS.- The default space in control-plane resources is
(default)(RC1-37,SCP-9), and space ids beginning with(are CoSec's: a request that declares one is403(scope-rejected), and a document binding in one does not compile. A control-plane policy written forscope/<tenant>/<app>/-now means the space named-; writescope/<tenant>/<app>/(default)for the default space. A control-plane DENY onscope/*/*/-no longer applies to the default space: rewrite it asscope/*/*/(default)before upgrading, or the grants it held back are allowed. A binding in a space whose id begins with(stops its document compiling, and a request in such a space is refused: before upgrading, look for"space": "(in every document, move such bindings to a space id of yours, and move the memberships of that space with them. - Break-glass (RC1-27, RC1-29, RC1-30):
cosec-migratewrites no break-glass binding (Root becomes break-glass);BreakGlass.requestderives the binding's id and has nobindingparameter; approving break-glass needs a REQUIRED change listener (503otherwise,BRK-3). - Revoking break-glass answers by its effect (R4-1).
DELETE /break-glass/{bindingId}answers200only once the binding no longer grants on the platform document's head, whoever removed it. A revoke that leaves it granting is now409, itsdetailnaming the state of the caller's change (CONFLICTED, ...), where it was200with that change before: a client that read200as "revoked" without looking atstatemust handle the409. A binding id the platform document does not have is now404, and a binding of that id that is not a break-glass binding, live or expired,409(binding [<id>] is not a break-glass binding); neither proposes anything, where both answered200with aDRAFTchange (BRK-11). A revoke preempted by another revoke, or meeting a moved head, revokes again, at most three more times. - Abandoning (RC1-51,
BRK-10). Only its author abandons a revoke of a break-glass binding that still grants: anyone else, the principal it revokes included, is403. Revoke the binding again instead, which publishes the stalled revoke or takes its slot. Every abandon is recorded as a new change event,ABANDONED; abandoning a break-glass change needs a REQUIRED change listener (503otherwise). A change listener that handles everyChangeEvent.KindgainsABANDONED. - Identity forwarding is opt-in by scheme (RC1-49,
IDN-7). The gateway forwardsCoSec-Identityonly to a route to a registered service (uri: lb://...,lb:ws://...) or one whose metadata sayscosec-identity: true;falsestill keeps it from any route, and any value buttruereads asfalse. A route to one of your services byhttp://orhttps://stops receiving the identity, and the service behind it sees anonymous requests: before upgrading the gateway, addcosec-identity: trueto the metadata of those routes, and of no route to a third party (Forwarding the identity). The request attributecosec.identity.forwardis nowtrueorfalseon every routed request, where it was set only tofalse. - No credential goes downstream (RC1-5,
IDN-8). BesidesAuthorization, the gateway removes the API key header (cosec.pipeline.api-key-header, under whatever name it gives) and theauthorizationquery parameter from every request it forwards, whether or not the gateway itself reads a token from the query (only withcosec.pipeline.allow-query-token=true, which is off by default). A service that reads them itself needscosec.gateway.identity.forward-authorization=true; with it, they now go only to the routes that would receive the identity (lb://, orcosec-identity: true), so a route to a third party gets none. - The
authorizationcookie stays at the gateway too (IDN-8). Under the same switch, the gateway removes it from eachCookieheader it forwards, its name matched ignoring case, and keeps the other cookies; a header left with no cookie is not sent. A service that reads its token from that cookie needsforward-authorization=trueand a route that would receive the identity. - A route names its app (RC1-6,
SCP-2). Route metadatacosec-app-idis the app of the route's requests, ahead ofcosec.authorization.scope.app-id: on such a route a request that declares another app is403scope-rejected(401for an anonymous caller), and one that declares none gets the route's app, its role bindings and its DENYs. A route without it keeps the gateway's host app, or the client's. On a gateway that fronts several apps, give each route its app. Acosec-app-idthat is not a string, or cannot be an app id, fails every request of its route: quote a numeric app id. - Actuator on a gateway (RC1-48,
STA-2). A gateway host that decides with policies no longer starts while an actuator endpoint other thanhealthis exposed over HTTP on its application port (management.server.portunset, or the same asserver.port): CoSec authorizes the gateway's routes, not those endpoints. Serve actuator on its own port behind a network policy, expose onlyhealth, or list in the new propertycosec.gateway.unprotected-endpointsthe endpoints something else protects; it never acceptsgateway(Actuator on a gateway).cosec-gateway-serverandk8s/expose onlyhealth. - A blank
CoSec-*value beside another is ambiguous (RC1-16,SCP-4):?CoSec-Space-Id=with the headerCoSec-Space-Id: s1is now400invalid-request, wheres1applied. Blank means ASCII whitespace only, so a value of Unicode spaces, such as%E3%80%80, is a value: alone, it is a space the principal must have a role in. Send each parameter once. - App ids refuse control characters (RC1-15,
SCP-10), as tenant ids do: a declared app with one is403scope-rejected(401for an anonymous caller), and a host app with one fails startup. - Ids refuse unpaired UTF-16 surrogates (RC1-52,
IDN-10). A JSON token or body can write one as an escape ("beta\uD800"), and a Redis key holds?in its place, so tenantbeta\uD800read the documents of tenantbeta?, and a principal's memberships and revocations, and a rate limit bucket, were shared the same way. Now a token that claims one in itssub,tenantId,jti,rolesorpoliciesis401token-invalid, and CoSec's own issuer refuses to sign one (login fails); aCoSec-Identitythat names one is400; a control request that holds one anywhere in its path, query or body is400; an authenticator, an API key record or a membership provider that gives one fails the request with503; an app or tenant id with one is refused as one with a control character is. A rate limitkeyvalue with one counts in a bucket of its own (e:and the value, escaped). Ids with surrogate pairs, such as an emoji, are unchanged. Log lines and messages write such a surrogate as\uXXXX, never?. In code,Identifiers(cosec-model) holds the rule;ApiKeyandAuthenticatedPrincipalrefuse such ids when made, andRevokedTokenCache.key,RevokedSubjectCache.keyandMembershipCache.keythrow for them. Nothing to migrate; where a token issuer or a script could have sent such ids, what is stored under the id with?may have been written for the other. - The control plane takes only app ids (
SCP-10). An app id is not blank, not*, has no:and no control character, and has at most 128 characters; earlier builds took any app without:. A binding in any other app is now aV2finding (400) at$.bindings[i].app, wherever it is in the candidate.analyzeanswers400for such an app. Before upgrading the control plane, remove the tenant bindings in such apps, abandon the open changes of such app documents, and empty the app documents published under such ids (publish each with no policies and no bindings), which drops their back-references. Nothing can be done about them afterwards, and what is left behind is a format error that fails closed, never skipped: a document that keeps such a binding still reads, and the binding grants nothing, but neither a publish norrepair-referencesgets past it; an open change of such an app answers503and stops every maintenance pass until its record is removed; an app list entry makes every app a grant reaches unknown until you delete<p>:control:apps:alland runcosec-migrate repair-references; a back-reference naming such an app fails whatever reads that set until you delete the set and runrepair-references; and an instance's status entry fails the read of the instance statuses until it expires, two minutes after that instance last wrote it. - Enforcing hosts drop a client's
CoSec-Identity(RC1-18,IDN-9). A WebFlux or Spring MVC host inenforcemode removes the header from the request its handler sees, so it never relays one a client wrote. Code that read it there read what any client could write; read theSecurityContext. - A tenant's grant of an app's permission to
Anyoneor a principal resolves (RC1-17,TNT-4). A request in that app now reads the app's document whatever the principal's roles, so the binding's DENY or ALLOW applies, where every such request was503, and so do the app document's rate limit rules.simulate,explainand shadow windows read it by the same rule (CTL-3). In code,CompiledDocument.tenanttakes the setboundApps, andCompiledDocument.needsAppanswers it; aShadowListenerbuilt by hand needs the installed views (views) to compare a tenant candidate that makes a request read an app document, and reportsCANDIDATE_ERRORwithout them. - One key prefix (RC1-46,
SNP-9).cosec.key-prefixreplacescosec.authorization.snapshot.key-prefix,cosec.authorization.cache.key-prefixandcosec.api-key.key-prefix. An environment that still sets one of them fails startup, as any key CoSec does not read does. Every key lives under it: API keys under<p>:api-key, rate limit counters under<p>:rate-limiterand the social login's OAuth states under<p>:oauth:state, which were fixed (Redis keys). With the defaults every key stays where it was. A deployment that set one of the three setscosec.key-prefixto its snapshot prefix instead; revocations and API keys kept under another prefix are no longer read, so a token revoked there would be accepted again: before switching, copy each such key under the new prefix (COPY, orRENAME, which keeps its expiry). Memberships fill again on their own. With<p>the value ofcosec.key-prefix, the families move:- snapshot documents, control-plane records, candidates and shadow reports: from the old
cosec.authorization.snapshot.key-prefix(defaultcosec) to<p>; - token revocations and memberships: from the old
cosec.authorization.cache.key-prefix(defaultcosec) to<p>, except the memberships of a membership cache the application made itself, which stay under its own prefix; - API keys: from the old
cosec.api-key.key-prefix(defaultcosec:api-key) to<p>:api-key; - rate limit counters and the social login's OAuth states: from
cosecto<p>.cosec-migrate api-keysno longer takes--api-key-prefix: it converts the keys under<--key-prefix>:api-key.
- snapshot documents, control-plane records, candidates and shadow reports: from the old
revalidate-intervalcannot turn the periodic pass off (RC1-50,SNP-6). The pass is the only bound on a change whose invalidation message was lost, socosec.authorization.snapshot.revalidate-intervalmust be at least1s(each pass reads every installed document from Redis), at most5m, less thanlag-warnand, withfail-closed.tenants, less thanfail-closed.max-lag; anything else fails startup naming the property, andSnapshotOptionsrefuses the same. Replace a0with an interval within the bounds; a longer one lowers what revalidation costs Redis (Storage).- Path patterns have cost bounds (RC1-8,
DOC-4). Anhttp:path:pattern is at most 2,048 characters, a segment that mixes*,?or{name}with other text holds at most 16 parts (consecutive*count once), a document's such segments hold at most 2,048 glob units in all (their parts and the characters of their text, twice after a leading**and for a rate limit rule keyed by a captured variable), and a typed pattern is at most 2,058 characters (Policy language). The control plane answers a change over them with aCOMPILEfinding (422) at the pattern or at$. A document published before with such a pattern no longer compiles on an upgraded instance, and every request that reads it fails closed: rewrite it and publish before upgrading the data plane. - A policy is evaluated once per pass for each document that binds it (
ALG-9), however many of the document's bindings apply, and a policy claimed twice among the attachments is attached once. The decision and the statement and binding it reports do not change: the first binding in candidate order reports. A trace lists the later bindings with the first one's outcomes, without evaluating them again. - A repeated header that a document reads is
400(RC1-38,PIP-12). When a request sends a header with different values, and any statement, policy condition, boundary or rate limit key of the documents its view reads reads that header (OriginandRefererincluded), the pipeline answers400invalid-requestbefore evaluating, where a DENY on it made the request503and an ALLOW on it did not match. Identical repeats are one value (Web). - A malformed
roles,policiesorattributesclaim is an invalid token (PIP-6):401token-invalid, evaluated as anonymous, where it was a500. - Duplicate keys are refused everywhere (RC1-44,
DOC-5). Every stored format (API keys, memberships, shadow reports, revocations) and every control-plane request body with a duplicate key fails to read: a stored value is503, a request body400.cosec-migraterefuses 7.x exports and files with duplicate keys too. - CoSec's caches keep their pins whoever builds them (RC1-45,
SNP-3).createPolicySnapshotCacheapplies the store-of-record policy, the snapshot's codec and no key filter, per-entry TTL or loader to any spec, and aCacheSpecCustomizerno longer changes a CoSec cache's codec, loaders, key filter or per-entry TTL. - A compilation that overflows the stack fails the document closed (RC1-43,
SNP-8), as any compile error does, instead of keeping the revision before it. - Rate limits count on a Redis Cluster (#1229,
OBL-4). The Redis limiter's counters move to<p>:rate-limiter:{<rule>:<bucket>}:<window>: the hash tag keeps the two windows of a bucket, which its script reads together, on one slot. On a cluster every call failed withCROSSSLOT, so a rule withoutstrictFailurewas skipped and limited nothing, and one with it made every permitted request503. On a single Redis only the keys change. During a rolling upgrade, instances of each version count in their own keys: while instances of both versions serve, and for up to two windows after the last old one stops, a rule lets through up to twice its limit. The old keys expire after two windows. Acosec.key-prefixwhose first{is immediately followed by}(an empty hash tag) now fails startup. - A boundary's external attributes are fetched (#1208,
ATR-8). The attribute plan holds the attributes of the boundary that holds the request, its statements' and its policy condition's, so a stage-B provider is asked for them. A request such a boundary allows was503(BoundaryUnavailable) and now proceeds; providers may be asked for more attributes per request. - A check fetches the attributes it needs (#1209,
ATR-8).AuthorizationCheckerasks the providers for every attribute its action and resource read, a stage-A provider included (without the scope, as stage A asks), where a stage-A attribute was unavailable (AttributeUnavailable) unless some stage-B provider was registered. A stage-A provider is now called by each check that needs one of its attributes. - Providers are asked for fewer attributes (#1211,
ATR-8). The attribute plan walks the statements the evaluation visits, those the statement index gives, instead of every statement whose action matches: a statement whose resource path cannot match the request plans nothing, nor does its policy condition. A stage-B provider is no longer called for a request that no statement reading its attribute can match. What a request is decided on does not change. - One revalidation pass at a time (#1215,
SNP-6). A periodic pass that outlastsrevalidate-intervalis no longer joined by another: the next starts as soon as it ends, so a slow Redis sees at most four revalidation reads from an instance at once. A change whose invalidation was lost is installed by the first pass that reaches its document, which can then take longer than one interval (Storage). - Identity claims of every standard number type (#1228). A gateway forwards a claim that is a
Byte, aShort, aBigIntegerwithin aLong, aFloat, or aBigDecimalthat aDoubleholds exactly, where the request was500. A number the header cannot hold exactly is still refused with500, and so areNaNand the infinities, which JSON has no number for. simulateandexplainare decided and authorized on the tenant that decides the request (RC1-40,CTL-23). A request without aprincipalis decided on(0)'s document, as enforcement decides it: it needscosec:simulateorcosec:explainon(0), where alpha.2 checked the tenant the request named, and one that names another tenant is400. Simulate an anonymous request with"tenant": "(0)", by a principal that may simulate there.simulateandexplainrefuse what enforcement refuses (CTL-3,PIP-12): a request that sends a header its documents read with different values is400, where it was decided (Indeterminate for a DENY on it), and ahttpresource goes through the path normalization a request's path does: a path enforcement refuses (a dot segment, a malformed escape, over 2,048 characters or 256 per segment) is400, and path parameters are removed before deciding, where the path was decided as written; a typed id over those lengths is400.analyzetakes its resource the same way.- The control API's
400says less, and a stored value that does not decode is500(RC1-39). A400'sdetailis one of the control plane's own checks, or names the field that does not parse; it no longer carries a parser's or an exception's message (No enum constant ...,For input string ..., a JSON parser's), and a time that does not parse (expiresAt,time) is400where it was500. A stored document or record that does not decode is500without detail, where it was a400with the stored document's JSON path; the control host logs it with its key. A client that matched ondetailtext should match on the status andcode. - A lone surrogate half in a path pattern does not compile (review L4 of #1200): half of a pair, without the other, in the text of an
http:path:pattern is aCOMPILEfinding, where it compiled and could match the middle of a pair, which Spring never matches. A document published before with one fails closed on an upgraded instance. - CoSec's Redis templates read from the primary (RC1-47): a
LettuceConnectionFactorythat reads from replicas, byspring.data.redis.lettuce.read-fromor a client customizer, fails startup (Redis requirements). And a new health indicator,cosecSnapshotEviction, isDOWNwhile Redis may evict the snapshot, read everyrevalidate-interval; a policy it cannot read isDOWNundereviction-check: fail, andUPwitheviction: unknownunderwarn. It is an alert:cosecSnapshotdoes not change, and only it belongs in the readiness group. - During a rolling upgrade, an app document an older instance creates is not in the app list; newer instances find it when they start and at each reclamation pass (
cosec.control.revisions.reclaim-interval, 1 hour by default), and until then may analyze a grant without that app's DENYs. Create no app through an older instance while you roll, or lowerreclaim-intervalfor the duration. An older instance also still takes a tenant principal holdingcosec:approvefor the trust root, and accepts an API key's approval: approve and publish through upgraded instances only until the roll is done. An approval an older instance accepted names no credential, so an upgraded instance does not publish on it. - Public API nothing used is gone.
KafkaAuditEventSink:KafkaAuditListeneris what the starter registers, and it writes the same key and value.SimpleSecurityContextand its extensionCoSecPrincipal.tenant: the pipeline makes the request'sSecurityContext, and a test mocks or implements the interface. Of the engine's request,AuthzRequest.scope, the classme.ahoo.cosec.model.Scope, andSubject.roles,policiesandroot, none of which the engine read: code that builds anAuthzRequestor aSubjectdrops those arguments. The engine's tenant, roles and attachments are inEngineRequest.scopeandEngineRequest.memberships.Subject.tenantIdstays, for a stage-AAttributeProvider, which runs before there is a scope.
Data written through CoCache 6
8.0.0-alpha.2 kept its data in Redis through CoCache 6; 8.0.0 keeps it through CoCache 8, under the same keys, and CoCache 8 does not read CoCache 6's format. What it finds in that format fails closed, as unreadable content: a request that needs such a document is 503 (SourceUnavailable), a token or principal revoked there is 503 instead of 401, and the control API answers 500. Nothing reads such a value as absent, so a revoked token is never accepted again.
8.0.0's cosec-migrate no longer has the command that moves it: follow the steps below with the cosec-migrate of 8.0.0-alpha.4, before upgrading to 8.0.0 (From 8.0.0-alpha.4).
| Data | Keys | On 8.0.0, before the move | cosec-migrate cocache8 |
|---|---|---|---|
| Snapshot documents | <p>:snapshot:* | 503 for every request that reads one | Published again as revision 1 of each document (provenance MIGRATE, no parent: the parent's SHA-1 digest is none CoCache 8 knows) |
| Revocations | <p>:token:revoked:*, <p>:token:subject:revoked:* | 503 for the revoked token or principal | Written again, each with what remains of its lifetime |
| Control-plane records | <p>:control:* | The control API answers 500 | Deleted: the history starts again with the published documents |
| Candidates and shadow reports | <p>:candidate:*, <p>:shadow:* | The shadow window cannot report | Deleted; a change still in flight refuses the run (below) |
| Memberships | <p>:membership:* | Loaded again from the MembershipLoader | Deleted; they fill again |
| API keys, rate limit counters, OAuth states | <p>:api-key:*, <p>:rate-limiter:*, <p>:oauth:state:* | Unchanged: kept by Spring's Redis template, not CoCache | Nothing |
- Publish or abandon every change in flight, and end every break-glass grant: the run refuses an open change (a draft included), a staging slot or a candidate unless told
--discard-pending, and refuses a document that holds a break-glass binding, aspublishdoes. - If alpha.2 set one of the key prefixes that
cosec.key-prefixreplaced, move those keys first ("One key prefix", above): the command reads one prefix. - Stop every CoSec instance, the control plane included. An alpha.2 instance and an 8.0.0 instance read neither each other's values nor each other's invalidations, whose channels are named after the key prefix in CoCache 8.
- See what would move, writing nothing:
cosec-migrate cocache8 --redis redis://localhost:6379 --key-prefix cosec --out ./cocache8 --dry-run(--clusterwith the seed nodes of a Redis Cluster). It lists what it refuses and why: a change still open, a draft included, a documentpublishwould refuse, a value it cannot read, or neither a document to move nor a platform document. - Run it without
--dry-run. It writes the documents to--outfirst, in the layoutpublishreads, and a marker,<p>:meta:cocache8, then the revocations (a write over the CoCache 6 value, so none is ever missing), then deletes the other CoCache 6 values, then publishes the documents, and removes the marker. If it stops after the deletions, do not runcocache8again to finish: it cannot see the documents it deleted, and it refuses while the marker is there. Finish with the command it prints,cosec-migrate publish --to-redis <uri> --key-prefix <p> [--cluster] --in ./cocache8 --resume, which removes the marker once every document is published again: alpha.4'spublish, since 8.0.0's refuses while the marker is there. - Start the 8.0.0 instances. Each document's revision starts again at 1; the history before the move is not carried over, so keep a copy of
<p>:control:revision:*before step 5 if you need it.
Digests are SHA-256 now, where alpha.2's were CoCache 6's SHA-1: the control API's revision history, a change's base and checks, and the events that name a digest write SHA-256:<64 hex>. A SnapshotDocumentStore of your own must produce 32-byte SHA-256 digests, or every read fails closed (Extending).
From 8.0.0-alpha.1
8.0.0-alpha.1 is a preview with no compatibility promise. These changes since then, from the RC security review, break decisions, code or configuration written against it. A 7.x deployment reads them in the sections below.
- The
cosec.gateway.*variables Kubernetes sets from a Service (COSEC_GATEWAY_SERVICE_HOSTand the like) were refused at startup by 8.0.0-alpha.1 ascosec.*keys CoSec does not read. Since alpha.2 the check skips exactly these variables;enableServiceLinks: falsein the manifests keeps them out anyway (Deployment). - A role cap removes ALLOWs only (RC1-1,
BND-9,IDN-2). A capped credential (an API key withroles) still gets no grant from its principal's attached policies and principal bindings, but their DENYs now apply to it: a request its principal is denied is denied to every key of the principal, capped or not. In alpha.1 a cap dropped those DENYs too, so a capped key could do what its principal could not. Nothing to migrate; to see which requests change,simulatethem withprincipalBindings: false(Testing policies). The grant analysis counts a capped author's DENYs the same way. - Break-glass by provenance (RC1-26,
BRK-8). Only a token CoSec's ownJwtTokenVerifierverified gets break-glass. ATokenAuthenticatoraround anotherTokenVerifierauthenticates its tokens without break-glass, and names their credential after itsmethod(tokenby default) rather thanjwt. The methodjwtis reserved:AuthenticatedPrincipalrefuses a credential of that method from your code (IllegalArgumentException, so a503), andTokenAuthenticatorrefusesmethod = "jwt"for a verifier that is not CoSec's. Name your authenticator's method after its credential (Extending). - A renamed API key header is a credential header (RC1-21,
CND-5). Withcosec.pipeline.api-key-headerset, a document that reads that header (a condition or a rate limitkey) no longer compiles, in the control plane or on an instance, and the pipeline never reads it for a condition. Remove such references before upgrading. In code,ConditionChecker,PolicyDocumentCompiler.forPlatformandof,PlatformCompiler,ChangeChecks,SimulatorandHttpAttributestake the header as a new parameter. - A
tenantIdclaim that is not a string makes the token invalid (RC1-22), where alpha.1 read it as the default tenant(0). Issue the tenant as a string. - The tenant switch re-derives memberships (RC1-23).
AbstractSwitchTenantAuthentication.switchTenantanswers aTenantMembership, the user's roles, policies and attributes in the target tenant (orTenantMembership.fromProvider()), instead of a principal, andauthenticatebuilds the new principal from it alone. An implementation that wrappedpreviousPrincipalcarried the previous tenant's roles into the new token (Tenants). - The JWT secret has a minimum length (RC1-24): 32, 48 or 64 UTF-8 bytes for
hmac256,hmac384orhmac512. A shortercosec.jwt.secretfails startup; set a longer one on the issuer and every verifier, which makes the tokens issued with the old one invalid. - Social login signs only what the provider owns (RC1-25).
DirectSocialUserPrincipalConvertergives the principal two attributes,cosec_oauth_providerandcosec_oauth_user_id, instead of the provider's raw user info, which the user edits, and no longer writes into theSocialUserit converts. A token whoseattributesnameapiKeyId, which CoSec sets for API keys, is refused astoken-invalid, andJwtTokenConverterdoes not issue one. To keep profile fields, declare your ownSocialUserPrincipalConverterand keep only fields the user cannot change (Social login).