commerce-canon/research/identity-provisioning/ory-kratos-keto.md

# Ory Kratos and Keto

## Source Type

Product documentation and open-source implementation reference for Ory Kratos
(identity management) and Ory Keto (relationship-based authorization).

## Domain

Cloud-native identity management, self-service flows, and ReBAC authorization
separation.

## Why This Source Matters

Ory Kratos identity/user management and Ory Keto relationship-based
authorization separation.

Ory explicitly separates identity management (Kratos) from authorization
(Keto). This architectural split is a strong reference for identity-canon's
P6 principle (authorization projections separate from identity model).

## Key Concepts

- **Identity (Kratos)**: core identity record with traits (schema-defined
  attributes), credentials, verifiable addresses, and recovery settings.
- **Traits**: JSON attributes on an identity (email, name, etc.) governed by
  identity schema.
- **Credential**: password, OIDC link, TOTP, WebAuthn, or lookup secret
  attached to an identity.
- **Identity schema**: JSON Schema defining allowed traits and validation.
- **Session**: authenticated session bound to an identity after credential
  verification.
- **Recovery / Verification flow**: self-service processes for account
  recovery and address verification.
- **Relation tuple (Keto)**: `namespace:object#relation@subject` assertion
  for ReBAC checks.
- **Namespace (Keto)**: typed object class in the authorization model with
  defined relations and permissions.
- **Subject (Keto)**: entity in a relation tuple; may reference a Kratos
  identity or arbitrary identifier.
- **Permission check**: evaluate whether a subject has a relation to an
  object in a namespace.

## Relevant Terminology

| Term | Source meaning |
| --- | --- |
| Identity | Kratos record with traits and credentials; not authorization entity. |
| Traits | Schema-validated attributes on an identity. |
| Credential | Authentication factor bound to identity. |
| Session | Active authenticated state for an identity. |
| Schema | JSON Schema defining identity trait structure per use case. |
| Relation tuple | Subject-relation-object fact in Keto. |
| Namespace | Authorization object type with relation definitions. |
| Subject | Authorization participant in a tuple. |
| Object | Resource or entity being authorized in a tuple. |
| Relation | Named edge type between subject and object. |

## Modeling Assumptions

- **Identity and authorization are separate services** with distinct storage
  and APIs.
- **Identity means traits + credentials**, not permissions.
- **Traits are schema-driven**, allowing multiple identity schemas per
  deployment (consumer vs. admin personas).
- **Sessions are ephemeral** authentication state, not identity records.
- **Authorization uses Zanzibar-style tuples** in Keto, not Kratos groups or
  roles.
- **Subjects in Keto may not map 1:1** to Kratos identities; integration is
  application-level.
- **No first-class organization or tenant** in Kratos core; multi-tenancy is
  application concern.

## Identity-Canon Implications

- Kratos **Identity** maps to **Identity Record** with **Profile** (traits)
  and **Credential** attachments.
- Kratos does not use "account" explicitly; Identity is closer to Account +
  Profile combined.
- **Session** is ephemeral auth state, not a canonical entity; maps to
  downstream session projection.
- **Identity schema** maps to schema governance for Profile/Identity Record
  attributes in a Scope.
- Keto **relation tuple** maps to **Relationship Tuple** (authorization
  projection) or typed **Relationship** with authz implication.
- Keto **namespace** maps to **Authorization Domain** Scope.
- Keto **subject** maps to **Authorization Principal** projection.
- Strong evidence for **P6**: identity store and authorization graph are
  orthogonal.
- Supports S01 (single local identity), S10 (service identity via traits +
  credentials), S11 (agent via separate Keto tuples).

## Terminology Conflicts

- **Identity**: Kratos Identity is a record with credentials; conflicts with
  bare "identity" meaning personhood or issuer subject.
- **Subject**: Keto subject is authorization participant; OIDC subject is
  issuer identifier; different layers.
- **Traits vs. Profile**: traits are stored attributes; profile is
  presentation — often conflated in Kratos.
- **Namespace**: Keto namespace is authorization object type; DNS/LDAP
  namespace is naming scope.
- **No user term**: Kratos avoids "user" in API, but docs sometimes use it
  informally.

## Candidate Canonical Mappings

| Ory concept | Candidate canonical concept |
| --- | --- |
| Kratos Identity | Identity Record + Account facet |
| Traits | Profile attributes |
| Credential | Credential |
| Session | Ephemeral auth projection (non-canonical) |
| Identity schema | Profile/record schema in Scope |
| Keto relation tuple | Relationship Tuple (authorization projection) |
| Keto namespace | Authorization Domain Scope |
| Keto subject | Authorization Principal |
| Keto object | Authorization Resource |
| Keto relation | Relationship type (authz) |
| Verification flow | Evidence Source event |

## Open Questions

- Should Kratos Identity be split into Account + Profile in canon, or kept
  as unified Identity Record?
- How should Keto subjects that reference non-Kratos identifiers (e.g.,
  `group:engineering#member`) map to canonical Group + Membership?
- Does Kratos multi-schema support (consumer vs. admin) map to Persona or
  separate Identity Records?
- Should session be documented as a projection type in canon or remain
  explicitly out of scope?

## References

- Ory Kratos documentation — https://www.ory.sh/docs/kratos/
- Ory Keto documentation — https://www.ory.sh/docs/keto/
- Ory Kratos identity model — https://www.ory.sh/docs/kratos/manage-user-identities/identity-schema
- Ory Keto relation tuples — https://www.ory.sh/docs/keto/concepts/relation-tuples