key-cape/wiki/KeyCapeSpecification_v0.1.md

KeyCape

Prepare for KeyCloak without KeyCloak

Keycape Specification v0.1

Status: Draft Project: NetKingdom Component: Keycape Purpose: Lightweight IAM profile implementation for small and early production environments, with explicit replaceability by Keycloak in larger or federated environments.

---

1. Purpose

Keycape is a profile-constrained IAM implementation for NetKingdom.

It provides the externally visible IAM contract used by NetKingdom applications in lightweight environments, while being intentionally replaceable by Keycloak in larger environments.

Keycape is not a full IAM platform and not a full Keycloak clone.

Its role is to:

• implement the NetKingdom IAM Profile
• provide a slim production-capable setup for small environments
• enforce interface discipline from the beginning
• expose telemetry on demanded functionality
• support automated replacement tests to prove migration to Keycloak

---

2. Design Intent

The architecture shall support two valid production modes:

2.1 Lightweight mode

Uses lightweight components for lean production and development.

Typical implementation:

• Keycape as the externally visible profile implementation
• Authelia as lightweight OIDC-capable backend where useful
• LLDAP as lightweight directory backend where useful
• privacyIDEA as MFA authority

2.2 Expanded mode

Uses more feature-rich components for scale, federation, and enterprise IAM breadth.

Typical implementation:

• Keycloak as the externally visible IAM implementation
• full LDAP directory as identity backend where needed
• privacyIDEA as MFA authority

The critical idea is:

Applications integrate against the NetKingdom IAM Profile, not against incidental behavior of Keycape, Authelia, LLDAP, or Keycloak.

---

3. Core Architectural Principle

Keycape shall be a contract implementation, not a platform clone.

That means:

• Keycape replicates only the relevant external interfaces
• Keycape may fulfill functionality by orchestrating underlying components
• unsupported functions must fail clearly and predictably
• profile violations must be observable through telemetry
• Keycape must remain small enough to be maintainable

---

4. Scope

4.1 In scope

Keycape is responsible for:

• implementing the NetKingdom IAM Profile
• exposing the external IAM endpoints required by profile-conformant clients
• normalizing identity and claims behavior across lightweight mode
• providing structured errors for unsupported functionality
• generating telemetry on requested functionality and profile drift
• supporting migration and replacement testing to Keycloak
• participating in automated data migration workflows

4.2 Out of scope

Keycape shall not attempt to provide broad parity with Keycloak in areas such as:

• identity brokering to arbitrary upstream IdPs
• general SAML platform parity
• Keycloak SPI/plugin parity
• Keycloak admin console parity
• Keycloak authorization services parity
• generic realm import/export parity
• broad compatibility with arbitrary Keycloak-specific admin APIs
• full LDAP server behavior
• enterprise IAM feature breadth beyond the defined profile

---

5. Terminology

5.1 NetKingdom IAM Profile

The explicit, versioned contract supported by both Keycape and Keycloak-mode deployments.

5.2 Profile implementation

A concrete runtime that implements the profile, such as Keycape or Keycloak.

5.3 Lightweight mode

Deployment mode using slim components and limited scope.

5.4 Expanded mode

Deployment mode using Keycloak and fuller directory/federation infrastructure.

5.5 Canonical identity model

A product-neutral representation of users, groups, roles, clients, and related metadata used for validation, provisioning, migration, and tests.

5.6 Canonical LDAP schema

A restricted LDAP-oriented schema profile derived from the canonical identity model and validated before provisioning or migration.

---

6. Functional Positioning of Components

6.1 Keycape

External contract implementation in lightweight mode.

Responsibilities:

• profile endpoints
• protocol normalization
• claim normalization
• config translation to underlying components
• unsupported-feature handling
• telemetry

6.2 Authelia

Optional lightweight backend for OIDC/session/auth flows.

Responsibilities may include:

• login/session handling
• token issuance
• client handling within supported subset

Authelia remains an internal implementation detail from the application point of view.

6.3 LLDAP

Optional lightweight LDAP-compatible identity backend.

Responsibilities may include:

• user storage
• group membership storage
• dev/bootstrap directory service
• lean production directory for small environments

