docs: admin connector, admin debugging, and accuracy fixes - #246
Conversation
a541188 to
c88d12a
Compare
| @@ -0,0 +1,200 @@ | |||
| # Admin Connector | |||
|
|
|||
| The admin connector is a standalone binary (`cmd/admin-connector`) that sits between a frontend application and the Kerberos admin API. It acts as a reverse proxy that enforces admin session authentication before forwarding requests to the admin API server. | |||
There was a problem hiding this comment.
@copilot the admin connector forwards to OTHER services, after validating the admin session attached to a request, it does not proxy the admin API server
There was a problem hiding this comment.
Fixed in the latest commit. The doc now correctly describes the connector as an authenticating reverse proxy that validates the admin session cookie and forwards to any configured TARGET service, with no mention of the admin API as the upstream.
|
|
||
| ## Purpose | ||
|
|
||
| The admin connector solves a common deployment problem: browsers cannot safely forward HTTP-only session cookies set by Kerberos to a backend API that is hosted on a different origin. The connector is deployed at an origin the browser trusts, validates that the incoming request carries a valid admin session cookie, and then proxies the request to the upstream admin API. |
There was a problem hiding this comment.
@copilot remove "admin API", just say "target", that's the canonical term for what the admin connector forwards to. Ensure the rest of the doc is aligned on the term "target".
There was a problem hiding this comment.
Done in the latest commit — all "admin API" references replaced with "target" throughout the doc.
|
|
||
| The connector: | ||
|
|
||
| 1. Reads the `krb-admin-session` cookie from the incoming request. |
There was a problem hiding this comment.
@copilot what is that cookie name?... Just say "session cookie" is enough.
There was a problem hiding this comment.
Done — all occurrences now just say "session cookie" without naming it.
|
|
||
| All fields except `persistence` are optional. | ||
|
|
||
| #### `persistence` (required) |
There was a problem hiding this comment.
@copilot do not bother documenting specific configuration fields, this will surely change at a rapid pace. Just MENTION which configuration options you have on a high level: server TLS, target TLS, persistence (SQLITE/PG)...
There was a problem hiding this comment.
Done in c0912f0 — the config section now just lists the four high-level options (persistence, tls, targetTls, origins) as a bullet list with no field-level detail.
3792d29 to
ad50b44
Compare
Co-authored-by: maansaake <15028979+maansaake@users.noreply.github.com>
…ot the admin API Co-authored-by: maansaake <15028979+maansaake@users.noreply.github.com>
Co-authored-by: maansaake <15028979+maansaake@users.noreply.github.com>
Co-authored-by: maansaake <15028979+maansaake@users.noreply.github.com>
ad50b44 to
462bbea
Compare
Adds missing documentation for the admin connector binary and the debug API, links the organisations doc from authentication, and corrects several factual errors in existing docs.
New documents
admin-connector.md— purpose, config file schema (persistence,tls,targetTls,origins), all env vars, emitted OTel metrics, minimal and production examplesadmin-debugging.md— debugger mechanics,debuggerpermission requirement, session lifecycle (start / extend / stop / delete), full API reference, data models (DebugSession,DebugSessionCall,FlowTransition), step-by-step workflowAccuracy fixes
authentication.mdsessioncookie, not anX-Krb-Sessionheader as previously statedorganizations.mdfrom the Basic Auth sectionrouting.md— "OTEL" renamed to "Observability" to match the actual component nameREADME.md— new docs added, list kept alphabetical