generated from coulomb/repo-seed
tegwick
6ea582cd9e
Add research on PCI/tokenized payment references vs login Credentials (Payment Instrument Reference, Payment Mandate) and CRM Opportunity promotion thresholds (Pipeline Pursuit, binding_trigger). Resolve OpenQuestions for both topics. Update glossary, conceptual model, terminology, and downstream recommendations.
138 lines
7.2 KiB
Markdown
138 lines
7.2 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 |
|
|
| 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. |