identity-canon/DownstreamRecommendations.md

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
KYC / AML / LEI / DUNS	Commercial Record, Beneficial Ownership Relationship, Registry Identifier, Proxy Commercial Identifier	Assurance, Evidence
Salesforce / CRM	Commercial Record, Contact as Natural Person	Account hierarchy

Commercial Binding

• Model fluid identity (trials, leads, pseudonyms) without Commercial Commitment until counterparty reliance exists.
• On subscription, contract, or KYC acceptance, create Commercial Commitment with Evidence Source and lifecycle state.
• Model LEI, UEI, and company registration numbers as Registry Identifier with authority_class and renewal lifecycle (LEI annual).
• Model DUNS as Proxy Commercial Identifier (ICD 0060); do not treat as incorporating-register authority.
• Model KYC beneficial owners as Beneficial Ownership Relationship with ownership_prong / control_prong metadata — not Ownership subtype or authz owner.
• Link registry identifiers for the same entity via Synonymity Assertion when multiple registries describe one Organization/Legal Entity.
• Separate CRM Account and Stripe Customer as Commercial Records; never merge with login Account.
• Use qualified credentials (eIDAS seal, VC) as Evidence for Commercial Commitment where applicable.
• Map reviews and star ratings to Reputation Signal (opinion tier); never merge with credit scores or legal outcomes.
• Map PAYDEX, SLA metrics, and credit bureau data to Performance Evidence (observed tier).
• Map bonds, escrow, and signed SLAs to Commercial Commitment (committed tier).
• Map arbitration awards and court judgments to Adjudication Outcome (adjudicated tier).
• Trust Relationship projections must cite assurance_basis tier; weight opinion weak by default.
• Never store PAN/CVV in identity-layer stores; use Payment Instrument Reference only.
• Map SetupIntent/mandate success to Payment Mandate Commercial Commitment.
• Map CRM Opportunity to Pipeline Pursuit; promote to Commercial Commitment only on binding_trigger.
• Do not treat Salesforce Forecast "Commit" as Commercial Commitment active state.
• Use settled enums from commercial-identity-nuance-settlement.md: control_basis, binding_trigger, commitment_type, cross-registry Synonymity strengths.
• Person Account adapters: split Natural Person + Commercial Record; export combined projection only with projection_mode: person_account_combined.
• FinCEN ID → Registry Identifier on Natural Person; BO exemptions → explicit Evidence.
• LEI↔DUNS Synonymity default medium; LEI↔company reg default strong.
• Reputation portability: linked_to Synonymity weak between Reputation Signals.
• Oracle/escrow release → Performance Evidence; ADR/court → Adjudication Outcome.