identity-canon/model/ConceptualModel.md

Conceptual Model

Status: draft. Refined after IDENTITY-WP-0003 corpus backfill and scenario representation review. Implementation-neutral.

Core Claim

Identity-canon models identity-related systems as scoped actors, records, identifiers, claims, credentials, relationships, and projections. Social, legal, operational, authentication, and authorization meanings stay visible instead of collapsing into user, group, or tenant.

Entity Families

Actor Layer

• Actor: participation root.
• Natural Person: human actor.
• Artificial Agent: non-human automated actor.
• Collective Actor: actor composed of, representing, or organizing multiple actors.
• Organization, Community, Family or Household, Group, and Team: candidate collective actor specializations.

Record Layer

• Account: operational access record in a scope.
• Service Account: software-oriented account.
• Identity Record: source-specific record about an actor or account.
• Commercial Record: billing, CRM, or commerce-system record linked to an actor or tenant (e.g., Stripe Customer).
• Profile: presentation or attribute surface.
• Persona: contextual presentation of an actor.

Reference Layer

• Identifier: value or reference within a scope.
• Scoped Identifier: identifier designed for limited correlation.
• Credential: proof or control material.
• Claim: statement made by a source or issuer.
• Evidence Source: support for claims, relationships, and synonymity.

Scope Layer

• Scope: boundary for meaning.
• Tenant: administrative or isolation scope.
• Realm: issuer or security namespace.
• Namespace: naming scope.
• Authorization Domain: scope in which principals, resources, actions, and policies are evaluated.

Projection Layer

• Authenticated Subject: protocol projection of an identified entity.
• Authorization Principal: decision-engine projection of an actor, account, or subject.
• Authorization Resource, Action, Policy, and Relationship Tuple: downstream authorization projections, not canonical identity roots.

Relationship Classes

Relationships are explicit model elements when they affect meaning, authorization, privacy, or lifecycle.

Core relationship classes:

• Membership: actor participates in a collective actor or scope.
• Affiliation: actor is associated with another actor or collective.
• Following: actor subscribes to or follows another actor or profile.
• Ownership: actor controls or is responsible for a record, resource, tenant, or organization.
• Representation: actor acts on behalf of another actor.
• Delegation: actor grants bounded authority to another actor.
• Administration: actor manages records, relationships, or configuration in a scope.
• Trust: actor, issuer, verifier, or system relies on another for a purpose.
• Commercial: vendor actor provides services to customer actor; may reference a Commercial Record for billing or subscription state.
• Synonymity: records or identifiers are asserted to refer to the same target under stated evidence and scope.

Recommended relationship fields:

• relationship type;
• source and target;
• scope;
• source system or issuer;
• evidence reference;
• confidence or assurance when relevant;
• lifecycle state;
• privacy constraints;
• authorization implication, if any.

Identity Linking Model

Identity linking does not merge records by default. It creates Synonymity Assertions with relation types (same_as, probably_same_as, linked_to, represents), strength bands, scope, evidence, and lifecycle state.

Weak synonymity: probabilistic entity-resolution matches, schema.org sameAs, shared attributes without verification.

Strong synonymity: deterministic keys (OIDC iss+sub, persistent SAML NameID), operator-verified links, VC cryptographic proof.

Privacy-limited synonymity: pairwise OIDC sub, pseudonymous persona links, GDPR pseudonymization with separated re-identification key.

Scenario Representation Paths

Each scenario in scenarios/ScenarioTests.md maps to canonical elements as follows.

S01 — Single Person With One Local Account

Natural Person → operates → Account (in Scope) → has Identifier(s) → presents Profile → optional Membership Relationship to Group → authz projects Account to Authorization Principal.

S02 — Person With Multiple Accounts Across Scopes

Natural Person → operates → multiple Account (one primary Scope each) → optional Synonymity Assertion (linked_to or same_as, scoped) between accounts → independent Lifecycle State per account.

S03 — Enterprise With Sub-Organizations

Organization actors → structural child/parent relationships → Identity Record/Account per directory source (LDAP/SCIM) → Membership Relationship to org units → Legal Entity as specialization or relationship when evidenced.

S04 — Vendor Tenant Serving Customer Tenants

Organization(vendor) + Organization(customer) → Commercial Relationship (vendor/customer roles) → separate Tenant scopes → optional Commercial Record per customer tenant (billing) → Trust Relationship for federation → Administration Relationship for delegated support.

S05 — Customer Organization With Delegated Administrators

