/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Identity & Tenancy

Keywords on this page
WordMeaningExample
KeycloakThe sign-in server: it checks passwords and knows peopleLogin page
Internal JWTA signed pass, made by claims-gateway, that every service trustsCookie authentication_token
Public keysWhat anyone uses to check the pass is realRead by Istio
ClaimsWhat the pass says: who the person is, their organizations and rolesAda is staff in Northfield
MembershipOne person in one organization, with one roleAda, staff, Northfield
CedarThe language access rules are written in, run inside each service“staff may edit buildings”
Control planeServices that create organizations, not the product itselfregistry, provisioner
Reconcile loopA loop that looks at what should exist and makes it soEvery 15 s

Realises the Identity & Access domain. Four Go services plus Keycloak. Code-level pages: Claims Gateway, Tenancy, Registry, Provisioner.


Who does what

PartJobKeeps
KeycloakChecks the passwordPeople
claims-gatewayTurns a Keycloak sign-in into the internal passNothing
tenancyOrganizations, memberships, invites, access rulesPostgreSQL
registryTakes a new customer’s signupPostgreSQL
provisionerTurns a signup into a working organizationNothing

Each part does one job. Signing in and signing up change for different reasons, so they live in different services.

flowchart LR
    B["client"] --> K["Keycloak"]
    B --> G["claims-gateway"]
    G --> K
    G --> T["tenancy"]
    B -.-> R["registry"]
    P["provisioner"] --> R
    P --> T

Solid: sign-in. Dotted: signup. registry and provisioner have no route at the edge: they are reached only from inside the network.


Inside each service

All four have the same shape: a core with the rules, and adapters around it.

flowchart LR
    IN["HTTP handlers, or a timer"] --> CORE["Core: the rules"]
    CORE --> PORT["Ports: what the core needs"]
    PORT -.-> AD["Adapters: database, Keycloak, other services"]
    PORT -.-> FAKE["Fakes, in tests"]

Signing in

sequenceDiagram
    participant C as client
    participant K as Keycloak
    participant G as claims-gateway
    participant T as tenancy
    C->>K: sign in
    K-->>C: Keycloak token
    C->>G: exchange it
    G->>K: is this token real?
    G->>T: memberships of this person
    alt none, and the Keycloak token names an organization
        G->>T: provision a membership in that organization
        Note over T: invite-only? refused, the pass has no membership
    end
    G-->>C: cookie with the internal pass

Every later request

The edge checks the pass once. Services behind it trust the result.

LocalCluster
Who checksCaddy asks claims-gateway on every requestIstio checks it alone, with the public keys
Extra hop per requestYesNo
What services receiveThe claims headerThe same claims header

How long a session lasts

FactValue
Pass lifetime15 min
client renews itEvery 10 min, with no user action
Renewing needsA pass that is still valid
A renewal that cannot reach the gatewayRetried after 30 s, so a short restart costs nothing
Any other request refused with 401Ends the session at once: home, and a banner offering sign-in again

Example. Ada signs in at 09:00. The pass is renewed at 09:10, 09:20, and so on, all day. Her laptop sleeps from 10:05 to 10:30, and the pass dies at 10:20. On wake-up the renewal answers 401: the app drops the session, goes home, and the banner asks her to sign in again.

Keep 10 below 15

The two numbers live in different services, and nothing checks one against the other. A pass shorter than the renew interval ends every session.


Access rules

Roles are flattened before Cedar runs. Cedar can test “is this in the list”, but not “is this role higher than that one”. So tenancy first turns each membership into lists:

Ada’s membershipLists she ends up in
Staff in NorthfieldVisitor or higher: Northfield. Staff or higher: Northfield

A rule then only asks “is this organization in the staff-or-higher list”.

“in” does not mean “in the list”

In Cedar, in means “is a child of”, for entities. On a plain list it denies everything, with no error. Lists need “contains”. Only the shared tests that run real rules catch this.

Two checks stay outside Cedar, because they are not about roles:


Signing up

sequenceDiagram
    participant C as New customer
    participant R as registry
    participant P as provisioner
    participant T as tenancy
    C->>R: sign up, from inside the network
    R-->>C: provisioning
    loop every 15 s
        P->>R: anything pending?
    end
    P->>T: create the organization
    P->>R: ready, or failed with the reason

Choices

ChoiceWhy
Keycloak for every customerOne sign-in path, whatever the customer’s size
One pass shape, frozen in a shared packageEvery service reads it the same way
Rules run inside each serviceNo network call per decision
Organization in registry, tenant in tenancyBilling and access change for different reasons, and are not always one to one
Signup by loop, not by callCreating an organization is slow, and nobody should wait for it

Gaps