Keycloak Integration

How Control Plane authenticates Customer Portal and API users via the platform Keycloak realm.

Control Plane uses Keycloak as the identity provider for the Customer Portal (app.groundfloor.cloud) and Operator Admin (admin.groundfloor.cloud). Every /v1/* request carries a Bearer JWT verified against the platform realm.

This page covers Control Plane auth — signing into Groundfloor's own portals and APIs. Optional per-workspace site auth is a separate feature; see Workspace site auth.

Flow

User → Keycloak login → access_token (JWT)
     → Customer Portal or API client
     → Authorization: Bearer <token>
     → Control Plane verifies iss + signature
     → sub resolved to internal users.id
     → SpiceDB CheckPermission for the requested action

Principal model

After JWT verification, handlers receive a Principal with:

Field	Source	Usage
`subject_id`	JWT `sub`	Stable IdP user ID
`email`	JWT claim	Display, membership lookup
`idp_provider`	Config	`"keycloak"` today
`scopes`	JWT	Optional fine-grained claims

Control Plane maps sub → internal users.id on each request. Authorization always uses the internal user ID when writing SpiceDB relationships.

Environments

Surface	Production	Development
Customer Portal	`app.groundfloor.cloud`	`localhost:3000`
Control Plane API	`dev-platform.groundfloor.cloud`	`localhost:8088`
Keycloak issuer	Platform realm URL	Local or shared dev realm

Tenant provisioning

In production, customers typically do not self-serve account creation. Groundfloor operators provision accounts via POST /v1/admin/accounts with an owner email unless ALLOW_CUSTOMER_ACCOUNT_CREATE=true.

On create, Control Plane:

Creates or attaches the Keycloak realm user
Upserts the Portal users row
Grants owner membership on the new account

One human may belong to multiple accounts (same sub, multiple memberships).

API authentication

See API Authentication for headers, error codes, and curl examples.

ReBAC model — permissions after authentication
Core concepts — two identity planes
Shell authentication — JWT in federated apps