tegwick
30fa8570aa
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06e87-e039-7ed2-b85c-20ad37f8a21b
110 lines
6.9 KiB
Markdown
110 lines
6.9 KiB
Markdown
# SCOPE
|
|
|
|
Reviewed 2026-09-05 against source revision `b989de4`.
|
|
|
|
## Purpose and boundary
|
|
|
|
KeyCape is Go identity **Tooling** for NetKingdom's lightweight IAM deployment.
|
|
It runs its own OIDC-style issuer, uses Authelia for upstream browser
|
|
authentication, reads identities from LLDAP, and delegates factor checks to
|
|
privacyIDEA. It also provides caller authentication commands, directory snapshot
|
|
validation, and migration artifact generators.
|
|
|
|
It issues identity, role, scope and assurance claims. Resource authorization
|
|
belongs to access-engine and consuming services; secret custody and OpenBao
|
|
policy/token enforcement belong to their platform owners. The implemented subset
|
|
supports NetKingdom integrations, but complete profile conformance and drop-in
|
|
Keycloak interchangeability are not established.
|
|
|
|
## Implemented capabilities
|
|
|
|
| Surface | What the current source provides |
|
|
| --- | --- |
|
|
| Issuer HTTP API | Discovery, `/authorize` and its callback/registration-return routes, `/token`, `/jwks`, `/userinfo`, local `/logout`, and `/healthz`. |
|
|
| Human authentication | Authorization code with S256 PKCE, exact registered redirects, scope allow-lists, Authelia login, privacyIDEA MFA challenges, client-specific assurance requirements, browser session reuse, step-up/fresh-login handling, and configured registration/enrollment handoffs. |
|
|
| Service authentication | Static confidential `client_credentials` clients authenticated with form-encoded `client_secret_basic`; configured subject, tenant, roles, scopes and per-client token lifetime. Secrets are resolved from environment references at startup. |
|
|
| Tokens and identity | Locally signed RS256 JWTs; configurable access-token resource audience while ID tokens retain the client audience; human/service principal types, tenant, groups, roles, scope and assurance claims. UserInfo resolves canonical directory subjects and filters profile/email/groups by scope. |
|
|
| Caller commands | `keycape login` for public-client browser PKCE login and `keycape service-token` for service exchange. HTTPS discovery/JWKS verification and private JSON token-file delivery outside Git; no token output on stdout. |
|
|
| Validation and migration | Canonical snapshot checks; LLDAP user/group/membership export; basic Keycloak realm JSON; LDIF generation for OpenLDAP, 389 Directory Server and AD targets. These generate artifacts rather than execute a complete migration. |
|
|
| Diagnostics and packaging | Structured authentication/enforcement/migration events, a process health response, Go build/test/vet targets, a container containing the KeyCape binary, and development/CI scaffolding. |
|
|
|
|
## Material limits
|
|
|
|
- Client registrations, service secrets and the signing key are loaded at startup.
|
|
Login, authorization and handoff state are process-local. There is no shared
|
|
session store, general refresh-token flow, token introspection/revocation API,
|
|
or automatic signing-key/client-secret rotation service. Logout clears the
|
|
local KeyCape session, not every upstream or downstream session/token.
|
|
- The optional tenant-engine `tenant_roles` adapter and handler support exist,
|
|
but the server entry point does not configure them. That claim is not an
|
|
enabled capability of the stock executable.
|
|
- The Keycloak CLI exports users/groups through the basic transformer and has
|
|
no client-list input. Library-level client mapping does not preserve the full
|
|
current service-identity, audience, tenant/role, MFA and lifetime contract.
|
|
Password and MFA credential migration is not supplied.
|
|
- Snapshot validation is a limited Go rule set, not full machine-readable schema
|
|
enforcement. The canonical YAML model and discovery metadata lag newer runtime
|
|
capabilities. Protocol hardening gaps remain; see the assessment below.
|
|
- Tests cover local handlers, adapters, transformations and CLI protocol behavior.
|
|
They do not establish complete replacement against a running Keycloak/full-LDAP
|
|
stack. The Scenario B/C shell harnesses are incomplete.
|
|
- The server listens on HTTP; HTTPS termination is deployment-owned.
|
|
`/healthz` reports process status without probing dependencies. Development
|
|
Compose needs configuration/key material absent from the checkout. Production
|
|
deployment and custody are external; a source implementation or example client
|
|
fragment does not prove live registration or consumer cutover.
|
|
- Approval-client provisioning, coordinated Qonto rotation, native consumer
|
|
handoffs and notification receipt closure remain open in KEY-WP-0009/0013/0014.
|
|
|
|
## Deliberate exclusions
|
|
|
|
General-purpose IAM, dynamic client registration, implicit/password grants,
|
|
wildcard redirects, arbitrary identity brokering, resource authorization policy,
|
|
OpenBao credential custody, and Keycloak operations are outside this repository's
|
|
ownership. Registration/enrollment handoffs do not implement user provisioning
|
|
or factor enrollment themselves.
|
|
|
|
## Entry points and verification
|
|
|
|
Run the issuer with `keycape --config PATH`; `keycape server` and
|
|
`keycape migrate` are not implemented subcommands. Caller commands are
|
|
`keycape login` and `keycape service-token`.
|
|
|
|
Separate binaries under `src/cmd/` are `validator`, `lldap-export`,
|
|
`keycape-to-keycloak`, and `lldap-to-ldap`. `make -C src build` places binaries in
|
|
root `bin/`; the container packages only `keycape`. Tests live under `src/tests/`
|
|
and alongside packages in `src/internal/`.
|
|
|
|
`make test`, `make lint` (Go vet), `make build`, and `make contract-test` are the
|
|
root checks. The capability-contract check requires the sibling NetKingdom
|
|
validator. These checks passed for the reviewed revision in the preceding
|
|
implementation session; the scope assessment is a source/documentation review.
|
|
|
|
Use this repo for its bounded issuer, caller JWT acquisition, identity adapters
|
|
and migration preparation. Consult [INTENT.md](INTENT.md) for the architectural
|
|
target, [native authentication](docs/native-authentication.md) for caller
|
|
constraints, and the [scope/intent assessment](history/2026-09-05-011726-scope-intent-assessment.md)
|
|
for evidence, priorities and remaining gaps.
|
|
|
|
## Provided capabilities
|
|
|
|
```capability
|
|
type: security
|
|
title: Bounded OIDC and service-token issuance
|
|
description: Implements static-client browser PKCE and client-credentials authentication with RS256 identity claims through Authelia, LLDAP and privacyIDEA; complete Keycloak interchangeability remains unproven.
|
|
keywords: [oidc, pkce, authentication, iam, sso, mfa, identity, service-token]
|
|
```
|
|
|
|
```capability
|
|
type: security
|
|
title: Verified caller JWT acquisition
|
|
description: Provides native browser login and service-token exchange commands with HTTPS discovery, JWKS verification and private token-file delivery.
|
|
keywords: [oidc, pkce, jwt, cli, authentication, jwks]
|
|
```
|
|
|
|
```capability
|
|
type: security
|
|
title: Directory validation and migration artifact generation
|
|
description: Checks canonical snapshots and produces LLDAP exports, basic Keycloak realm JSON and target-specific LDIF; does not perform or prove a complete live migration.
|
|
keywords: [migration, identity, lldap, keycloak, ldif, validation]
|
|
```
|