generated from coulomb/repo-seed
tegwick
bd272151af
Add research on the journey from gamable opinion signals (reviews, ratings) through observed metrics (PAYDEX, SLA stats), financial commitments (bonds, escrow), and adjudicated outcomes (arbitration, courts). Resolve OpenQuestions: no Reputation entity; use Reputation Signal, Performance Evidence, Commercial Commitment, and Adjudication Outcome with Counterparty Assurance Gradient pattern.
134 lines
6.8 KiB
Markdown
134 lines
6.8 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. |