Files

tegwick 3ccf841095 Resolve Customer Account question; add commercial subscription research

Record B2B SaaS subscriber tenancy and Stripe billing source notes. Resolve
the Customer Account open question: reject it as canonical, add Commercial
Record and Commercial Relationship to the Record and relationship layers, and
document Subscriber as a convenience term only.

2026-06-21 20:35:36 +02:00

5.1 KiB

Raw Blame History

Downstream Recommendations

Status: draft. Updated after IDENTITY-WP-0003 corpus backfill. Implementation ideas derived from the canon; no implementation in this repository.

Recommended Consumption Pattern

Downstream repositories should consume identity-canon as a conceptual reference. Map schemas, APIs, CLI commands, UI labels, and authorization policies to canonical terms. Do not depend on this repository as a runtime package unless a later explicit package is extracted.

Schema Design

Separate Natural Person, Account, Profile, Credential, and Principal in user-management schemas. Corpus confirms SCIM/LDAP use "user" for records, Keycloak/ZITADEL for accounts.
Model Tenant as Scope; relate explicitly to Organization, Customer role, Vendor role, Commercial Relationship, and Realm. ZITADEL org-as-tenant and Keycloak realm-as-namespace are common mapping patterns.
Store Stripe Customer / CRM Account as Commercial Record; link to Tenant and Organization via Identifier binding. Do not create a customer_account table that merges billing and login semantics.
Map Auth0/Stytch "subscriber" to Organization + Customer role + Tenant; treat Subscriber as convenience label only.
Store Synonymity Assertions with relation type, strength, scope, evidence, source system, lifecycle state, and privacy classification. Never default to destructive merge for duplicate detection.
Attach IAL/AAL/FAL (or equivalent) to bindings and federation relationships, not as a single account trust field.
Preserve source record IDs (SCIM id, LDAP DN, externalId, OIDC iss+sub) as Identifiers with provenance.

Authorization Adapters

Project canonical Membership, Delegation, and Administration relationships into Zanzibar/OpenFGA tuples rather than encoding social meaning in authz graphs.
Map Cedar Principal/Resource/Action/Context from Account and Relationship; carry delegation in Context, not by overloading Principal identity.
When using Cerbos derived roles, trace ownership/admin derived roles back to canonical Ownership or Administration relationships where possible.
Keep authz user: identifiers aligned with Account IDs or Authenticated Subject bindings via explicit mapping table.

Federation Adapters

Treat OIDC iss+sub and SAML persistent NameID as strong Synonymity Assertion candidates after RP verification policy.
Treat pairwise OIDC sub as Scoped Identifier with privacy-limited assertion.
Subscribe to SSF/CAEP/RISC events to drive Lifecycle State on accounts, credentials, and identifier bindings.
Separate OIDC authentication (Authenticated Subject) from VC claims (Credential + Claim) per OpenID4VC patterns.

Provisioning Adapters

SCIM User → Identity Record; map Group → Group + Membership edges.
LDAP inetOrgPerson → Identity Record; posixAccount → Account facet on same or linked record.
Do not promote SCIM organization string to Organization actor without separate org entity.

ActivityPub Actor → Actor + Profile on origin Scope; Follow → Following Relationship only.
FOAF OnlineAccount → Account with service Scope from accountServiceHomepage.
Schema.org sameAs → weak Synonymity Assertion only; require review before promotion to strong.

Privacy and Entity Resolution

Implement probabilistic matching as weak probably_same_as assertions in proposed lifecycle state with review queue.
Store GDPR pseudonymization re-identification keys in separately secured scope with restricted access.
Support assertion revocation and supersession (SSF identifier-changed, manual unlink) without deleting source records.

UI Copy

Use product-friendly labels externally; maintain internal canonical mappings.
Avoid showing "user" in schema or API names without a mapping note.

Avoid For Now

Do not implement identity provider integrations in this repository.
Do not add database migrations or production APIs here.
Do not treat the glossary as a finalized schema.
Do not use MDM golden-record merge as default linking behavior.
Do not collapse Realm, Tenant, and Organization into one table without relationship modeling.
Do not introduce CustomerAccount as a canonical type; use Commercial Record for billing and Organization + Customer role for subscribing parties.

Suggested Adapter Inventory

Source family	Primary canonical mapping	Common projection
SCIM / LDAP	Identity Record, Group, Membership	Account, Principal
Keycloak / ZITADEL	Account, Organization, Realm/Tenant	Role, OIDC Subject
OIDC / SAML	Authenticated Subject, Identifier	Account link assertion
Zanzibar / OpenFGA	Relationship Tuple	Membership, admin edges
Cedar / Cerbos	Principal, Resource, Action, Context	Role, derived ownership
ActivityPub / FOAF	Actor, Profile, Following	—
DID / VC	Identifier, Credential, Claim	Trust relationship
Entity resolution	Synonymity Assertion	—
Stripe / CRM billing	Commercial Record, Commercial Relationship	Subscription state
Auth0 / Stytch B2B	Organization, Customer role, Tenant, Membership	Account, Subscriber label

5.1 KiB Raw Blame History