Skip to content

Choosing a Deployment ​

For an operator or an architect deciding which processes run CoSec and what each one needs. Every topology below is a set of Spring Boot applications on one Redis; they differ in who decides, who verifies tokens and who holds which secret. Read the hardening checklist with it: this page says what each topology rests on, the checklist what to set before it carries traffic. The settings are in Configuration, the gateway image in Deployment.

TopologyProcessesWho decidesWho verifies tokensRests on
One service that enforcesone applicationthe servicethe servicethe signing secret, and Redis
A gateway, services in gateway modea gateway and its servicesthe gatewaythe gatewaythe network between the gateway and the services
A gateway and services that decide againa gateway and its servicesbothboththe signing secret in every process, and Redis
A service that verifies tokens another service issuesone application beside an issuerthe service's own codethe servicethe issuer's secret, and the issuer's Redis
A login serviceone applicationit issuesthe signing secret
Gateway, control-plane host and IAMa gateway, the cosec-control image and an IAM servicethe gateway, for operators; the control plane, for each changenobody on the host: it believes the identity it is sentthe network that admits its callers, and write access to Redis
Gateway and an IAM that embeds the control planea gateway and one IAM applicationthe gateway, for operators; the control plane, for each changethe IAM service issues; the gateway verifiesthe gateway as the only way in, the IAM's own code, and write access to Redis

What every topology shares ​

  • Redis is the store of record for the documents, revocations and sessions, with maxmemory-policy noeviction, persistence, a replica and a backup (Redis requirements). Everything that reads or writes CoSec's keys uses one cosec.key-prefix per environment.
  • cosec.jwt.secret signs and verifies. HMAC is symmetric: every process that holds the secret can issue a token for any tenant, principal and role, the (platform) administrator of the control plane included. A service that "only verifies" is an issuer to anyone who takes its configuration. Give the secret only to processes you would trust to issue, keep it in a secret store, and treat a leak as a leak of every account. Rotating it invalidates every token signed with the old one: at the moment instances switch, each request is 401 token-invalid on an instance that has the other secret, and every session has to log in again. There is one secret per deployment and no key id, so a rolling restart is a mixed fleet for its duration; plan a rotation in a quiet window, and expect to log everyone out.
  • The starter checks modules at startup and fails naming the artifact that is missing (Modules, STA-1). It also refuses a cosec.* switch written with a value it cannot read (true or false; enforce or gateway for cosec.pipeline.mode; memory or redis for the API key store) rather than reading it as "off" (Feature switches), and logs one INFO line of what CoSec is configured as, or one WARN when cosec.enabled=false (Startup summary).

One service that enforces ​

What the Quick Start builds: one Spring Boot application with the default cosec.pipeline.mode=enforce.

Runsthe application, with cosec-spring-boot, its web adapter (cosec-webflux or cosec-webmvc) and cosec-cocache with Spring's Redis starter and CoCache's; optionally cosec-control, cosec-kafka, cosec-micrometer
Setscosec.jwt.secret, spring.data.redis.*, and, for what it serves, cosec.authorization.scope.app-id and cosec.authorization.remote-ip.max-trusted-index
ReachesRedis (the primary), and Kafka when audit goes there
Rests onthe signing secret; the client address, which depends on the proxies in front of it
CoSec checksthe modules a feature needs; the three token stores; that Redis cannot evict; the client-address setting; readiness on the platform document
CoSec does not checkthat Redis persists or has a replica; that two environments use two prefixes; that the secret is the same across processes

See Quick start, Web integration and Storage.

A gateway with services behind it ​

A Spring Cloud Gateway decides with the documents; each service sets cosec.pipeline.mode=gateway and reads the caller from the CoSec-Identity header the gateway forwards.

Runsthe gateway (the image, or cosec-gateway with cosec-cocache), and each service with cosec-webflux or cosec-webmvc
Setsgateway: cosec.jwt.secret, Redis, the routes; service: cosec.pipeline.mode=gateway and cosec.pipeline.identity.only-gateway-can-reach=true (no Redis, no secret)
Reachesgateway: Redis and the services; service: nothing of CoSec's
Rests onthe network, alone
CoSec checksa WARN at the service's start; startup fails when a gateway host sets gateway mode; per request, a header that is unreadable, from an unknown format version, too old or too large is refused
CoSec does not checkwho can reach the service

The header is unsigned base64url JSON, with no key and no signature. A service in gateway mode believes any CoSec-Identity it receives: anyone who can send it a request can be the platform administrator. What holds the boundary is the network: a Kubernetes NetworkPolicy that admits only the gateway's pods, a private network, or mutual TLS. A namespace with no policy, which is the Kubernetes default, lets any pod in the cluster send the header. k8s/examples/gateway-mode-service-networkpolicy.yaml is a NetworkPolicy to copy for the service: it admits the service's port from the pods labeled app.kubernetes.io/name: cosec-gateway in the gateway's namespace and from nothing else. It needs a network plugin that enforces NetworkPolicy; without one it does nothing, so test that a pod of another label cannot connect. cosec.pipeline.identity.max-age bounds only how old a captured header may be, and a forger sets it to now. Build the boundary before the service is reachable at all (Services behind the gateway, Trust boundaries).

A gateway and services that decide again ​

