generated from coulomb/repo-seed
tegwick
a626dd5d4e
Some checks failed
Build and Publish Container Image / build-and-push (push) Has been cancelled
116 lines
4.2 KiB
Markdown
116 lines
4.2 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
Lightweight IAM implementation of the NetKingdom IAM Profile — orchestrates Authelia, LLDAP, and privacyIDEA to provide OIDC/PKCE authentication as a drop-in Keycloak alternative.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
NetKingdom applications target the "NetKingdom IAM Profile" — a versioned OIDC/PKCE contract. KeyCape implements that profile in lightweight mode (Authelia + LLDAP + privacyIDEA) with intentional constraints: no implicit flow, no wildcard redirects, no dynamic client registration. The same profile is implemented in expanded mode by Keycloak, so applications can migrate between modes without code changes.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- OIDC profile endpoints (discovery, authorization, token, JWKS, userinfo) per NetKingdom IAM Profile
|
|
- Canonical identity model: users, groups, clients, MFA
|
|
- Claim normalization across Authelia/LLDAP/privacyIDEA backend quirks
|
|
- Profile enforcement with structured error taxonomy (no silent emulation of unsupported features)
|
|
- Telemetry for unsupported-feature requests
|
|
- Migration tooling: LLDAP export, Keycloak import, LDIF generation
|
|
- LDAP schema validation
|
|
- Full acceptance test suite (profile baseline, migration scenarios, negative tests)
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- General-purpose IAM (profile-specific only; no out-of-profile extensions)
|
|
- Dynamic client registration
|
|
- Implicit flow
|
|
- Wildcard redirect URIs
|
|
- Identity brokering beyond OIDC
|
|
- Keycloak operations (KeyCape is the lightweight alternative, not a Keycloak wrapper)
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- Deploying NetKingdom IAM in lightweight mode (no Keycloak license/resources needed)
|
|
- Applications need OIDC authentication with MFA in a constrained environment
|
|
- Migrating from lightweight (KeyCape) to expanded (Keycloak) mode
|
|
- Validating LDAP schema or generating migration artifacts
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- Expanded-mode Keycloak is already running (applications use the same profile; no code changes needed)
|
|
- Need out-of-profile IAM features (dynamic client registration, implicit flow, etc.)
|
|
- Non-NetKingdom OIDC deployments
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: stable (v0.1 complete)
|
|
- Implementation: complete — all 23 workplan tasks implemented and tested
|
|
- Stability: high — profile-constrained; no silent failures; acceptance tests passing
|
|
- Usage: internal NetKingdom stack; replaces Keycloak in lightweight deployments
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: Authelia (OIDC provider/sessions), LLDAP (identity directory), privacyIDEA (MFA)
|
|
- Downstream consumers: all NetKingdom applications; net-kingdom (parent domain)
|
|
- Often used with: net-kingdom (SSO/MFA workplan), railiance (deployed on Railiance infrastructure)
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: NetKingdom IAM Profile, lightweight mode, expanded mode, profile enforcement, canonical model
|
|
- Also known as: "KeyCape", "key-cape"
|
|
- Potentially confusing terms: "lightweight mode" = KeyCape stack; "expanded mode" = Keycloak stack; both implement the same OIDC profile
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `net-kingdom` — parent platform domain; KeyCape is the lightweight IAM implementation of its IAM Profile
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: security
|
|
title: OIDC/PKCE authentication (lightweight mode)
|
|
description: Provides OIDC/PKCE endpoints conforming to the NetKingdom IAM Profile via Authelia + LLDAP + privacyIDEA — a drop-in Keycloak alternative for constrained environments.
|
|
keywords: [oidc, pkce, authentication, iam, sso, authelia, lldap, mfa, identity]
|
|
```
|
|
|
|
```capability
|
|
type: security
|
|
title: Identity migration tooling
|
|
description: Migrate identities between lightweight (KeyCape) and expanded (Keycloak) IAM modes — LLDAP export, Keycloak import, LDIF generation.
|
|
keywords: [migration, identity, lldap, keycloak, ldif, iam]
|
|
```
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `wiki/KeyCapeSpecification_v0.1.md` (architecture and design intent)
|
|
- Key files / directories: `wiki/KeyCapeSpecificationPack_v0.1.md` (normative spec), `src/cmd/` (binary entrypoints), `src/internal/` (implementation), `tests/` (acceptance suite)
|
|
- Entry points: `keycape server` binary; `keycape migrate` for migration tooling
|