generated from coulomb/repo-seed
134 lines
5.3 KiB
Markdown
134 lines
5.3 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;
|
||
canonical spec: `canon/standards/iam-profile_v0.2.md`)
|
||
- 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)
|
||
- User Engine Boundary Contract: source-of-truth, membership,
|
||
application-onboarding, projection, authorization, and audit contracts for
|
||
`user-engine` integration (`canon/standards/user-engine-boundary-contract_v0.1.md`)
|
||
- Security bootstrapping: credential management, SOPS/age integration,
|
||
platform-root custody, OpenBao runtime secret authority
|
||
- 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
|
||
- Designing or using the guided security bootstrap experience
|
||
- 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
|
||
|
||
- `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 — canonical v0.2 defines discovery, PKCE, token, JWKS, tenant, principal-type, assurance, and flex-auth claim inputs.
|
||
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: `docs/platform-root-custody.md`, `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
|
||
- User-domain boundary contract:
|
||
`canon/standards/user-engine-boundary-contract_v0.1.md`
|
||
- Bootstrap/custody entry points:
|
||
`docs/platform-root-custody.md`,
|
||
`docs/security-bootstrap-use-cases.md`,
|
||
`workplans/NET-WP-0015-platform-root-custody-and-openbao-identity-bootstrap.md`,
|
||
and `workplans/NET-WP-0016-guided-security-bootstrap-experience.md`
|