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

key-cape — lightweight IAM implementation (KeyCape orchestrates Authelia+LLDAP+privacyIDEA)
railiance-platform — net-kingdom identity services integrate at the platform services layer

Provided Capabilities

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]

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]

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
User-engine integration assessment (intent/scope fit, gaps, and recommendations): docs/user-engine-netkingdom-integration-assessment.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

5.4 KiB Raw Blame History Unescape Escape