generated from coulomb/repo-seed
tegwick
3ccf841095
Record B2B SaaS subscriber tenancy and Stripe billing source notes. Resolve the Customer Account open question: reject it as canonical, add Commercial Record and Commercial Relationship to the Record and relationship layers, and document Subscriber as a convenience term only.
265 lines
10 KiB
Markdown
265 lines
10 KiB
Markdown
# 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. |