Organization → owns Tenant scope → administrator Account(s) → Delegation Relationship + Administration Relationship → authz projection via Cedar Principal or OpenFGA admin tuple.

S06 — Family With Guardian And Dependent Accounts

Family or Household collective actor → Natural Person (guardian, dependent) → Representation Relationship (guardian→dependent) → child Account with privacy constraints → optional NIST IAL-capped proofing metadata.

S07 — Spontaneous Interest Group

Community or Group collective actor → Membership Relationship (informal) → optional Administration Relationship (moderator) → no Tenant or Legal Entity required.

S08 — Community With Members, Moderators, And Followers

Community actor → Membership Relationship (members) → Administration Relationship (moderators) → Following Relationship (followers) → Profile may differ from Account.

S09 — Social Media Follower Graph

Actor/Persona → Profile in social Scope → directed Following Relationship edges → no implied Membership or authz tuple.

S10 — Bot Or Service Account Acting For An Organization

Artificial Agent → Service Account → Organization actor → Representation or Delegation Relationship → Credential → authz tuple (e.g., org#delegate@service_account).

S11 — AI Agent Acting Under Delegated Authority

Artificial Agent → Account or Service Account → Delegation Relationship from Natural Person or Organization → Evidence Source for actions → Cedar Context.delegatedBy or contextual OpenFGA tuple.

S12 — Weak Identity Match From Imported Data

Source Identity Record(s) → Synonymity Assertion (probably_same_as, weak, scoped) → Evidence Source (import job, match score) → Lifecycle State proposed until reviewed.

S13 — Strong Account Link After Explicit Verification

Account(s) or Identifier(s) → Synonymity Assertion (same_as, strong) → Evidence Source (verification event, VC proof, re-authentication) → revocation/supersession path via Lifecycle State.

S14 — Pseudonymous Profile Linked Only Within Restricted Scope

Persona/Profile → Scoped Identifier → Synonymity Assertion (privacy-limited, restricted Scope) → separated re-identification Evidence Source per GDPR pseudonymization pattern.

S15 — Organization Represented By Legal Entity And Operational Tenants

Organization actor → Legal Entity relationship or specialization → one or more Tenant scopes → Representation Relationship for authorized persons or agents.

Scenario Gaps

No scenario requires glossary or principle changes that the current model cannot satisfy. Remaining ambiguities are documented in OpenQuestions.md:

• mandatory Synonymity Assertion field set;
• Realm vs. Tenant promotion for Keycloak-heavy mappings;
• Customer Account resolved: use Commercial Record + Commercial Relationship; see OpenQuestions.md.

Invariants

• A Natural Person can control zero, one, or many Accounts.
• An Account belongs to exactly one primary operational Scope, but can have relationships to other scopes.
• A Profile presents an Actor, Account, or Persona within a Scope.
• A Principal is a projection for authorization and must not replace Actor or Account in the canon.
• A Tenant can be related to an Organization or Customer, but is not identical to either.
• A Group carries Membership relationships; Role assignment and relationship semantics stay explicit.
• A Synonymity Assertion links records without destroying source identity or evidence.
• Lifecycle state applies to relationships and assertions, not only accounts.
• Authorization tuples (Zanzibar/OpenFGA) and Cedar principals are projections from canonical actors, accounts, and relationships — not alternate identity roots.
• OIDC Subject and SAML Principal are Authenticated Subject projections, not Natural Persons.

External Mapping Rule

When mapping an external system, identify the canonical layer first:

1. Actor layer: who or what participates?
2. Record layer: what operational record exists?
3. Reference layer: what values, claims, or credentials refer or prove?
4. Scope layer: where is the meaning valid?
5. Relationship layer: what typed connection is asserted?
6. Projection layer: what downstream protocol or authorization view is needed?

Only after that mapping should source-specific labels such as user, group, organization, realm, tenant, subject, or principal be adopted in a downstream artifact.

Source Grounding

This revision is grounded in the backfilled research corpus (23 source notes). Key cross-cutting findings:

• Provisioning sources (SCIM, LDAP) model records and group membership, not actors directly.
• Federation sources (OIDC, SAML, NIST, SSF) define subject identifiers, assurance, and lifecycle events.
• Authorization sources (Zanzibar, OpenFGA, Cedar, Cerbos) are projection layers over opaque identifiers.
• Social sources (ActivityPub, FOAF, Schema.org, WebID) separate person, actor, account, and social edges.
• VC/DID sources add portable claims and decentralized identifiers.
• Entity-resolution and GDPR sources define synonymity strength and privacy constraints.