generated from coulomb/repo-seed
tegwick
1c1b5c9bc6
Backfill all 23 research source notes with terminology extracts, modeling assumptions, conflicts, canonical mappings, and references. Refresh terminology artifacts, refine the conceptual model with explicit scenario paths, reconcile canon surfaces and open questions, and mark the workplan finished.
4.5 KiB
4.5 KiB
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, Vendor, and Realm. ZITADEL org-as-tenant and Keycloak realm-as-namespace are common mapping patterns.
- 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
organizationstring 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_asassertions inproposedlifecycle 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.
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 | — |