sharang
bb2c638fb4
internal/keycloak/ — Adapter interface with two implementations:
HTTPAdapter pgxpool-style real Admin API client with cached client-
credentials token (auto-refresh, 401 retry).
Mock in-process map for unit tests + dev convenience when
KEYCLOAK_ADMIN_URL is empty. Used by the eachStore harness.
Adapter contract (adapter.go):
CreateOrgAndInvite(ctx, InviteInput) (*InviteResult, error)
Creates a KC organization, an IT_ADMIN user, adds the user as a
member, triggers VERIFY_EMAIL + UPDATE_PASSWORD execute-actions
email. Atomic from the caller's PoV; partial failures surface as
typed errors (ErrOrgConflict, ErrUserConflict, ErrUnauthorized,
ErrUnavailable).
SyncClaims(ctx, userID, Claims) error
Pushes tenant_id / tenant_slug / org_roles / products / plan /
tenant_status into the user's KC attributes — the same shape the
realm's protocol mappers project into JWTs.
Health(ctx) error
Pings /admin/serverinfo; wired into readyz.
Wiring:
POST /v1/tenants now accepts admin_email + admin_name. When set, the
adapter creates the org and invites the user. Response wraps the
tenant with the new TenantCreated{tenant, invite_url} shape so dev
testers can use the action-token URL without waiting for the email.
KC failures DO NOT roll the tenant back — they emit a
keycloak.provision_failed audit event so the operator can resend.
Successful invites emit keycloak.invite_sent.
POST /v1/internal/keycloak/claims resolves a tenant's current claim
bundle. Lookup chain: body.tenant_id → body.tenant_slug →
body.user_attrs.tenant_id → body.user_attrs.tenant_slug. The realm's
protocol mapper calls this at token issuance, or operators on demand.
Config: KEYCLOAK_ADMIN_URL / REALM / CLIENT_ID / CLIENT_SECRET; empty
URL falls back to Mock for dev.
OpenAPI: TenantCreated + Claims schemas added; /v1/internal/keycloak/claims
documented. Contract test extended to cover the new endpoint.
Tests:
internal/keycloak/mock_test.go Mock semantics: conflict surfacing,
FailNext hook, SyncClaims persistence.
internal/server/keycloak_test.go KC provisioning end-to-end via
eachStore: invite_url returned,
mock records, invite_sent audit;
failure path emits provision_failed
but tenant still lands; claims
endpoint resolves via tenant_id /
tenant_slug / user_attrs / 404 / 400.
The real-KC integration test (against a testcontainers-spun KC 26)
lands in a follow-up — gating it behind KEYCLOAK_INTEGRATION=1 + a
slower nightly CI is cleaner than baking 30s+ of KC boot into every PR.
Refs: M4.3
80 lines
3.3 KiB
Go
80 lines
3.3 KiB
Go
// Package keycloak adapts the Keycloak Admin API to the tenant-registry's
|
|
// language of "tenants" and "IT_ADMIN invites".
|
|
//
|
|
// The Adapter interface is the seam: tenant-registry handlers depend on
|
|
// it, never on the concrete HTTP client. Tests use Mock; production uses
|
|
// HTTPAdapter against the real KC at the configured base URL.
|
|
//
|
|
// Required Keycloak features (verified against KC 26):
|
|
// - Organizations feature enabled in the realm (organizationsEnabled: true)
|
|
// - Realm roles: BREAKPILOT_ADMIN, SUPPORT_ENGINEER, SALES_REP
|
|
// - Group `/IT_ADMIN` (used as the org_role marker for invited users)
|
|
//
|
|
// All errors are wrapped with %w so callers can errors.Is them against
|
|
// ErrUnauthorized / ErrOrgConflict / ErrUserConflict.
|
|
package keycloak
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
)
|
|
|
|
// Sentinel errors.
|
|
var (
|
|
ErrUnauthorized = errors.New("keycloak: admin auth failed")
|
|
ErrOrgConflict = errors.New("keycloak: organization already exists")
|
|
ErrUserConflict = errors.New("keycloak: user already exists")
|
|
ErrUnavailable = errors.New("keycloak: unreachable")
|
|
)
|
|
|
|
// InviteInput captures the per-tenant onboarding event from POST /v1/tenants.
|
|
// The adapter creates a Keycloak organization, invites the IT_ADMIN, and
|
|
// stores the (TenantID, OrganizationID) link back in the caller's Tenant.
|
|
type InviteInput struct {
|
|
TenantID string // the tenant_registry id; stored as KC org attribute "tenant_id"
|
|
Slug string // becomes the KC org alias
|
|
Name string // human-readable org name
|
|
AdminEmail string // IT_ADMIN to invite (required)
|
|
AdminName string // optional display name
|
|
}
|
|
|
|
// InviteResult is what the adapter produces. OrganizationID is what the
|
|
// tenant-registry stores so it can later assert tenants.id ↔ kc.org_id 1:1.
|
|
type InviteResult struct {
|
|
OrganizationID string
|
|
UserID string
|
|
// InviteURL is what the user clicks to set their password. In dev (no
|
|
// Stalwart yet) we surface it in the response so testers can use it
|
|
// directly. In prod it's emailed by Keycloak and we discard it.
|
|
InviteURL string
|
|
}
|
|
|
|
// Claims is the tenant-scoped claim bundle the protocol-mapper would push
|
|
// into a JWT at token issuance. Returned by Adapter.ClaimsFor so the user-
|
|
// attributes can be refreshed on subscription change.
|
|
type Claims struct {
|
|
TenantID string `json:"tenant_id"`
|
|
TenantSlug string `json:"tenant_slug"`
|
|
OrgRoles []string `json:"org_roles"`
|
|
Products []string `json:"products"`
|
|
Plan string `json:"plan"`
|
|
TenantStatus string `json:"tenant_status"`
|
|
}
|
|
|
|
// Adapter is the shape tenant-registry handlers code against. HTTPAdapter
|
|
// is the real one; Mock satisfies the same surface for tests.
|
|
type Adapter interface {
|
|
// CreateOrgAndInvite is the M4.3 happy path. Atomic from the caller's
|
|
// PoV: either both org+user land or neither does.
|
|
CreateOrgAndInvite(ctx context.Context, in InviteInput) (*InviteResult, error)
|
|
|
|
// SyncClaims pushes the current Claims into the user's Keycloak
|
|
// attributes. Called whenever entitlements change (M4.2 catalog/trial
|
|
// flows, M14.x cancel, M12.x trial transitions).
|
|
SyncClaims(ctx context.Context, userID string, c Claims) error
|
|
|
|
// Health pings the admin endpoint. Used by readyz and the cluster cold-
|
|
// start sequence (INFRASTRUCTURE.md §10 scenario F).
|
|
Health(ctx context.Context) error
|
|
}
|