LLDAP is not part of the application-facing contract.

6.4 privacyIDEA

Stable MFA and token-policy authority across both modes.

Responsibilities:

• MFA enforcement and policy
• token management where applicable
• stable security concept across migration paths

6.5 Keycloak

Replacement implementation for expanded mode.

Responsibilities:

• implement the same profile for applications
• provide wider IAM capability when needed
• optionally federate with larger directories

---

7. Keycape Objectives

Keycape shall satisfy the following objectives:

7.1 Contract stability

Applications should see a stable IAM surface.

7.2 Minimalism

Only the defined profile shall be implemented.

7.3 Replaceability

Replacement by Keycloak shall be continuously testable.

7.4 Observability

Demand for unsupported or non-profile functionality shall be measurable.

7.5 Migration readiness

Data and configuration required for replacement shall be exportable, transformable, and validated.

7.6 Production validity

The lightweight stack shall be considered valid production infrastructure where the required feature set stays within the profile.

---

8. NetKingdom IAM Profile

This section defines the initial minimum profile supported by the KeyCape v0.1 specification. The canonical NetKingdom profile has since moved to net-kingdom/canon/standards/iam-profile_v0.2.md; KeyCape conformance should be measured against that profile and the executable suite in net-kingdom/tools/iam-profile-conformance/.

8.1 Supported authentication model

The initial profile shall support:

• OpenID Connect Authorization Code Flow
• PKCE
• confidential clients
• public clients only if explicitly allowed in a later profile revision
• fixed redirect URIs
• a small, stable claim set
• stable issuer behavior
• JWKS exposure
• discovery metadata

8.2 Supported endpoints

The initial profile shall define support for:

• discovery endpoint
• authorization endpoint
• token endpoint
• JWKS endpoint
• userinfo endpoint if required by supported clients
• logout endpoint only if its semantics are clearly defined in the profile

Optional endpoints such as introspection and revocation shall only be supported if there is a concrete application need.

8.3 Supported scopes

Initial mandatory scopes:

• openid

Optional initial scopes, if required:

• profile
• email
• groups

Custom scopes shall be explicitly versioned as part of the profile.

8.4 Supported claims

Initial standard claims may include:

• sub
• iss
• aud
• exp
• iat
• preferred_username
• email if present
• name if present

NetKingdom profile v0.2 requires these normalized claims before applications or flex-auth consume a token:

• tenant
• principal_type
• groups
• roles
• scope or scp
• assurance

Claim names, types, and semantics must be fixed by the profile and validated in tests.

8.5 Supported client model

Clients shall be defined in a constrained way:

• immutable client identifier
• known redirect URIs
• known scopes
• known grant types within the profile
• predictable claim mapping behavior
• minimal client-secret handling rules
• no dynamic client registration in v0.1

8.6 MFA interaction

MFA behavior shall be treated as part of the authentication policy, not as ad hoc application logic.

The profile shall define:

• when MFA is required
• whether MFA state influences token claims
• whether step-up behavior is supported
• which user/account states are considered valid for issuance

The exact MFA mechanics may be delegated to privacyIDEA.

---

9. Unsupported Functionality Policy

Any request beyond the profile shall be handled explicitly.

9.1 Required behavior

Keycape shall never silently emulate unsupported features in an undefined way.

9.2 Error taxonomy

The following error classes shall exist:

feature_not_supported_by_profile

The requested capability is outside the NetKingdom IAM Profile.

available_in_keycloak_mode_only

The capability may exist in expanded mode but is intentionally absent in lightweight mode.

rejected_for_profile_safety

The request is rejected because supporting it would weaken the profile’s guarantees or security discipline.

invalid_profile_usage

The client uses a supported endpoint or feature incorrectly.

9.3 Error response requirements

Errors shall be:

• machine-readable
• human-readable
• loggable
• distinguishable by category
• stable enough for automated tests

---

10. Canonical Identity Model

Keycape development shall use a canonical identity model independent of product-specific storage schemas.

10.1 Purpose

The canonical identity model is the source of truth for:

• test fixtures
• provisioning
• migration
• validation
• replacement testing

10.2 Core entities

At minimum:

