B2B CIAM · CIAM Reference Architecture
One architecture for orgs, entitlements and access
Separate what a customer bought from what a person may do. Keycloak owns identity and organizations, an entitlement service owns products, plans and seats, and OpenFGA answers resource-level questions — each fact with exactly one owner.
- One source of truth per fact
- Enforced at login and at every API
- B2B orgs and B2C users in one model
Standards & integrations
- Keycloak Organizations
- OpenID Connect
- SAML 2.0
- OpenFGA
- Transactional outbox
- PostgreSQL row-level security
Overview
Four systems, four jobs
Most CIAM trouble starts when one system is asked to do everything — entitlements squeezed into user attributes, product tiers turned into roles, tenant checks left to each API. This architecture gives every fact one owner. CRM and billing hold commercial truth. The entitlement service turns it into subscribers, products, plans, seats and validity. Keycloak holds identities, organizations, memberships and tokens that carry the organization. OpenFGA holds resource relationships. Effective access is the intersection, checked at login and again at every API.
What we deliver
- Reference architecture tailored to your products and tenancy
- Keycloak realm with organizations and a login-time entitlement check
- Entitlement service design: data model, APIs and events
- OpenFGA authorization model with tests
- Onboarding saga and lifecycle event design
- Security and tenant-isolation checklist
Capabilities
What CIAM Reference Architecture covers
Configured, tested and documented on upstream Keycloak — then handed over or operated by us.
Subscriber abstraction
A subscriber is either an organization (B2B) or an individual (B2C), so both models share one entitlement service without special cases in your APIs.
An organization per customer
Each business customer is a Keycloak organization with its own members, domains and identity providers, and the organization travels in every token.
Entitlements outside the IdP
Products, plans, features, seats and validity live in a dedicated service fed by CRM and billing — not in user attributes or roles.
A gate at login
A Keycloak authenticator checks the organization's entitlement for the requested product, cached and failing closed, and a mapper adds a lean entitlement claim.
Authorization at every request
APIs validate the token, enforce the organization down to row-level security, and ask OpenFGA about access to individual resources.
An event-driven lifecycle
CRM and billing events drive an idempotent onboarding saga, and entitlement changes reach OpenFGA and revocation workers through an outbox.
Architecture
Who owns what
Each fact has exactly one owner; everything else is a projection of it.
| Component | Owns | Does not own |
|---|---|---|
| CRM | Accounts, opportunities, contracts, commercial contacts | Identity and access |
| Billing | Subscriptions, invoices, payment status | Who can sign in |
| Onboarding orchestrator | Provisioning workflow state | Business data — it only coordinates |
| Entitlement service | Subscribers, products, plans, seats, validity | Credentials and org roles |
| Keycloak | Users, credentials, organizations, memberships, sessions, tokens | Commercial entitlements |
| OpenFGA | Membership projection, product licenses, resource grants | Seat counts and billing history |
| Org admin portal | Customer self-service: invites, roles, SSO setup | Nothing directly — it calls the owners |
| Product APIs | Business data, partitioned by organization | Identity decisions |
| Migration service | Batches, per-user migration state, reconciliation | Final user records |
How it works
From first call to production
Model products, plans and tenants
We map your catalog, tenancy model and customer types, and agree the source of truth for every fact before any code is written.
Build the core services
The Keycloak realm and organizations, the entitlement service, the login-time extension and the OpenFGA model are built and tested together.
Automate the lifecycle and migrate
CRM events start provisioning organizations automatically, and existing users move in org by org.
Use cases
Where teams put it to work
Multi-product B2B SaaS
Customers buy different products and tiers, and every organization sees exactly what it paid for.
Product-led growth to enterprise
Self-serve individual sign-ups and enterprise organizations with SSO and seat limits run on the same platform.
Getting entitlements out of the IdP
Move plans and seats out of user attributes and roles into a service that can model tiers, seats and history.
FAQ
CIAM Reference Architecture questions, answered
Why not keep entitlements in Keycloak attributes or roles?
Attributes and roles can't model tiers, seat counts, validity dates or commercial history, and they drift away from CRM and billing. A separate entitlement service gives one source of truth that both the login flow and your APIs read.
Do we need OpenFGA from day one?
Only if resource-level sharing is in scope. Organization context, entitlements and coarse roles are enough to start, and OpenFGA can be added later without changing tokens.
Does Keycloak Organizations support org-scoped roles?
Organizations in Keycloak 26.x handle members, domains, identity providers and invitations. Roles scoped to a single organization aren't a built-in concept, so we model org roles in OpenFGA or with per-organization groups.
We're on Auth0 today — does this still apply?
Yes. The entitlement service, onboarding saga, migration service and OpenFGA model don't depend on the identity provider. The same design works with Auth0 Organizations, and it's the blueprint we follow when moving Auth0 customers to Keycloak.
Ready to roll out CIAM Reference Architecture?
Walk us through your requirements on a free strategy call. We'll come back with an architecture, a delivery plan and a fixed scope.