docs(auth): add documentation on authentication and authorization - #1068
Draft
aparajon wants to merge 19 commits into
Draft
docs(auth): add documentation on authentication and authorization#1068aparajon wants to merge 19 commits into
aparajon wants to merge 19 commits into
Conversation
…orization configuration.md documents the YAML but nothing explained the model: which surfaces exist and what authenticates each, why plan is a write and reads are deployment-wide, how the three authenticators differ, how per-database operator scoping decides in two phases, and what to monitor. Add docs/auth.md for that, framed as an adoption path from auth-off through scoped per-team grants, with an end-to-end decision-flow diagram. Add a PR comment workflow timeline to architecture.md and cross-link the new doc from the configuration reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds an adoption-oriented guide explaining SchemaBot’s authentication and authorization model, and links to it from existing documentation so adopters can move from “auth off” to a locked-down deployment with clear tradeoffs and operational guidance.
Changes:
- Add a new
docs/auth.mdguide describing trust surfaces, the two-tier API model, decision flow, and observability signals. - Link the configuration reference’s Authentication section to the new guide for model/intent context beyond YAML fields.
- Extend
docs/architecture.mdwith a timeline-style sequence diagram for the PR comment workflow.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/configuration.md | Adds a pointer from the YAML reference to the new auth model guide. |
| docs/auth.md | New end-to-end doc covering authn/authz concepts, adoption steps, and monitoring. |
| docs/architecture.md | Adds a timeline diagram of the PR comment workflow (and surfaces an API path inconsistency to fix). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Give services calling SchemaBot as themselves a dedicated section covering both authenticators (client-credentials tokens under oidc, the read-only gateway lane under forward_auth), and add a config or on-the-wire example to every section so each concept lands next to the YAML and headers that implement it. Trim the PR-workflow timeline diagram to the apply command and correct the API route prefix in the architecture overview. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The TOC generator collapsed whitespace runs into a single hyphen, but GitHub hyphenates each space, so a heading like "User Layer (CLI / PR Comments / API)" got a TOC link that pointed nowhere. Slug each whitespace character individually and regenerate the affected TOCs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… example Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ground the section in what a service consumer actually builds on: the four read endpoints (databases, pull, history, progress) and the periodic-sync call pattern. Add the end-to-end identity diagram (no tokens anywhere; the mesh certificate is the identity) and the onboarding tip that deny-by-default makes concrete: the denial log records the caller identity that arrived, so one pre-allowlist call pins the exact SPIFFE ID to grant. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Give service consumers a dedicated doc for the four core read endpoints (databases, pull, history, progress) with obfuscated request/response examples verified against pkg/apitypes. The auth doc's service-calling section and the architecture doc's User Layer section link to it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This reverts commit 077ff5f, splitting the API consumer guide into a follow-up PR (branch armand/api-consumer-doc). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
aparajon
changed the title
Moving to an authenticated API is driven by integrating into real company infrastructure (networking boundaries, security requirements that expect caller identity), not by spotting unauthenticated writes in logs. Keep the logging point as an audit trail, not as the signal to move up. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Name the two front doors (GitHub PR workflow vs CLI/API) up front and state that GitHub is optional: a CLI-only deployment's entire auth story is the API authenticator, and the GitHub sections do not apply. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Compress the model into the rules an agent operating against a deployment needs: authenticate as a service caller with its own identity, the read tier is the complete surface, a 403 is answered by an operator grant rather than workarounds, onboarding pins identity from the denial log, and schema changes go through the PR workflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Split the agent identity rule on the line that matters: a standing agent authenticates as a service caller with its own identity, while an agent working under a person's supervision may use the CLI with that person's credentials for reads. Writes stay in the person's own hands or the PR workflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Direct write access is use-at-your-own-risk. Name the concrete posture for step 4: production stays out of operator_environments, so direct production access is held only by the platform team's admin write_groups and everyone else uses the PR workflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Step 4 is a spectrum, not a rule: a single-developer setup keeps CLI write access everywhere, a team keeps production on the PR workflow, and at the strict end an organization leaves production out of operator_environments so direct access stays with the platform team's admin groups. Direct write access is use-at-your-own-risk either way. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The review gate is optional, so a solo developer still gets plans, checks, and history from the PR workflow without a second person. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add the hybrid rhythm (CLI for fast local/staging iteration, GitHub as the GitOps source of record) and land the spectrum on the mature best practice: production leaves operator_environments, every production change is a PR, and platform-team admin access remains as break-glass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Service callers carry no user identity in the first place, so the rule warned against something the model already rules out. The section now leads with the supervised-CLI-reads guidance. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Clarified guidelines for agent CLI usage regarding reads and writes, emphasizing the need for supervision and guardrails for write operations.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/auth.md, an adoption-oriented guide to authentication and authorization, linked from the configuration reference. Auth is often the first real barrier an adopter hits: a fresh server starts with API authentication off, and the path from there to a locked-down deployment was undocumented outside the YAML reference.The doc leads with a graduated adoption path (auth off → authenticate the API → narrow reads → per-database operator grants → choose how open production is, a workflow-based spectrum from single-developer setups to GitHub-only production). Behind the path it explains the model, with a config or on-the-wire example in every section: the two front doors (GitHub vs CLI/API, GitHub optional), the four trust surfaces, the two-tier API model, the end-to-end decision flow including the two-phase scoped-write decision, the three authenticators, calling SchemaBot as a service (read-only by design), fail-closed principles, the decision metrics, and a closing 💡 section for AI agents.
Also:
CLI / PR) were getting dead single-hyphen anchors; the generator now hyphenates each space the way GitHub does, and affected TOCs are regenerated.Opened by Claude (Fable 5).