The gateway authenticates and decides, forwards the credential (cosec.gateway.identity.forward-authorization: true, only to lb:// routes and routes marked cosec-identity: true), and each service runs the full pipeline.

Runsthe gateway as above, and services in enforce mode
Setson each service: the gateway's cosec.jwt.secret, Redis, the same cosec.key-prefix, and its own cosec.authorization.scope.app-id
Reachesgateway and services: Redis
Rests onthe secret shared by every process (see above), and the prefix agreeing
CoSec checksnothing across processes
CoSec does not checkthat the gateway and a service hold the same secret or prefix

A different secret shows as 401 token-invalid at the service; a different prefix as 503, because the service reads no platform document. Documents, action names and the two decisions are in Gateway topologies.

A service that verifies tokens another service issues ​

A resource server beside an issuer: it verifies the issuer's tokens and decides in its own code.

Runsone application in enforce mode, with cosec-cocache, and no login
Setsthe issuer's cosec.jwt.secret and cosec.jwt.algorithm; spring.data.redis.* of the issuer's Redis and the issuer's cosec.key-prefix; a platform document of its own, in memory
Reachesthe issuer's Redis
Rests onthe issuer's secret, and reading the issuer's revocations
CoSec checksthe three token stores at startup; a WARN when the reader is RevocationReader.NONE
CoSec does not checkthat the prefix is the issuer's: a different one reads an empty table, and revoked tokens are accepted without a message

A service that verifies tokens another service issues has the document and the sample.

A login service ​

The application that signs tokens (cosec-login and cosec-jwt come with the starter).

Runsone application with cosec.authentication.login.*, which can serve the refresh and logout routes
Setscosec.jwt.*, cosec-cocache for the stores; behind a gateway, cosec.jwt.enabled=true
ReachesRedis (it writes revocations and sessions)
Rests onthe signing secret, which is the root of trust of every account
CoSec checksthe secret's presence, the token stores, and the refresh and logout routes at startup
CoSec does not checkthat the gateway and the verifiers hold the same secret

See Authentication and What your application serves.

The control plane ​

The only writer of documents: changes are validated, shadowed and approved before they publish. It runs in one of two deployments, and in these two only. Both run the same code; they differ in where the control plane lives and in who calls it.

Gateway, control-plane host and IAM ​

The control plane is a process of its own, the cosec-control image, behind the gateway. The IAM service is a caller of it, like any other service you admit.

Runsthe gateway as above; the cosec-control image; and your IAM service, which issues tokens and, for what it changes itself, calls the host's service port
Setson the host: cosec.pipeline.identity.only-trusted-callers-can-reach=true (the image does not start without it), the Redis account that writes the documents, and a policy per port of the network that admits only its callers; on the gateway: the route /cosec/control/** to the host, with cosec-app-id: cosec-control; the first administrator with cosec-migrate bootstrap
ReachesRedis (writes), and Kafka when the change log goes there; the IAM service reaches the host's service port
Rests onthe network that admits the gateway and the services you name, and write access to Redis. The host holds no signing secret: it verifies no token
CoSec checksthat the statement is written; that it names the right one (the gateway's alone fails beside a service port); that the image has no credential verification, login or API keys on; each control action, decided by the policies for the principal the caller states
CoSec does not checkthat the statement is true; that a service admitted to the service port states only the principal it acts as

The first platform document still comes from cosec-migrate publish; until it is installed the host is not ready. The operators' calls arrive through the gateway, which verified their token and forwards the identity. A service calls the service port with a CoSec-Identity header it writes itself (IdentityHeader.write, cosec-document): the service API has no client class of its own yet.

Gateway and an IAM that embeds the control plane ​

The control plane is a library of the IAM service, which is an application of your own behind the gateway. There is no control-plane host.

Runsthe gateway as above; one IAM application with cosec-control and cosec-cocache, in enforce with cosec.pipeline.caller=forwarded-identity, which calls the control plane from its own code through ControlService
Setscosec.pipeline.identity.only-gateway-can-reach=true; the Redis account that writes the documents; for operators, the gateway route /cosec/control/** to the IAM service, with cosec-app-id: cosec-control; cosec.control.http.enabled=false when nobody calls the control API over HTTP and the code reaches it in process only
ReachesRedis (writes), and Kafka when the change log goes there
Rests onthe gateway as the only way in, the IAM service's own code, and write access to Redis: code in that process holds the store's write account, and what it states as the acting principal is believed
CoSec checksthe statement, and a hidden-method filter; each control action, decided by the policies for the principal the call states, and recorded as that principal's step, with via.method: in-process for a call from code
CoSec does not checkthat the statement is true; the IAM service's own routes: on a host that takes its caller from the identity the web adapter does not decide a request, so they are authorized at the gateway or not at all

A change that needs a second person's approval stops at AWAITING_APPROVAL whoever proposed it: a person approves it on the operators' routes, through the gateway. Every instance of the IAM service runs the control plane's maintenance passes (reclaiming revisions, closing shadow windows, reconciling the app and staged lists), kept apart by their leases as a control host's are: any number of instances may, and one does each at a time.

What the control plane trusts, and what it does not ​

Both deployments believe the CoSec-Identity header they receive, and the header carries no signature (STA-9). So whoever can reach the host, or the IAM service, is whoever they claim to be, a platform administrator included, and can publish any policy of any tenant. The control plane contains mistakes and keeps the audit: every call is decided by the policies for the principal it states, and each step records that the identity was asserted, with the credential's method and id, the request's id and the address of the connection it arrived on (Control-plane change log). It is not a defence against a compromised workload that can reach it, which can also approve its own changes. The network is the boundary. That is why the host does not start until the operator states what can reach it, and why a compromise of the gateway, or of any service admitted to the service port, is a compromise of the control plane. Signing the header is planned for 8.1.

In both, a change to the platform document, the platform tenant's or the control app's that would keep its publisher out of the control plane is a 422 unless the publish says "lockout": true (check V4). A lock-out that was acknowledged, or one the check cannot see, is undone with cosec-migrate restore, run by whoever holds the store's credentials (Recovering from a lock-out).

See The control plane, Storage and Change a document later.

Next: run the gateway image and its manifests, in Deployment.

Licensed under the Apache License, Version 2.0.