• User
• Group
• Membership
• Client
• Role
• ClientScopeAssignment
• MFAEnrollmentReference
• DirectoryAttributes
• ProfileVersion

10.3 Canonical user fields

Minimum user fields:

• stable internal identifier
• username
• display name
• email
• enabled/disabled state
• group memberships
• optional role memberships
• optional MFA linkage reference
• LDAP-oriented attributes required by the canonical LDAP schema

10.4 Canonical client fields

Minimum client fields:

• client ID
• display label
• allowed redirect URIs
• allowed scopes
• client type
• secret reference if applicable
• token/claim profile
• environment applicability

---

11. Canonical LDAP Schema

The canonical LDAP schema is the restricted LDAP expression of the canonical identity model.

It exists to ensure portability between:

• LLDAP
• larger LDAP implementations
• Keycloak federation targets where relevant

11.1 Goals

• keep LDAP usage intentionally small and portable
• prevent schema drift
• validate data before provisioning/migration
• ensure only approved attributes and structures are used

11.2 Validator requirement

A canonical LDAP schema validator is mandatory.

It shall validate:

• object class usage
• required and optional attributes
• DN placement rules
• naming rules
• group membership representation
• forbidden attributes or structures
• cross-entry consistency
• profile version compatibility

11.3 Validator modes

The validator should support:

• fixture validation
• pre-provision validation
• pre-migration validation
• post-migration verification
• drift detection in CI

---

12. Keycape Runtime Responsibilities

In lightweight mode Keycape shall be responsible for:

12.1 Profile endpoint exposure

Expose the agreed external endpoints.

12.2 Backend translation

Translate profile concepts into underlying Authelia/LLDAP/privacyIDEA configuration and behavior.

12.3 Claim normalization

Ensure tokens and userinfo behave according to profile definitions, regardless of backend quirks.

12.4 Unsupported-feature enforcement

Block non-profile usage with structured errors.

12.5 Telemetry

Emit data on requested behavior and unsupported demand.

12.6 Configuration export support

Produce the information needed for migration to expanded mode.

---

13. Telemetry Specification

Telemetry is a first-class feature of Keycape.

13.1 Purpose

Telemetry shall answer questions such as:

• which profile features are actually used
• which unsupported features are demanded
• which applications are creating pressure for expanded-mode features
• whether the current profile remains sufficient

13.2 Minimum telemetry events

Keycape shall emit events for:

• successful authentication flow start
• successful token issuance
• unsuccessful authentication attempt
• unsupported endpoint usage
• unsupported grant/scopes/claims usage
• invalid redirect or client usage
• logout attempts
• admin/config-related unsupported requests
• migration/export operations

13.3 Minimum telemetry fields

Each event should capture:

• timestamp
• environment
• deployment mode
• client ID
• endpoint
• feature category
• result status
• error class if applicable
• requested scopes
• requested grant type
• correlation ID / trace ID

13.4 Telemetry outputs

Telemetry should be usable for:

• logs
• metrics
• dashboards
• CI analysis
• migration planning

---

14. Migration Model

Replacement by Keycloak shall be an explicit, tested capability.

14.1 Migration dimensions

Migration has at least two independent dimensions:

A. IAM implementation migration

Keycape/lightweight implementation → Keycloak

B. Directory migration

LLDAP → full LDAP implementation

14.2 Migration principles

• migration shall be reproducible
• migration shall be test-driven
• migration shall use canonical data as the source of truth
• migration success shall be determined by application-facing contract tests
• migration shall include data validation before and after transfer

14.3 Supported migration paths

Initial required paths:

Path 1

LLDAP + Keycape stack → Keycloak with same directory data semantics

Path 2

LLDAP → full LDAP, then Keycloak federating with full LDAP

Path 3

Lightweight stack → expanded stack with privacyIDEA remaining stable

14.4 Migration outputs

Migration tooling should generate:

• transformed directory data
• client definitions
• profile conformance reports
• validation results
• contract test results
• incompatibility reports

---

15. Replacement Test Strategy

Automated replacement testing is mandatory.

15.1 Goal

Prove that applications relying only on the profile behave acceptably after replacement.

15.2 Required test scenarios

Scenario A: Lightweight baseline

