generated from coulomb/repo-seed
119 lines
4.5 KiB
Markdown
119 lines
4.5 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
|
||
|
||
Platform domain for NetKingdom identity and security services — owns the IAM Profile specification, SSO/MFA platform (Keycloak), and bootstrap local-identity infrastructure for Kubernetes deployments.
|
||
|
||
---
|
||
|
||
## Core Idea
|
||
|
||
NetKingdom is a self-optimizing security platform for Kubernetes-based IT infrastructure. This repo owns identity at the platform level: the NetKingdom IAM Profile specification (the versioned OIDC/PKCE contract all applications target), the enterprise Keycloak-based SSO/MFA platform, and a lightweight file-based local-identity service for bootstrap environments before the full cluster is available.
|
||
|
||
---
|
||
|
||
## In Scope
|
||
|
||
- NetKingdom IAM Profile specification (versioned OIDC/PKCE contract)
|
||
- SSO/MFA Platform: Keycloak with LDAP/Entra federation, enterprise identity (NK-WP-0001)
|
||
- Local Identity: file-based user store + minimal OIDC server for bootstrap phase (NK-WP-0002)
|
||
- Security bootstrapping: credential management, SOPS/age integration, KeePassXC/Vault progression
|
||
- Architectural decisions (DECISIONS.md): identity source, secrets, GitOps, bootstrap user store
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
- Kubernetes runtime concerns → railiance-cluster
|
||
- Platform services (PostgreSQL, storage, caches) → railiance-platform
|
||
- Application deployments → railiance-apps
|
||
- KeyCape implementation details → key-cape
|
||
|
||
---
|
||
|
||
## Relevant When
|
||
|
||
- Setting up identity for a NetKingdom/Railiance deployment
|
||
- Applications need OIDC authentication; deciding between lightweight (KeyCape) and expanded (Keycloak) modes
|
||
- Bootstrap scenario: cluster not yet available, need minimal OIDC for dev/test/sandbox
|
||
- Reviewing IAM Profile specification or architectural identity decisions
|
||
|
||
---
|
||
|
||
## Not Relevant When
|
||
|
||
- Infrastructure provisioning (use railiance-infra)
|
||
- Platform services configuration (use railiance-platform)
|
||
- Application-level auth code (use the IAM Profile spec as reference only)
|
||
|
||
---
|
||
|
||
## Current State
|
||
|
||
- Status: active (design phase complete, implementation ongoing)
|
||
- Implementation: emerging — NK-WP-0001 (SSO/MFA) and NK-WP-0002 (local identity) both in active development
|
||
- Stability: evolving
|
||
- Usage: foundational authentication layer for all NetKingdom deployments
|
||
|
||
---
|
||
|
||
## How It Fits
|
||
|
||
- Upstream dependencies: KeyCape (lightweight IAM implementation), Authelia, Keycloak, LLDAP, privacyIDEA
|
||
- Downstream consumers: railiance (all Railiance deployments), applications targeting the NetKingdom IAM Profile
|
||
- Often used with: key-cape (lightweight mode), railiance-platform (identity services integration), railiance-cluster (deployed on Kubernetes)
|
||
|
||
---
|
||
|
||
## Terminology
|
||
|
||
- Preferred terms: NetKingdom IAM Profile, local identity, SSO/MFA platform, bootstrap, lightweight mode, expanded mode
|
||
- Also known as: "net-kingdom"
|
||
- Potentially confusing terms: "local identity" = file-based bootstrap store (not a full LDAP); "SSO/MFA platform" = production Keycloak deployment
|
||
|
||
---
|
||
|
||
## Related / Overlapping Repositories
|
||
|
||
- `key-cape` — lightweight IAM implementation (KeyCape orchestrates Authelia+LLDAP+privacyIDEA)
|
||
- `railiance-platform` — net-kingdom identity services integrate at the platform services layer
|
||
|
||
---
|
||
|
||
## Provided Capabilities
|
||
|
||
```capability
|
||
type: security
|
||
title: NetKingdom IAM Profile specification
|
||
description: Versioned OIDC/PKCE contract that all NetKingdom applications target — defines discovery, authorization, token, JWKS, and userinfo endpoints plus claim normalization.
|
||
keywords: [iam, oidc, pkce, profile, specification, identity, authentication]
|
||
```
|
||
|
||
```capability
|
||
type: security
|
||
title: SSO/MFA platform (Keycloak)
|
||
description: Enterprise-grade Keycloak-based SSO with LDAP/Entra federation, MFA, and full OIDC/PKCE support for production deployments.
|
||
keywords: [sso, mfa, keycloak, ldap, entra, federation, oidc, enterprise]
|
||
```
|
||
|
||
```capability
|
||
type: security
|
||
title: Bootstrap local identity service
|
||
description: Minimal file-based OIDC server for environments where the full cluster is not yet available — covers dev, test, and sandbox bootstrapping scenarios.
|
||
keywords: [bootstrap, local-identity, oidc, minimal, dev, sandbox]
|
||
```
|
||
|
||
---
|
||
|
||
## Getting Oriented
|
||
|
||
- Start with: `wiki/` (specifications and decisions), `DECISIONS.md` (key architectural choices D1–D5)
|
||
- Key files / directories: `sso-mfa/` (NK-WP-0001 active workplan), `local-identity/` (NK-WP-0002), `workplans/`
|
||
- Entry points: `workplans/NK-WP-0001-sso-mfa-platform.md` and `NK-WP-0002-local-identity.md` for current work
|