generated from coulomb/repo-seed
tegwick
3ccf841095
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.
110 lines
5.1 KiB
Markdown
110 lines
5.1 KiB
Markdown
# 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.
|
|
|
|
## Social and Profile Adapters
|
|
|
|
- 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 | |