Provision canonical fixtures into lightweight mode and run all profile integration tests.

Scenario B: IAM replacement

Replace Keycape-based implementation with Keycloak and rerun the same app-facing tests.

Scenario C: Full expansion

Migrate LLDAP data into full LDAP, connect Keycloak, and rerun tests.

Scenario D: Negative profile tests

Attempt to use unsupported functionality and verify correct error behavior and telemetry.

15.3 Test categories

Required categories:

• discovery tests
• login flow tests
• token claim tests
• redirect validation tests
• client configuration tests
• logout tests if supported
• MFA policy tests
• migration data integrity tests
• canonical LDAP schema validation tests
• telemetry assertion tests

15.4 Acceptance rule

A migration path is acceptable only if:

• profile-conformant apps keep working
• required claims remain stable
• unsupported cases fail in expected ways
• canonical identity data remains valid
• telemetry remains available where expected

---

16. Security Requirements

16.1 General

Keycape shall prioritize narrowness and correctness over feature breadth.

16.2 Mandatory controls

• strict redirect URI validation
• strict issuer consistency
• strict client identity validation
• no handwritten cryptography
• no handwritten password hashing implementation
• use of established protocol and crypto libraries
• minimal and explicit scope handling
• explicit token lifetime policy
• auditability of authentication decisions

16.3 Safety through profile discipline

Feature restriction is a security control.

Any expansion of the profile must be reviewed for:

• protocol complexity increase
• migration complexity increase
• test burden increase
• security surface increase

---

17. Configuration Principles

Keycape configuration shall be declarative.

17.1 Configuration sources

Configuration may include:

• profile definition version
• client definitions
• backend connection settings
• LDAP schema rules
• privacyIDEA integration settings
• telemetry destinations
• environment-specific overrides

17.2 Configuration constraints

Configuration should be:

• version-controlled
• environment-promotable
• statically validated where possible
• linked to profile version
• convertible into migration/export artifacts

---

18. Operational Modes

18.1 Dev mode

Optimized for rapid local iteration and deterministic tests.

May use:

• local LLDAP
• local Authelia
• simplified privacyIDEA integration stubs or real integration depending on environment policy

18.2 Slim production mode

A real production mode for environments whose needs fit inside the profile.

May use:

• LLDAP
• Authelia
• privacyIDEA
• Keycape

18.3 Expanded production mode

Used when federation, admin breadth, or IAM complexity exceeds the profile’s lightweight implementation strategy.

May use:

• Keycloak
• full LDAP
• privacyIDEA

---

19. Non-Goals

Keycape shall not pursue these goals in v0.1:

• broad Keycloak API parity
• general-purpose enterprise IAM platform status
• support for arbitrary legacy LDAP consumers through Keycloak
• plugin ecosystem parity
• realm-level multi-tenancy complexity beyond explicit profile need
• bespoke app-specific exceptions outside the profile

---

20. Conformance

20.1 Keycape conformance

Keycape conforms if it:

• implements the required profile endpoints and behaviors
• produces correct claims and errors
• passes all lightweight profile tests
• emits required telemetry
• supports migration/export flows required by the specification

20.2 Expanded-mode conformance

A Keycloak-based deployment conforms if it:

• passes the same application-facing profile tests
• honors the same claim model and client behavior
• supports defined migration scenarios

20.3 Fixture conformance

Canonical fixtures conform if they pass canonical model and LDAP schema validation.

---

21. Initial Deliverables Derived from This Specification

The following implementation artifacts should be created next:

21.1 NetKingdom IAM Profile

A formal canonical profile document now exists in net-kingdom as canon/standards/iam-profile_v0.2.md, with endpoint-by-endpoint detail, tenant/principal/assurance claims, and executable conformance checks.

21.2 Canonical identity model schema

Machine-readable schema for canonical fixtures.

21.3 Canonical LDAP schema and validator spec

Formal validator rules and error codes.

21.4 Keycape component design

Internal architecture, adapters, translation logic, and runtime behavior.

21.5 Replacement test matrix

End-to-end scenarios and expected outcomes.

21.6 Migration design

LLDAP → full LDAP and lightweight IAM → Keycloak data/config mapping.

xxx